001/*
002 *   Licensed to the Apache Software Foundation (ASF) under one
003 *   or more contributor license agreements.  See the NOTICE file
004 *   distributed with this work for additional information
005 *   regarding copyright ownership.  The ASF licenses this file
006 *   to you under the Apache License, Version 2.0 (the
007 *   "License"); you may not use this file except in compliance
008 *   with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *   Unless required by applicable law or agreed to in writing,
013 *   software distributed under the License is distributed on an
014 *   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *   KIND, either express or implied.  See the License for the
016 *   specific language governing permissions and limitations
017 *   under the License.
018 *
019 */
020package org.apache.directory.ldap.client.template;
021
022
023import org.apache.directory.api.ldap.model.entry.Attribute;
024import org.apache.directory.api.ldap.model.entry.Entry;
025import org.apache.directory.api.ldap.model.entry.Value;
026import org.apache.directory.api.ldap.model.message.AddRequest;
027import org.apache.directory.api.ldap.model.message.DeleteRequest;
028import org.apache.directory.api.ldap.model.message.ModifyRequest;
029import org.apache.directory.api.ldap.model.message.SearchRequest;
030import org.apache.directory.api.ldap.model.message.SearchScope;
031import org.apache.directory.api.ldap.model.name.Dn;
032import org.apache.directory.ldap.client.api.search.FilterBuilder;
033
034
035/**
036 * A factory for creating {@link org.apache.directory.api.ldap.model} objects.
037 *
038 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
039 */
040public interface ModelFactory
041{
042    /**
043     * Returns a new <code>AddRequest</code> for the <code>entry</code>.
044     *
045     * @param entry The Entry to add
046     * @return The resulting AddRequest
047     */
048    AddRequest newAddRequest( Entry entry );
049
050
051    /**
052     * Returns a new Attribute for with the provided <code>name</code> and
053     * a null value.  This is useful for clearing out an Attribute with a
054     * ModifyRequest, replace function.
055     *
056     * @param name The attribute's name
057     * @return The resulting Attribute
058     */
059    Attribute newAttribute( String name );
060
061
062    /**
063     * Returns a new Attribute for with the provided <code>name</code> and
064     * <code>value(s)</code>.
065     *
066     * @param name The attribute's name
067     * @param values The attribute's values
068     * @return The resulting Attribute
069     */
070    Attribute newAttribute( String name, byte[]... values );
071
072
073    /**
074     * Returns a new Attribute for with the provided <code>name</code> and
075     * <code>value(s)</code>.
076     *
077     * @param name The attribute's name
078     * @param values The attribute's values
079     * @return The resulting Attribute
080     */
081    Attribute newAttribute( String name, String... values );
082
083
084    /**
085     * Returns a new Attribute for with the provided <code>name</code> and
086     * <code>value(s)</code>.
087     *
088     * @param name The attribute's name
089     * @param values The attribute's values
090     * @return The resulting Attribute
091     */
092    Attribute newAttribute( String name, Value<?>... values );
093
094
095    /**
096     * Returns a new <code>DeleteRequest</code> for the <code>dn</code>.
097     *
098     * @param dn The Dn for the Entry to delete
099     * @return The resulting DeleteRequest
100     */
101    DeleteRequest newDeleteRequest( Dn dn );
102
103
104    /**
105     * Returns a <code>Dn</code> that represents <code>dn</code>.
106     *
107     * @param dn The Entry's Dn
108     * @return The resulting Dn
109     */
110    Dn newDn( String dn );
111
112
113    /**
114     * Returns a <code>Entry</code> with the specified <code>dn</code>.
115     *
116     * @param dn The Entry's Dn
117     * @return The resulting Entry
118     */
119    Entry newEntry( String dn );
120
121
122    /**
123     * Returns a <code>Entry</code> with the specified <code>dn</code>.
124     *
125     * @param dn The Entry's Dn
126     * @return The resulting Entry
127     */
128    Entry newEntry( Dn dn );
129
130
131    /**
132     * Returns a new <code>ModifyRequest</code> for the <code>dn</code>.
133     *
134     * @param dn  The Dn of the entry to modify
135     * @return The resulting ModifyRequest
136     */
137    ModifyRequest newModifyRequest( String dn );
138
139
140    /**
141     * Returns a new <code>ModifyRequest</code> for the <code>dn</code>.
142     *
143     * @param dn The DN of the entry to modify
144     * @return The resulting ModifyRequest
145     */
146    ModifyRequest newModifyRequest( Dn dn );
147
148
149    /**
150     * Returns a new <code>SearchRequest</code> over <code>baseDn</code> in
151     * <code>scope</code> matching <code>filter</code> returning 
152     * all normal attributes for each matching entry.
153     *
154     * @param baseDn The base DN from which to start the search
155     * @param filter The filter selecting the entries
156     * @param scope The scope to look from
157     * @return The resulting SearchRequest
158     */
159    SearchRequest newSearchRequest( String baseDn, FilterBuilder filter,
160        SearchScope scope );
161
162
163    /**
164     * Returns a new <code>SearchRequest</code> over <code>baseDn</code> in
165     * <code>scope</code> matching <code>filter</code> returning 
166     * all normal attributes for each matching entry.
167     *
168     * @param baseDn The base DN from which to start the search
169     * @param filter The filter selecting the entries
170     * @param scope The scope to look from
171     * @return The resulting SearchRequest
172     */
173    SearchRequest newSearchRequest( String baseDn, String filter,
174        SearchScope scope );
175
176
177    /**
178     * Returns a new <code>SearchRequest</code> over <code>baseDn</code> in
179     * <code>scope</code> matching <code>filter</code> returning 
180     * all normal attributes for each matching entry.
181     *
182     * @param baseDn The base DN from which to start the search
183     * @param filter The filter selecting the entries
184     * @param scope The scope to look from
185     * @return The resulting SearchRequest
186     */
187    SearchRequest newSearchRequest( Dn baseDn, String filter,
188        SearchScope scope );
189
190
191    /**
192     * Returns a new <code>SearchRequest</code> over <code>baseDn</code> in
193     * <code>scope</code> matching <code>filter</code> returning 
194     * all normal attributes for each matching entry.
195     *
196     * @param baseDn The base DN from which to start the search
197     * @param filter The filter selecting the entries
198     * @param scope The scope to look from
199     * @return The resulting SearchRequest
200     */
201    SearchRequest newSearchRequest( Dn baseDn, FilterBuilder filter,
202        SearchScope scope );
203
204
205    /**
206     * Returns a new <code>SearchRequest</code> over <code>baseDn</code> in
207     * <code>scope</code> matching <code>filter</code> returning 
208     * <code>attributes</code> for each matching entry.
209     *
210     * @param baseDn The base DN from which to start the search
211     * @param filter The filter selecting the entries
212     * @param scope The scope to look from
213     * @param attributes The list of AttributeType to return
214     * @return The resulting SearchRequest
215     */
216    SearchRequest newSearchRequest( String baseDn, String filter,
217        SearchScope scope, String... attributes );
218
219
220    /**
221     * Returns a new <code>SearchRequest</code> over <code>baseDn</code> in
222     * <code>scope</code> matching <code>filter</code> returning 
223     * <code>attributes</code> for each matching entry.
224     *
225     * @param baseDn The base DN from which to start the search
226     * @param filter The filter selecting the entries
227     * @param scope The scope to look from
228     * @param attributes The list of AttributeType to return
229     * @return The resulting SearchRequest
230     */
231    SearchRequest newSearchRequest( String baseDn, FilterBuilder filter,
232        SearchScope scope, String... attributes );
233
234
235    /**
236     * Returns a new <code>SearchRequest</code> over <code>baseDn</code> in
237     * <code>scope</code> matching <code>filter</code> returning 
238     * <code>attributes</code> for each matching entry.
239     *
240     * @param baseDn The base DN from which to start the search
241     * @param filter The filter selecting the entries
242     * @param scope The scope to look from
243     * @param attributes The list of AttributeType to return
244     * @return The resulting SearchRequest
245     */
246    SearchRequest newSearchRequest( Dn baseDn, String filter,
247        SearchScope scope, String... attributes );
248
249
250    /**
251     * Returns a new <code>SearchRequest</code> over <code>baseDn</code> in
252     * <code>scope</code> matching <code>filter</code> returning 
253     * <code>attributes</code> for each matching entry.
254     *
255     * @param baseDn The base DN from which to start the search
256     * @param filter The filter selecting the entries
257     * @param scope The scope to look from
258     * @param attributes The list of AttributeType to return
259     * @return The resulting SearchRequest
260     */
261    SearchRequest newSearchRequest( Dn baseDn, FilterBuilder filter,
262        SearchScope scope, String... attributes );
263}