001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.naming.directory;
019:
020: import javax.naming.Context;
021: import javax.naming.Name;
022: import javax.naming.NamingEnumeration;
023: import javax.naming.NamingException;
024: import javax.naming.directory.ModificationItem;
025: import javax.naming.directory.SearchControls;
026: import javax.naming.directory.SearchResult;
027:
028: /**
029: * This is the main interface to a directory service.
030: * <p>
031: * A <code>DirContext</code> is the interface through which a client interacts
032: * with a particular concrete directory service provider. The API provides
033: * methods for searching, reading and writing attributes of directory entries.
034: * </p>
035: * <p>
036: * The name of a directory entry is taken as relative to the context receiving
037: * the method invocation. Names cannot be null and the empty name has a special
038: * meaning of the context itself.
039: * </p>
040: * <p>
041: * In this interface there are duplicated methods that take either a
042: * <code>String</code> or <code>Name</code> parameter. This is simply a
043: * convenience and the behavior of each method is identical.
044: * </p>
045: * <p>
046: * The semantics of a name in a <code>DirContext</code> is exactly equivalent
047: * to that of a name in a regular naming <code>Context</code>.
048: * </p>
049: *
050: * <em>Attribute storage models</em>
051: * <p>
052: * JNDI supports two logical models of attribute storage:
053: * <ul>
054: * <li>Type A : where an attribute operation on a named object is equivalent to
055: * a lookup in the <code>DirContext</code> on the given name followed by
056: * application of the operation to the resulting empty <code>DirContext</code>.
057: * Think of this as attributes being stored on the object itself.</li>
058: * <li>Type B : where an attribute operation on a named object is equivalent to
059: * a lookup on that name in the <em>parent</em> <code>DirContext</code>
060: * followed by application of the operation on the parent
061: * <code>DirContext</code> providing the name as an argument. Think of this as
062: * the attributes being stored in the parent context.
063: * <p>
064: * In this model objects that are not <code>DirContext</code> can have
065: * attributes, provided their parents are <code>DirContext</code>.</li>
066: * </ul>
067: * </p>
068: * <p>
069: * The directory service provider can implement either of these logical models,
070: * and the client is expected to know which model it is dealing with.
071: * </p>
072: *
073: * <em>Attribute Name aliasing</em>
074: * <p>
075: * Directory service providers are free to implement attribute name aliasing. If
076: * the service employs aliasing then the list of attribute names that are
077: * returned as a result of API calls to get a named attribute, or search for a
078: * set of attributes may include attributes whose name was not in the search
079: * list. Implementations should not rely on the preservation of attribute names.
080: * </p>
081: *
082: * <em>Searching and operational attributes</em>
083: * <p>
084: * Some directory service providers support "operational attributes" on objects.
085: * These are attributes that are computed by the provider, or have other special
086: * semantics to the directory service. The directory service defines which
087: * attributes are operational.
088: * </p>
089: * <p>
090: * The API calls for searching for attributes, and those for getting named
091: * attributes using a list of names are defined to interpret the
092: * <code>null</code> argument to match all non-operational attributes.
093: * </p>
094: * <p>
095: * It is therefore possible to get a specific named attribute that is not
096: * returned in a global retrieval of all object attributes.
097: * </p>
098: *
099: * <em>Conditions</em>
100: * <p>
101: * Some APIs require that the name resolves to another <code>DirContext</code>
102: * and not an object. In such cases, if this postcondition is not met then the
103: * method should throw a <code>NotContextException</code>. Other methods can
104: * resolve to be either objects or <code>DirContext</code>.
105: * </p>
106: * <p>
107: * Service providers must not modify collection parameters such as
108: * <code>Attribute</code>, <code>SearchControl</code> or arrays. Similarly,
109: * clients are expected not to modify the collections while the service provider
110: * iterates over such collections -- the service provider should be given
111: * exclusive control of the collection until the method returns.
112: * </p>
113: * <p>
114: * APIs that return collections are safe -- that is, the service provider will
115: * not modify collections that are returned to clients.
116: * </p>
117: *
118: * <em>Exceptions</em>
119: * <p>
120: * Any method may throw a <code>NamingException</code> (or subclass) as
121: * defined by the exception descriptions.
122: * </p>
123: */
124: public interface DirContext extends Context {
125:
126: /**
127: * Constant value indicating the addition of an attribute.
128: * <p>
129: * The new value is added to the existing attributes at that identifier
130: * subject to the following constraints:
131: * <ol>
132: * <li>If the attribute is being created and the value is empty, an
133: * <code>InvalidAttributeValueException</code> is thrown if the attribute
134: * must have a value.</li>
135: * <li>If the attribute already exists with a single value and the schema
136: * requires that the attribute can only have a single value, an
137: * <code>AttributeInUseException</code> is thrown.</li>
138: * <li>If the attribute is being created with a multi-value and the schema
139: * requires that the attribute can only have a single value, an
140: * <code>InvalidAttributeValueException</code> is thrown.</li>
141: * </ol>
142: * </p>
143: */
144: public static final int ADD_ATTRIBUTE = 1;
145:
146: /**
147: * Constant value indicating the replacement of an attribute value.
148: * <p>
149: * If the attribute does not exist then it is created with the given
150: * attribute identifier and attribute. If the value contravenes the schema,
151: * an <code>
152: * InvalidAttributeValueException</code> is thrown.
153: * </p>
154: * <p>
155: * If the attribute exists then all of its values are replaced by the given
156: * values. If the attribute is defined to take a single value and the new
157: * value is a multi-value then an
158: * <code>InvalidAttributeValueException</code> is thrown. If no value is
159: * given then all of the values are removed from the attribute.
160: * </p>
161: * <p>
162: * If an attribute is defined as requiring at least one value, then removing
163: * values results in the removal of the attribute itself.
164: * </p>
165: */
166: public static final int REPLACE_ATTRIBUTE = 2;
167:
168: /**
169: * Constant field indicating the removal of an attribute.
170: * <p>
171: * If the attribute exists then the resulting values of the attribute is the
172: * set of values given by removing all values in the given set from the
173: * existing attribute set.
174: * </p>
175: * <p>
176: * If the given set of attributes is <code>null</code> that should be
177: * interpreted as a request to remove all values from the existing attribute
178: * set.
179: * </p>
180: * <p>
181: * If the attribute does not exist, or a value in the given set does not
182: * appear in the existing attribute set then the service provider is free to
183: * either ignore the fact it does not exist, or throw a
184: * <code>NamingException</code>.
185: * </p>
186: */
187: public static final int REMOVE_ATTRIBUTE = 3;
188:
189: /**
190: * Binds a <code>Name</code> to an <code>Object</code> in this directory
191: * to produce a binding.
192: *
193: * <p>
194: * This binding can have attributes, which are specified by the
195: * <code>attributes</code> parameter if it is non-null. If the
196: * <code>attributes</code> parameter is null and <code>obj</code> is a
197: * <code>DirContext</code> with attributes, the binding will have the
198: * attributes of <code>obj</code>.
199: * </p>
200: * <p>
201: * Note that null is not a valid value for <code>name</code>. Neither is
202: * the empty <code>Name</code> because this is reserved to refer to the
203: * context.
204: * </p>
205: * <p>
206: * If <code>name</code> is already bound in this <code>DirContext</code>
207: * this method throws a <code>NameAlreadyBoundException</code>.
208: * </p>
209: * <p>
210: * If there are mandatory attributes for this binding in this
211: * <code>DirContext</code>, and they are not specified, this method
212: * throws an <code>InvalidAttributesException</code>.
213: * </p>
214: * <p>
215: * This method throws any <code>NamingException</code> that occurs.
216: * </p>
217: *
218: * @param name
219: * the name to be bound
220: * @param obj
221: * the object to be bound
222: * @param attributes
223: * the attributes of this binding, can be null
224: * @throws NamingException
225: * If any occurs.
226: */
227: void bind(Name name, Object obj, Attributes attributes)
228: throws NamingException;
229:
230: /**
231: * Binds a string name to an <code>Object</code> in this directory to
232: * produce a binding.
233: *
234: * @param s
235: * the string representative of name to be bound
236: * @param obj
237: * the object to be bound
238: * @param attributes
239: * the attributes of this binding, can be null
240: * @throws NamingException
241: * thrown if any occurs
242: * @see #bind(Name name, Object obj, Attributes attributes)
243: */
244: void bind(String s, Object obj, Attributes attributes)
245: throws NamingException;
246:
247: /**
248: * Creates and binds a new subcontext.
249: * <p>
250: * The new subcontext might not be an immediate subcontext of this one. If
251: * it is not an immediate subcontext, all the intervening subcontexts
252: * specified in <code>name</code> must already exist. If the attributes
253: * parameter is non-null the specified attributes are added to the new
254: * subcontext.
255: * </p>
256: * <p>
257: * Possible exceptions are <code>NameAlreadyBoundException</code> and
258: * <code>InvalidAttributesException</code>.
259: * </p>
260: * <p>
261: * This method throws any <code>NamingException</code> that occurs.
262: * </p>
263: *
264: * @param name
265: * the name bound to the new subcontext
266: * @param attributes
267: * the attributes of the new subcontxt, can be null
268: * @return the new subcontext
269: * @throws NamingException
270: * If any occurs.
271: */
272: DirContext createSubcontext(Name name, Attributes attributes)
273: throws NamingException;
274:
275: /**
276: * Creates and binds a new subcontext.
277: *
278: * @param s
279: * the string representative of name bound to the new subcontext
280: * @param attributes
281: * the attributes of the new subcontxt, can be null
282: * @return the new subcontext
283: * @throws NamingException
284: * If any occurs.
285: * @see #createSubcontext(Name n, Attributes attributes)
286: */
287: DirContext createSubcontext(String s, Attributes attributes)
288: throws NamingException;
289:
290: /**
291: * Gets all attributes of <code>name</code>.
292: * <p>
293: * See note in description about operational attributes.
294: * </p>
295: * <p>
296: * The returned set of attributes is empty if <code>name</code> has no
297: * attributes.
298: * </p>
299: * <p>
300: * This method throws any <code>NamingException</code> that occurs.
301: * </p>
302: *
303: * @param name
304: * name to be searched for attributes
305: * @return all attributes of <code>name</code>
306: * @throws NamingException
307: * If any occurs.
308: */
309: Attributes getAttributes(Name name) throws NamingException;
310:
311: /**
312: * Gets the attributes for <code>name</code> that match the strings in
313: * array <code>as</code>.
314: * <p>
315: * If any string in <code>as</code> is not matched it is skipped. More
316: * attributes may be returned than the number of strings in <code>as</code> -
317: * see notes on attribute aliasing.
318: * </p>
319: * <p>
320: * This method throws any <code>NamingException</code> that occurs.
321: * </p>
322: *
323: * @param name
324: * name to be searched for attributes
325: * @param as
326: * the array of strings to match attributes
327: * @return all attributes for <code>name</code> that match the strings in
328: * array <code>as</code>.
329: * @throws NamingException
330: * If any occurs.
331: */
332: Attributes getAttributes(Name name, String as[])
333: throws NamingException;
334:
335: /**
336: * Gets all attributes of name represented by <code>s</code>.
337: *
338: * @param s
339: * representative of name to be searched for attributes
340: * @return all attributes of name represented by <code>s</code>
341: * @throws NamingException
342: * If any occurs.
343: * @see #getAttributes(Name name)
344: */
345: Attributes getAttributes(String s) throws NamingException;
346:
347: /**
348: * Gets the attributes for name represented by <code>s</code> that match
349: * the strings in array <code>as</code>.
350: *
351: * @param s
352: * representative of name to be searched for attributes
353: * @param as
354: * the array of strings to match attributes
355: * @return all attributes for name represented by <code>s</code> that
356: * match the strings in array <code>as</code>.
357: * @throws NamingException
358: * If any occurs.
359: * @see #getAttributes(Name name, String[] as)
360: */
361: Attributes getAttributes(String s, String as[])
362: throws NamingException;
363:
364: /**
365: * Gets the top level of the schema for object <code>name</code>.
366: * <p>
367: * If <code>name</code> does not support a schema this method throws an
368: * <code>OperationNotSupportedException</code>.
369: * </p>
370: * <p>
371: * This method throws any <code>NamingException</code> that occurs.
372: * </p>
373: *
374: * @param name
375: * the object to be searched for schema
376: * @return the top level of the schema for object <code>name</code>
377: * @throws NamingException
378: * If any occurs.
379: */
380: DirContext getSchema(Name name) throws NamingException;
381:
382: /**
383: * Gets the top level of the schema for name represented by <code>s</code>.
384: *
385: * @param s
386: * representative of name to be searched for schema
387: * @return the top level of the schema for object <code>name</code>
388: * @throws NamingException
389: * If any occurs.
390: * @see #getSchema(Name name)
391: */
392: DirContext getSchema(String s) throws NamingException;
393:
394: /**
395: * Gets the class definition for <code>name</code> from its schema.
396: * <p>
397: * A class definition from a schema specifies a type and its mandatory and
398: * optional attributes. Note that the term "class" here refers to the
399: * general concept of a data type, not a Java class.
400: * </p>
401: * <p>
402: * If <code>name</code> does not support a schema this method throws an
403: * <code>OperationNotSupportedException</code>.
404: * </p>
405: * <p>
406: * This method throws any <code>NamingException</code> that occurs.
407: * </p>
408: *
409: * @param name
410: * the name to searched for the class definition from its schema
411: * @return the class definition for <code>name</code> from its schema.
412: * @throws NamingException
413: * If any occurs.
414: */
415: DirContext getSchemaClassDefinition(Name name)
416: throws NamingException;
417:
418: /**
419: * Gets the class definition for name represented by <code>s</code> from
420: * its schema.
421: *
422: * @param s
423: * the string representative of name to searched for the class
424: * definition from its schema
425: * @return the class definition for <code>name</code> from its schema.
426: * @throws NamingException
427: * If any occurs.
428: * @see #getSchemaClassDefinition(Name name)
429: */
430: DirContext getSchemaClassDefinition(String s)
431: throws NamingException;
432:
433: /**
434: * Modifies the attributes of <code>name</code>.
435: * <p>
436: * Parameter <code>i</code> is modification operation type and is
437: * constrained to be one of <code>ADD_ATTRIBUTE</code>,
438: * <code>REPLACE_ATTRIBUTE</code>, <code>REMOVE_ATTRIBUTE</code>. The
439: * implementation should try to make the modifications atomic.
440: * </p>
441: * <p>
442: * This method throws an <code>AttributeModificationException</code> if
443: * there is a problem completing the modification.
444: * </p>
445: * <p>
446: * This method throws any <code>NamingException<code> that occurs.</p>
447: *
448: * @param name the name which attributes will be modified
449: * @param i the modification operation type
450: * @param attributes the modified attributes
451: * @throws NamingException If any occurs.
452: */
453: void modifyAttributes(Name name, int i, Attributes attributes)
454: throws NamingException;
455:
456: /**
457: * Modifies the attributes of <code>name</code> in the order given by the
458: * array parameter <code>amodificationitem</code>.
459: * <p>
460: * The required operations are specified by the elements of
461: * <code>modificationItems</code>.
462: * </p>
463: * <p>
464: * This method throws an <code>AttributeModificationException</code> if
465: * there is a problem completing the modifications.
466: * </p>
467: * <p>
468: * This method throws any <code>NamingException</code> that occurs.
469: * </p>
470: *
471: * @param name
472: * the name which attributes will be modified
473: * @param modificationItems
474: * the array of modification item
475: * @throws NamingException
476: * If any occurs.
477: */
478: void modifyAttributes(Name name,
479: ModificationItem[] modificationItems)
480: throws NamingException;
481:
482: /**
483: * Modifies the attributes of name represented by <code>s</code>.
484: *
485: * @param s
486: * name represented by <code>s</code>
487: * @param i
488: * the modification operation type
489: * @param attributes
490: * the modified attributes
491: * @throws NamingException
492: * If any occurs.
493: * @see #modifyAttributes(Name name, int i, Attributes attributes)
494: */
495: void modifyAttributes(String s, int i, Attributes attributes)
496: throws NamingException;
497:
498: /**
499: * Modifies the attributes of name represented by <code>s</code> in the
500: * order given by the array parameter <code>modificationItems</code>.
501: *
502: * @param s
503: * name represented by <code>s</code>
504: * @param modificationItems
505: * the array of modification item
506: * @throws NamingException
507: * If any occurs.
508: * @see #modifyAttributes(Name name, ModificationItem[] modificationItems)
509: */
510: void modifyAttributes(String s, ModificationItem[] modificationItems)
511: throws NamingException;
512:
513: /**
514: * Rebinds <code>name</code> to <code>obj</code>.
515: * <p>
516: * If the attributes parameter is non-null, the attributes it specifies
517: * become the only attributes of the binding. If the attributes parameter is
518: * null but <code>obj</code> is an instance of <code>DirContext</code>
519: * then the attributes of <code>obj</code> become the only attributes of
520: * the binding. If the <code>attributes</code> parameter is null and
521: * <code>obj</code> is not an instance of <code>DirContext</code> then
522: * any attributes of the previous binding remain.
523: * </p>
524: * <p>
525: * If a schema defines mandatory attributes for the binding but they are not
526: * all present this method throws an <code>InvalidAttributesException</code>.
527: * </p>
528: * <p>
529: * This method throws any <code>NamingException</code> that occurs.
530: * </p>
531: *
532: * @param name
533: * the name to be bound
534: * @param obj
535: * the object to be bound
536: * @param attributes
537: * the attributes of the binding
538: * @throws NamingException
539: * If any occurs.
540: */
541: void rebind(Name name, Object obj, Attributes attributes)
542: throws NamingException;
543:
544: /**
545: * Rebinds name represented by <code>s</code> to <code>obj</code>.
546: *
547: * @param s
548: * the string representative of name to be bound
549: * @param obj
550: * the object to be bound
551: * @param attributes
552: * the attributes of the binding
553: * @throws NamingException
554: * If any occurs.
555: * @see #rebind(Name name, Object o, Attributes attributes)
556: */
557: void rebind(String s, Object obj, Attributes attributes)
558: throws NamingException;
559:
560: /**
561: * Searches in the context specified by <code>name</code> only, for any
562: * objects that have attributes that match the <code>attributes</code>
563: * parameter.
564: * <p>
565: * This method is equivalent to passing a null <code>as</code> parameter
566: * to <code>search(Name name, Attributes attributes, String[] as)</code>.
567: * Objects with attributes that match the <code>attributes</code>
568: * parameter are selected and all attributes are returned for selected
569: * objects.
570: * </p>
571: * <p>
572: * This method throws any <code>NamingException</code> that occurs.
573: * </p>
574: *
575: * @param name
576: * the name specifies the context to be searched
577: * @param attributes
578: * the attributes to be matched when search
579: * @return <code>NamingEnumeration</code> of <code>SearchResult</code>
580: * @throws NamingException
581: * If any occurs.
582: * @see #search(Name name, Attributes attributes, String[] as)
583: */
584: NamingEnumeration<SearchResult> search(Name name,
585: Attributes attributes) throws NamingException;
586:
587: /**
588: * This method searches in the context specified by <code>name</code>
589: * only, for any objects that have attributes that match the
590: * <code>attributes</code> parameter.
591: *
592: * <p>
593: * It uses default <code>SearchControls</code>. An object is selected if
594: * it has every attribute in the <code>attributes</code> parameter,
595: * regardless of whether it has extra attributes. If the
596: * <code>attributes</code> parameter is null or empty then every object in
597: * the context is a match.
598: * </p>
599: * <p>
600: * The definition of attribute matching is
601: * <ol>
602: * <li>both attributes have the same identifier;</li>
603: * <li>all values of the attribute from the attributes parameter are found
604: * in the attribute from the target object.</li>
605: * </ol>
606: * </p>
607: * <p>
608: * Attribute ordering is ignored. If an attribute from the
609: * <code>attributes</code> parameter has no values it is matched by any
610: * attribute that has the same identifier. The definition of attribute value
611: * equality is left to the directory service - it could be
612: * <code>Object.equals(Object obj)</code>, or a test defined by a schema.
613: * </p>
614: * <p>
615: * For each of the selected objects, this method collects and returns the
616: * attributes with identifiers listed in parameter <code>as</code>. Note
617: * that these may be different to those in the <code>attributes</code>
618: * parameter. If a selected object does not have one of the attributes
619: * listed in <code>as</code>, the missing attribute is simply skipped for
620: * that object. Attribute aliasing may mean that an attribute in the
621: * <code>as</code> parameter list maps to more than one returned
622: * attribute. If parameter <code>as</code> is empty, no attributes are
623: * returned, but if <code>a</code>s is null all attributes are returned.
624: * </p>
625: * <p>
626: * The return value is an enumeration of <code>SearchResult</code>
627: * objects, which is empty if no matches are found. It is not specified how
628: * subsequent changes to context specified by <code>name</code> will
629: * affect an enumeration that this method returns.
630: * </p>
631: * <p>
632: * This method throws any <code>NamingException</code> that occurs.
633: * </p>
634: *
635: * @param name
636: * the name specifies the context to be searched
637: * @param attributes
638: * the attributes to be matched when search
639: * @param as
640: * the array of string representative of attributes to be
641: * returned
642: * @return <code>NamingEnumeration</code> of <code>SearchResult</code>
643: * @throws NamingException
644: * If any occurs.
645: */
646: NamingEnumeration<SearchResult> search(Name name,
647: Attributes attributes, String as[]) throws NamingException;
648:
649: /**
650: * This method searches in the context specified by <code>name</code>
651: * only, using the filter specified by parameter <code>filter</code> and
652: * controlled by <code>searchControls</code>.
653: *
654: * <p>
655: * The parameter <code>filter</code> is an RFC2254 filter. It may contain
656: * variables such as "{N}", which refer to element N of the
657: * <code>objs</code> array.
658: * </p>
659: * <p>
660: * The "{N}" variables can be used in place of "attr", "value", or
661: * "matchingrule" from RFC2254 section 4. If an "{N}" variable refers to a
662: * <code>String</code> object, that string becomes part of the filter
663: * string, but with any special characters escaped as defined by RFC 2254.
664: * The directory service implementation decides how to interpret filter
665: * arguments with types other than <code>String</code>. The result of
666: * giving invalid variable substitutions is not specified.
667: * </p>
668: * <p>
669: * If <code>searchControls</code> is null, the default
670: * <code>SearchControls</code> object is used: i.e. the object created by
671: * the no-args <code>SearchControls()</code> constructor.
672: * </p>
673: * <p>
674: * The return value is an enumeration of <code>SearchResult</code>
675: * objects. The object names used may be relative to the context specified
676: * in the <code>name</code> parameter, or a URL string. If the
677: * <code>name</code> context itself is referred to in the results, the
678: * empty string is used. It is not specified how subsequent changes to
679: * context specified by <code>name</code> will affect an enumeration that
680: * this method returns.
681: * </p>
682: * <p>
683: * If an "{N}" variable in <code>s</code> references a position outside
684: * the bounds of array <code>objs</code> this method will throw an
685: * <code>ArrayIndexOutOfBoundsException</code>.
686: * </p>
687: * <p>
688: * If <code>searchControls</code> is invalid this method will throw
689: * <code>InvalidSearchControlsException</code>.
690: * </p>
691: * <p>
692: * If the filter specified by <code>filter</code> and <code>objs</code>
693: * is invalid this method will throw an
694: * <code>InvalidSearchFilterException</code>.
695: * </p>
696: * <p>
697: * This method throws any <code>NamingException</code> that occurs.
698: *
699: * @param name
700: * the name specifies the context to be searched
701: * @param filter
702: * the search filter
703: * @param objs
704: * array of objects referred by search filter
705: * @param searchControls
706: * the search controls
707: * @return <code>NamingEnumeration</code> of <code>SearchResult</code>
708: * @throws NamingException
709: * If any occurs.
710: * @see SearchControls
711: */
712: NamingEnumeration<SearchResult> search(Name name, String filter,
713: Object[] objs, SearchControls searchControls)
714: throws NamingException;
715:
716: /**
717: * This method searches in the context specified by <code>name</code>
718: * only, using the filter specified by parameter <code>filter</code> and
719: * controlled by <code>searchControls</code>.
720: * <p>
721: * This method can throw <code>InvalidSearchFilterException<c/ode>,
722: * <code>InvalidSearchControlsException</code>, <code>NamingException</code>.</p>
723: *
724: * @param name the name specifies the context to be searched
725: * @param filter the search filter
726: * @param searchControls the search controls
727: * @return <code>NamingEnumeration</code> of <code>SearchResult</code>
728: * @throws NamingException If any occurs.
729: * @see #search(Name, String, Object[], SearchControls)
730: */
731: NamingEnumeration<SearchResult> search(Name name, String filter,
732: SearchControls searchControls) throws NamingException;
733:
734: /**
735: * Searches in the context specified by name represented by
736: * <code>name</code> only, for any objects that have attributes that match
737: * the <code>attributes</code> parameter.
738: *
739: * @param name
740: * the string representative of name which specifies the context
741: * to be searched
742: * @param attributes
743: * the attributes to be matched when search
744: * @return <code>NamingEnumeration</code> of <code>SearchResult</code>
745: * @throws NamingException
746: * If any occurs.
747: * @see #search(Name, Attributes)
748: */
749: NamingEnumeration<SearchResult> search(String name,
750: Attributes attributes) throws NamingException;
751:
752: /**
753: * This method searches in the context specified by name represented by
754: * <code>name</code> only, for any objects that have attributes that match
755: * the <code>attributes</code> parameter.
756: *
757: * @param name
758: * the string representative of name which specifies the context
759: * to be searched
760: * @param attributes
761: * the attributes to be matched when search
762: * @param as
763: * the array of string representative of attributes to be
764: * returned
765: * @return <code>NamingEnumeration</code> of <code>SearchResult</code>
766: * @throws NamingException
767: * If any occurs.
768: * @see #search(Name, Attributes, String[])
769: */
770: NamingEnumeration<SearchResult> search(String name,
771: Attributes attributes, String as[]) throws NamingException;
772:
773: /**
774: * This method searches in the context specified by name represented by
775: * <code>name</code> only, using the filter specified by parameter
776: * <code>filter</code> and controlled by <code>searchControls</code>.
777: *
778: * @param name
779: * the string representative of name which specifies the context
780: * to be searched
781: * @param filter
782: * the search filter
783: * @param objs
784: * array of objects referred by search filter
785: * @param searchControls
786: * the search controls
787: * @return <code>NamingEnumeration</code> of <code>SearchResult</code>
788: * @throws NamingException
789: * If any occurs.
790: * @see #search(Name, String, Object[], SearchControls)
791: */
792: NamingEnumeration<SearchResult> search(String name, String filter,
793: Object[] objs, SearchControls searchControls)
794: throws NamingException;
795:
796: /**
797: * This method searches in the context specified by name represented by
798: * <code>name</code> only, using the filter specified by parameter
799: * <code>filter</code> and controlled by <code>searchControls</code>.
800: *
801: * @param name
802: * the string representative of name which specifies the context
803: * to be searched
804: * @param filter
805: * the search filter
806: * @param searchControls
807: * the search controls
808: * @return <code>NamingEnumeration</code> of <code>SearchResult</code>
809: * @throws NamingException
810: * If any occurs.
811: * @see #search(Name, String, SearchControls)
812: */
813: NamingEnumeration<SearchResult> search(String name, String filter,
814: SearchControls searchControls) throws NamingException;
815:
816: }
|