001: package com.flexive.war.webdav.catalina;
002:
003: import javax.naming.*;
004: import javax.naming.directory.Attributes;
005: import javax.naming.directory.DirContext;
006: import javax.naming.directory.ModificationItem;
007: import javax.naming.directory.SearchControls;
008: import java.util.Hashtable;
009:
010: /**
011: * Catalina sources cloned for packaging issues to the flexive source tree.
012: * Refactored to JDK 1.5 compatibility.
013: * Licensed under the Apache License, Version 2.0
014: * <p/>
015: * Directory Context implementation helper class.
016: *
017: * @author Remy Maucherat
018: * @author Markus Plesser (markus.plesser@flexive.com), UCS - unique computing solutions gmbh (http://www.ucs.at)
019: */
020:
021: public abstract class BaseDirContext implements DirContext {
022:
023: // -------------------------------------------------------------- Constants
024:
025: // ----------------------------------------------------------- Constructors
026:
027: /**
028: * Builds a base directory context.
029: */
030: public BaseDirContext() {
031: this .env = new Hashtable();
032: }
033:
034: /**
035: * Builds a base directory context using the given environment.
036: */
037: public BaseDirContext(Hashtable env) {
038: this .env = env;
039: }
040:
041: // ----------------------------------------------------- Instance Variables
042:
043: /**
044: * The document base path.
045: */
046: protected String docBase = null;
047:
048: /**
049: * Environment.
050: */
051: protected Hashtable env;
052:
053: /**
054: * Name parser for this context.
055: */
056: protected final NameParser nameParser = new NameParserImpl();
057:
058: /**
059: * Cached.
060: */
061: protected boolean cached = true;
062:
063: /**
064: * Cache TTL.
065: */
066: protected int cacheTTL = 5000; // 5s
067:
068: /**
069: * Max size of resources which will have their content cached.
070: */
071: protected int cacheMaxSize = 10240; // 10 MB
072:
073: // ------------------------------------------------------------- Properties
074:
075: /**
076: * Return the document root for this component.
077: */
078: public String getDocBase() {
079: return (this .docBase);
080: }
081:
082: /**
083: * Set the document root for this component.
084: *
085: * @param docBase The new document root
086: * @throws IllegalArgumentException if the specified value is not
087: * supported by this implementation
088: * @throws IllegalArgumentException if this would create a
089: * malformed URL
090: */
091: public void setDocBase(String docBase) {
092:
093: // Validate the format of the proposed document root
094: if (docBase == null)
095: throw new IllegalArgumentException("resources.null");
096:
097: // Change the document root property
098: this .docBase = docBase;
099:
100: }
101:
102: /**
103: * Set cached.
104: */
105: public void setCached(boolean cached) {
106: this .cached = cached;
107: }
108:
109: /**
110: * Is cached ?
111: */
112: public boolean isCached() {
113: return cached;
114: }
115:
116: /**
117: * Set cache TTL.
118: */
119: public void setCacheTTL(int cacheTTL) {
120: this .cacheTTL = cacheTTL;
121: }
122:
123: /**
124: * Get cache TTL.
125: */
126: public int getCacheTTL() {
127: return cacheTTL;
128: }
129:
130: /**
131: * Return the maximum size of the cache in KB.
132: */
133: public int getCacheMaxSize() {
134: return cacheMaxSize;
135: }
136:
137: /**
138: * Set the maximum size of the cache in KB.
139: */
140: public void setCacheMaxSize(int cacheMaxSize) {
141: this .cacheMaxSize = cacheMaxSize;
142: }
143:
144: // --------------------------------------------------------- Public Methods
145:
146: /**
147: * Allocate resources for this directory context.
148: */
149: public void allocate() {
150: // No action taken by the default implementation
151: }
152:
153: /**
154: * Release any resources allocated for this directory context.
155: */
156: public void release() {
157: // No action taken by the default implementation
158: }
159:
160: // -------------------------------------------------------- Context Methods
161:
162: /**
163: * Retrieves the named object. If name is empty, returns a new instance
164: * of this context (which represents the same naming context as this
165: * context, but its environment may be modified independently and it may
166: * be accessed concurrently).
167: *
168: * @param name the name of the object to look up
169: * @return the object bound to name
170: * @throws NamingException if a naming exception is encountered
171: */
172: public Object lookup(Name name) throws NamingException {
173: return lookup(name.toString());
174: }
175:
176: /**
177: * Retrieves the named object.
178: *
179: * @param name the name of the object to look up
180: * @return the object bound to name
181: * @throws NamingException if a naming exception is encountered
182: */
183: public abstract Object lookup(String name) throws NamingException;
184:
185: /**
186: * Binds a name to an object. All intermediate contexts and the target
187: * context (that named by all but terminal atomic component of the name)
188: * must already exist.
189: *
190: * @param name the name to bind; may not be empty
191: * @param obj the object to bind; possibly null
192: * mandatory attributes
193: * @throws NamingException if a naming exception is encountered
194: */
195: public void bind(Name name, Object obj) throws NamingException {
196: bind(name.toString(), obj);
197: }
198:
199: /**
200: * Binds a name to an object.
201: *
202: * @param name the name to bind; may not be empty
203: * @param obj the object to bind; possibly null
204: * mandatory attributes
205: * @throws NamingException if a naming exception is encountered
206: */
207: public void bind(String name, Object obj) throws NamingException {
208: bind(name, obj, null);
209: }
210:
211: /**
212: * Binds a name to an object, overwriting any existing binding. All
213: * intermediate contexts and the target context (that named by all but
214: * terminal atomic component of the name) must already exist.
215: * <p/>
216: * If the object is a DirContext, any existing attributes associated with
217: * the name are replaced with those of the object. Otherwise, any
218: * existing attributes associated with the name remain unchanged.
219: *
220: * @param name the name to bind; may not be empty
221: * @param obj the object to bind; possibly null
222: * mandatory attributes
223: * @throws NamingException if a naming exception is encountered
224: */
225: public void rebind(Name name, Object obj) throws NamingException {
226: rebind(name.toString(), obj);
227: }
228:
229: /**
230: * Binds a name to an object, overwriting any existing binding.
231: *
232: * @param name the name to bind; may not be empty
233: * @param obj the object to bind; possibly null
234: * mandatory attributes
235: * @throws NamingException if a naming exception is encountered
236: */
237: public void rebind(String name, Object obj) throws NamingException {
238: rebind(name, obj, null);
239: }
240:
241: /**
242: * Unbinds the named object. Removes the terminal atomic name in name
243: * from the target context--that named by all but the terminal atomic
244: * part of name.
245: * <p/>
246: * This method is idempotent. It succeeds even if the terminal atomic
247: * name is not bound in the target context, but throws
248: * NameNotFoundException if any of the intermediate contexts do not exist.
249: *
250: * @param name the name to bind; may not be empty
251: * @throws NamingException if a naming exception is encountered
252: */
253: public void unbind(Name name) throws NamingException {
254: unbind(name.toString());
255: }
256:
257: /**
258: * Unbinds the named object.
259: *
260: * @param name the name to bind; may not be empty
261: * @throws NamingException if a naming exception is encountered
262: */
263: public abstract void unbind(String name) throws NamingException;
264:
265: /**
266: * Binds a new name to the object bound to an old name, and unbinds the
267: * old name. Both names are relative to this context. Any attributes
268: * associated with the old name become associated with the new name.
269: * Intermediate contexts of the old name are not changed.
270: *
271: * @param oldName the name of the existing binding; may not be empty
272: * @param newName the name of the new binding; may not be empty
273: * @throws NamingException if a naming exception is encountered
274: */
275: public void rename(Name oldName, Name newName)
276: throws NamingException {
277: rename(oldName.toString(), newName.toString());
278: }
279:
280: /**
281: * Binds a new name to the object bound to an old name, and unbinds the
282: * old name.
283: *
284: * @param oldName the name of the existing binding; may not be empty
285: * @param newName the name of the new binding; may not be empty
286: * @throws NamingException if a naming exception is encountered
287: */
288: public abstract void rename(String oldName, String newName)
289: throws NamingException;
290:
291: /**
292: * Enumerates the names bound in the named context, along with the class
293: * names of objects bound to them. The contents of any subcontexts are
294: * not included.
295: * <p/>
296: * If a binding is added to or removed from this context, its effect on
297: * an enumeration previously returned is undefined.
298: *
299: * @param name the name of the context to list
300: * @return an enumeration of the names and class names of the bindings in
301: * this context. Each element of the enumeration is of type NameClassPair.
302: * @throws NamingException if a naming exception is encountered
303: */
304: public NamingEnumeration list(Name name) throws NamingException {
305: return list(name.toString());
306: }
307:
308: /**
309: * Enumerates the names bound in the named context, along with the class
310: * names of objects bound to them.
311: *
312: * @param name the name of the context to list
313: * @return an enumeration of the names and class names of the bindings in
314: * this context. Each element of the enumeration is of type NameClassPair.
315: * @throws NamingException if a naming exception is encountered
316: */
317: public abstract NamingEnumeration list(String name)
318: throws NamingException;
319:
320: /**
321: * Enumerates the names bound in the named context, along with the
322: * objects bound to them. The contents of any subcontexts are not
323: * included.
324: * <p/>
325: * If a binding is added to or removed from this context, its effect on
326: * an enumeration previously returned is undefined.
327: *
328: * @param name the name of the context to list
329: * @return an enumeration of the bindings in this context.
330: * Each element of the enumeration is of type Binding.
331: * @throws NamingException if a naming exception is encountered
332: */
333: public NamingEnumeration listBindings(Name name)
334: throws NamingException {
335: return listBindings(name.toString());
336: }
337:
338: /**
339: * Enumerates the names bound in the named context, along with the
340: * objects bound to them.
341: *
342: * @param name the name of the context to list
343: * @return an enumeration of the bindings in this context.
344: * Each element of the enumeration is of type Binding.
345: * @throws NamingException if a naming exception is encountered
346: */
347: public abstract NamingEnumeration listBindings(String name)
348: throws NamingException;
349:
350: /**
351: * Destroys the named context and removes it from the namespace. Any
352: * attributes associated with the name are also removed. Intermediate
353: * contexts are not destroyed.
354: * <p/>
355: * This method is idempotent. It succeeds even if the terminal atomic
356: * name is not bound in the target context, but throws
357: * NameNotFoundException if any of the intermediate contexts do not exist.
358: * <p/>
359: * In a federated naming system, a context from one naming system may be
360: * bound to a name in another. One can subsequently look up and perform
361: * operations on the foreign context using a composite name. However, an
362: * attempt destroy the context using this composite name will fail with
363: * NotContextException, because the foreign context is not a "subcontext"
364: * of the context in which it is bound. Instead, use unbind() to remove
365: * the binding of the foreign context. Destroying the foreign context
366: * requires that the destroySubcontext() be performed on a context from
367: * the foreign context's "native" naming system.
368: *
369: * @param name the name of the context to be destroyed; may not be empty
370: */
371: public void destroySubcontext(Name name) throws NamingException {
372: destroySubcontext(name.toString());
373: }
374:
375: /**
376: * Destroys the named context and removes it from the namespace.
377: *
378: * @param name the name of the context to be destroyed; may not be empty
379: */
380: public abstract void destroySubcontext(String name)
381: throws NamingException;
382:
383: /**
384: * Creates and binds a new context. Creates a new context with the given
385: * name and binds it in the target context (that named by all but
386: * terminal atomic component of the name). All intermediate contexts and
387: * the target context must already exist.
388: *
389: * @param name the name of the context to create; may not be empty
390: * @return the newly created context
391: * @throws NamingException if a naming exception is encountered
392: */
393: public Context createSubcontext(Name name) throws NamingException {
394: return createSubcontext(name.toString());
395: }
396:
397: /**
398: * Creates and binds a new context.
399: *
400: * @param name the name of the context to create; may not be empty
401: * @return the newly created context
402: * @throws NamingException if a naming exception is encountered
403: */
404: public Context createSubcontext(String name) throws NamingException {
405: return createSubcontext(name, null);
406: }
407:
408: /**
409: * Retrieves the named object, following links except for the terminal
410: * atomic component of the name. If the object bound to name is not a
411: * link, returns the object itself.
412: *
413: * @param name the name of the object to look up
414: * @return the object bound to name, not following the terminal link
415: * (if any).
416: * @throws NamingException if a naming exception is encountered
417: */
418: public Object lookupLink(Name name) throws NamingException {
419: return lookupLink(name.toString());
420: }
421:
422: /**
423: * Retrieves the named object, following links except for the terminal
424: * atomic component of the name.
425: *
426: * @param name the name of the object to look up
427: * @return the object bound to name, not following the terminal link
428: * (if any).
429: * @throws NamingException if a naming exception is encountered
430: */
431: public abstract Object lookupLink(String name)
432: throws NamingException;
433:
434: /**
435: * Retrieves the parser associated with the named context. In a
436: * federation of namespaces, different naming systems will parse names
437: * differently. This method allows an application to get a parser for
438: * parsing names into their atomic components using the naming convention
439: * of a particular naming system. Within any single naming system,
440: * NameParser objects returned by this method must be equal (using the
441: * equals() test).
442: *
443: * @param name the name of the context from which to get the parser
444: * @return a name parser that can parse compound names into their atomic
445: * components
446: * @throws NamingException if a naming exception is encountered
447: */
448: public NameParser getNameParser(Name name) throws NamingException {
449: return new NameParserImpl();
450: }
451:
452: /**
453: * Retrieves the parser associated with the named context.
454: *
455: * @param name the name of the context from which to get the parser
456: * @return a name parser that can parse compound names into their atomic
457: * components
458: * @throws NamingException if a naming exception is encountered
459: */
460: public NameParser getNameParser(String name) throws NamingException {
461: return new NameParserImpl();
462: }
463:
464: /**
465: * Composes the name of this context with a name relative to this context.
466: * <p/>
467: * Given a name (name) relative to this context, and the name (prefix)
468: * of this context relative to one of its ancestors, this method returns
469: * the composition of the two names using the syntax appropriate for the
470: * naming system(s) involved. That is, if name names an object relative
471: * to this context, the result is the name of the same object, but
472: * relative to the ancestor context. None of the names may be null.
473: *
474: * @param name a name relative to this context
475: * @param prefix the name of this context relative to one of its ancestors
476: * @return the composition of prefix and name
477: * @throws NamingException if a naming exception is encountered
478: */
479: public Name composeName(Name name, Name prefix)
480: throws NamingException {
481: prefix = (Name) prefix.clone();
482: return prefix.addAll(name);
483: }
484:
485: /**
486: * Composes the name of this context with a name relative to this context.
487: *
488: * @param name a name relative to this context
489: * @param prefix the name of this context relative to one of its ancestors
490: * @return the composition of prefix and name
491: * @throws NamingException if a naming exception is encountered
492: */
493: public String composeName(String name, String prefix)
494: throws NamingException {
495: return prefix + "/" + name;
496: }
497:
498: /**
499: * Adds a new environment property to the environment of this context. If
500: * the property already exists, its value is overwritten.
501: *
502: * @param propName the name of the environment property to add; may not
503: * be null
504: * @param propVal the value of the property to add; may not be null
505: * @throws NamingException if a naming exception is encountered
506: */
507: public Object addToEnvironment(String propName, Object propVal)
508: throws NamingException {
509: return env.put(propName, propVal);
510: }
511:
512: /**
513: * Removes an environment property from the environment of this context.
514: *
515: * @param propName the name of the environment property to remove;
516: * may not be null
517: * @throws NamingException if a naming exception is encountered
518: */
519: public Object removeFromEnvironment(String propName)
520: throws NamingException {
521: return env.remove(propName);
522: }
523:
524: /**
525: * Retrieves the environment in effect for this context. See class
526: * description for more details on environment properties.
527: * The caller should not make any changes to the object returned: their
528: * effect on the context is undefined. The environment of this context
529: * may be changed using addToEnvironment() and removeFromEnvironment().
530: *
531: * @return the environment of this context; never null
532: * @throws NamingException if a naming exception is encountered
533: */
534: public Hashtable getEnvironment() throws NamingException {
535: return env;
536: }
537:
538: /**
539: * Closes this context. This method releases this context's resources
540: * immediately, instead of waiting for them to be released automatically
541: * by the garbage collector.
542: * This method is idempotent: invoking it on a context that has already
543: * been closed has no effect. Invoking any other method on a closed
544: * context is not allowed, and results in undefined behaviour.
545: *
546: * @throws NamingException if a naming exception is encountered
547: */
548: public void close() throws NamingException {
549: env.clear();
550: }
551:
552: /**
553: * Retrieves the full name of this context within its own namespace.
554: * <p/>
555: * Many naming services have a notion of a "full name" for objects in
556: * their respective namespaces. For example, an LDAP entry has a
557: * distinguished name, and a DNS record has a fully qualified name. This
558: * method allows the client application to retrieve this name. The string
559: * returned by this method is not a JNDI composite name and should not be
560: * passed directly to context methods. In naming systems for which the
561: * notion of full name does not make sense,
562: * OperationNotSupportedException is thrown.
563: *
564: * @return this context's name in its own namespace; never null
565: * @throws NamingException if a naming exception is encountered
566: */
567: public abstract String getNameInNamespace() throws NamingException;
568:
569: // ----------------------------------------------------- DirContext Methods
570:
571: /**
572: * Retrieves all of the attributes associated with a named object.
573: *
574: * @param name the name of the object from which to retrieve attributes
575: * @return the set of attributes associated with name.
576: * Returns an empty attribute set if name has no attributes; never null.
577: * @throws NamingException if a naming exception is encountered
578: */
579: public Attributes getAttributes(Name name) throws NamingException {
580: return getAttributes(name.toString());
581: }
582:
583: /**
584: * Retrieves all of the attributes associated with a named object.
585: *
586: * @param name the name of the object from which to retrieve attributes
587: * @return the set of attributes associated with name
588: * @throws NamingException if a naming exception is encountered
589: */
590: public Attributes getAttributes(String name) throws NamingException {
591: return getAttributes(name, null);
592: }
593:
594: /**
595: * Retrieves selected attributes associated with a named object.
596: * See the class description regarding attribute models, attribute type
597: * names, and operational attributes.
598: *
599: * @param name the name of the object from which to retrieve attributes
600: * @param attrIds the identifiers of the attributes to retrieve. null
601: * indicates that all attributes should be retrieved; an empty array
602: * indicates that none should be retrieved
603: * @return the requested attributes; never null
604: * @throws NamingException if a naming exception is encountered
605: */
606: public Attributes getAttributes(Name name, String[] attrIds)
607: throws NamingException {
608: return getAttributes(name.toString(), attrIds);
609: }
610:
611: /**
612: * Retrieves selected attributes associated with a named object.
613: *
614: * @param name the name of the object from which to retrieve attributes
615: * @param attrIds the identifiers of the attributes to retrieve. null
616: * indicates that all attributes should be retrieved; an empty array
617: * indicates that none should be retrieved
618: * @return the requested attributes; never null
619: * @throws NamingException if a naming exception is encountered
620: */
621: public abstract Attributes getAttributes(String name,
622: String[] attrIds) throws NamingException;
623:
624: /**
625: * Modifies the attributes associated with a named object. The order of
626: * the modifications is not specified. Where possible, the modifications
627: * are performed atomically.
628: *
629: * @param name the name of the object whose attributes will be updated
630: * @param mod_op the modification operation, one of: ADD_ATTRIBUTE,
631: * REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE
632: * @param attrs the attributes to be used for the modification; may not
633: * be null
634: * @throws NamingException if a naming exception is encountered
635: */
636: public void modifyAttributes(Name name, int mod_op, Attributes attrs)
637: throws NamingException {
638: modifyAttributes(name.toString(), mod_op, attrs);
639: }
640:
641: /**
642: * Modifies the attributes associated with a named object.
643: *
644: * @param name the name of the object whose attributes will be updated
645: * @param mod_op the modification operation, one of: ADD_ATTRIBUTE,
646: * REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE
647: * @param attrs the attributes to be used for the modification; may not
648: * be null
649: * @throws NamingException if a naming exception is encountered
650: */
651: public abstract void modifyAttributes(String name, int mod_op,
652: Attributes attrs) throws NamingException;
653:
654: /**
655: * Modifies the attributes associated with a named object using an an
656: * ordered list of modifications. The modifications are performed in the
657: * order specified. Each modification specifies a modification operation
658: * code and an attribute on which to operate. Where possible, the
659: * modifications are performed atomically.
660: *
661: * @param name the name of the object whose attributes will be updated
662: * @param mods an ordered sequence of modifications to be performed; may
663: * not be null
664: * @throws NamingException if a naming exception is encountered
665: */
666: public void modifyAttributes(Name name, ModificationItem[] mods)
667: throws NamingException {
668: modifyAttributes(name.toString(), mods);
669: }
670:
671: /**
672: * Modifies the attributes associated with a named object using an an
673: * ordered list of modifications.
674: *
675: * @param name the name of the object whose attributes will be updated
676: * @param mods an ordered sequence of modifications to be performed; may
677: * not be null
678: * @throws NamingException if a naming exception is encountered
679: */
680: public abstract void modifyAttributes(String name,
681: ModificationItem[] mods) throws NamingException;
682:
683: /**
684: * Binds a name to an object, along with associated attributes. If attrs
685: * is null, the resulting binding will have the attributes associated
686: * with obj if obj is a DirContext, and no attributes otherwise. If attrs
687: * is non-null, the resulting binding will have attrs as its attributes;
688: * any attributes associated with obj are ignored.
689: *
690: * @param name the name to bind; may not be empty
691: * @param obj the object to bind; possibly null
692: * @param attrs the attributes to associate with the binding
693: * @throws NamingException if a naming exception is encountered
694: */
695: public void bind(Name name, Object obj, Attributes attrs)
696: throws NamingException {
697: bind(name.toString(), obj, attrs);
698: }
699:
700: /**
701: * Binds a name to an object, along with associated attributes.
702: *
703: * @param name the name to bind; may not be empty
704: * @param obj the object to bind; possibly null
705: * @param attrs the attributes to associate with the binding
706: * @throws NamingException if a naming exception is encountered
707: */
708: public abstract void bind(String name, Object obj, Attributes attrs)
709: throws NamingException;
710:
711: /**
712: * Binds a name to an object, along with associated attributes,
713: * overwriting any existing binding. If attrs is null and obj is a
714: * DirContext, the attributes from obj are used. If attrs is null and obj
715: * is not a DirContext, any existing attributes associated with the object
716: * already bound in the directory remain unchanged. If attrs is non-null,
717: * any existing attributes associated with the object already bound in
718: * the directory are removed and attrs is associated with the named
719: * object. If obj is a DirContext and attrs is non-null, the attributes
720: * of obj are ignored.
721: *
722: * @param name the name to bind; may not be empty
723: * @param obj the object to bind; possibly null
724: * @param attrs the attributes to associate with the binding
725: * @throws NamingException if a naming exception is encountered
726: */
727: public void rebind(Name name, Object obj, Attributes attrs)
728: throws NamingException {
729: rebind(name.toString(), obj, attrs);
730: }
731:
732: /**
733: * Binds a name to an object, along with associated attributes,
734: * overwriting any existing binding.
735: *
736: * @param name the name to bind; may not be empty
737: * @param obj the object to bind; possibly null
738: * @param attrs the attributes to associate with the binding
739: * @throws NamingException if a naming exception is encountered
740: */
741: public abstract void rebind(String name, Object obj,
742: Attributes attrs) throws NamingException;
743:
744: /**
745: * Creates and binds a new context, along with associated attributes.
746: * This method creates a new subcontext with the given name, binds it in
747: * the target context (that named by all but terminal atomic component of
748: * the name), and associates the supplied attributes with the newly
749: * created object. All intermediate and target contexts must already
750: * exist. If attrs is null, this method is equivalent to
751: * Context.createSubcontext().
752: *
753: * @param name the name of the context to create; may not be empty
754: * @param attrs the attributes to associate with the newly created context
755: * @return the newly created context
756: * the mandatory attributes required for creation
757: * @throws NamingException if a naming exception is encountered
758: */
759: public DirContext createSubcontext(Name name, Attributes attrs)
760: throws NamingException {
761: return createSubcontext(name.toString(), attrs);
762: }
763:
764: /**
765: * Creates and binds a new context, along with associated attributes.
766: *
767: * @param name the name of the context to create; may not be empty
768: * @param attrs the attributes to associate with the newly created context
769: * @return the newly created context
770: * @throws NamingException if a naming exception is encountered
771: */
772: public abstract DirContext createSubcontext(String name,
773: Attributes attrs) throws NamingException;
774:
775: /**
776: * Retrieves the schema associated with the named object. The schema
777: * describes rules regarding the structure of the namespace and the
778: * attributes stored within it. The schema specifies what types of
779: * objects can be added to the directory and where they can be added;
780: * what mandatory and optional attributes an object can have. The range
781: * of support for schemas is directory-specific.
782: *
783: * @param name the name of the object whose schema is to be retrieved
784: * @return the schema associated with the context; never null
785: * @throws NamingException if a naming exception is encountered
786: */
787: public DirContext getSchema(Name name) throws NamingException {
788: return getSchema(name.toString());
789: }
790:
791: /**
792: * Retrieves the schema associated with the named object.
793: *
794: * @param name the name of the object whose schema is to be retrieved
795: * @return the schema associated with the context; never null
796: * @throws NamingException if a naming exception is encountered
797: */
798: public abstract DirContext getSchema(String name)
799: throws NamingException;
800:
801: /**
802: * Retrieves a context containing the schema objects of the named
803: * object's class definitions.
804: *
805: * @param name the name of the object whose object class definition is to
806: * be retrieved
807: * @return the DirContext containing the named object's class
808: * definitions; never null
809: * @throws NamingException if a naming exception is encountered
810: */
811: public DirContext getSchemaClassDefinition(Name name)
812: throws NamingException {
813: return getSchemaClassDefinition(name.toString());
814: }
815:
816: /**
817: * Retrieves a context containing the schema objects of the named
818: * object's class definitions.
819: *
820: * @param name the name of the object whose object class definition is to
821: * be retrieved
822: * @return the DirContext containing the named object's class
823: * definitions; never null
824: * @throws NamingException if a naming exception is encountered
825: */
826: public abstract DirContext getSchemaClassDefinition(String name)
827: throws NamingException;
828:
829: /**
830: * Searches in a single context for objects that contain a specified set
831: * of attributes, and retrieves selected attributes. The search is
832: * performed using the default SearchControls settings.
833: *
834: * @param name the name of the context to search
835: * @param matchingAttributes the attributes to search for. If empty or
836: * null, all objects in the target context are returned.
837: * @param attributesToReturn the attributes to return. null indicates
838: * that all attributes are to be returned; an empty array indicates that
839: * none are to be returned.
840: * @return a non-null enumeration of SearchResult objects. Each
841: * SearchResult contains the attributes identified by attributesToReturn
842: * and the name of the corresponding object, named relative to the
843: * context named by name.
844: * @throws NamingException if a naming exception is encountered
845: */
846: public NamingEnumeration search(Name name,
847: Attributes matchingAttributes, String[] attributesToReturn)
848: throws NamingException {
849: return search(name.toString(), matchingAttributes,
850: attributesToReturn);
851: }
852:
853: /**
854: * Searches in a single context for objects that contain a specified set
855: * of attributes, and retrieves selected attributes.
856: *
857: * @param name the name of the context to search
858: * @param matchingAttributes the attributes to search for. If empty or
859: * null, all objects in the target context are returned.
860: * @param attributesToReturn the attributes to return. null indicates
861: * that all attributes are to be returned; an empty array indicates that
862: * none are to be returned.
863: * @return a non-null enumeration of SearchResult objects. Each
864: * SearchResult contains the attributes identified by attributesToReturn
865: * and the name of the corresponding object, named relative to the
866: * context named by name.
867: * @throws NamingException if a naming exception is encountered
868: */
869: public abstract NamingEnumeration search(String name,
870: Attributes matchingAttributes, String[] attributesToReturn)
871: throws NamingException;
872:
873: /**
874: * Searches in a single context for objects that contain a specified set
875: * of attributes. This method returns all the attributes of such objects.
876: * It is equivalent to supplying null as the atributesToReturn parameter
877: * to the method search(Name, Attributes, String[]).
878: *
879: * @param name the name of the context to search
880: * @param matchingAttributes the attributes to search for. If empty or
881: * null, all objects in the target context are returned.
882: * @return a non-null enumeration of SearchResult objects. Each
883: * SearchResult contains the attributes identified by attributesToReturn
884: * and the name of the corresponding object, named relative to the
885: * context named by name.
886: * @throws NamingException if a naming exception is encountered
887: */
888: public NamingEnumeration search(Name name,
889: Attributes matchingAttributes) throws NamingException {
890: return search(name.toString(), matchingAttributes);
891: }
892:
893: /**
894: * Searches in a single context for objects that contain a specified set
895: * of attributes.
896: *
897: * @param name the name of the context to search
898: * @param matchingAttributes the attributes to search for. If empty or
899: * null, all objects in the target context are returned.
900: * @return a non-null enumeration of SearchResult objects. Each
901: * SearchResult contains the attributes identified by attributesToReturn
902: * and the name of the corresponding object, named relative to the
903: * context named by name.
904: * @throws NamingException if a naming exception is encountered
905: */
906: public abstract NamingEnumeration search(String name,
907: Attributes matchingAttributes) throws NamingException;
908:
909: /**
910: * Searches in the named context or object for entries that satisfy the
911: * given search filter. Performs the search as specified by the search
912: * controls.
913: *
914: * @param name the name of the context or object to search
915: * @param filter the filter expression to use for the search; may not be
916: * null
917: * @param cons the search controls that control the search. If null,
918: * the default search controls are used (equivalent to
919: * (new SearchControls())).
920: * @return an enumeration of SearchResults of the objects that satisfy
921: * the filter; never null
922: * @throws NamingException if a naming exception is encountered
923: */
924: public NamingEnumeration search(Name name, String filter,
925: SearchControls cons) throws NamingException {
926: return search(name.toString(), filter, cons);
927: }
928:
929: /**
930: * Searches in the named context or object for entries that satisfy the
931: * given search filter. Performs the search as specified by the search
932: * controls.
933: *
934: * @param name the name of the context or object to search
935: * @param filter the filter expression to use for the search; may not be
936: * null
937: * @param cons the search controls that control the search. If null,
938: * the default search controls are used (equivalent to
939: * (new SearchControls())).
940: * @return an enumeration of SearchResults of the objects that satisfy
941: * the filter; never null
942: * @throws NamingException if a naming exception is encountered
943: */
944: public abstract NamingEnumeration search(String name,
945: String filter, SearchControls cons) throws NamingException;
946:
947: /**
948: * Searches in the named context or object for entries that satisfy the
949: * given search filter. Performs the search as specified by the search
950: * controls.
951: *
952: * @param name the name of the context or object to search
953: * @param filterExpr the filter expression to use for the search.
954: * The expression may contain variables of the form "{i}" where i is a
955: * nonnegative integer. May not be null.
956: * @param filterArgs the array of arguments to substitute for the
957: * variables in filterExpr. The value of filterArgs[i] will replace each
958: * occurrence of "{i}". If null, equivalent to an empty array.
959: * @param cons the search controls that control the search. If null, the
960: * default search controls are used (equivalent to (new SearchControls())).
961: * @return an enumeration of SearchResults of the objects that satisy the
962: * filter; never null
963: * @throws ArrayIndexOutOfBoundsException if filterExpr contains {i}
964: * expressions where i is outside the bounds of the array filterArgs
965: * @throws NamingException if a naming exception is encountered
966: */
967: public NamingEnumeration search(Name name, String filterExpr,
968: Object[] filterArgs, SearchControls cons)
969: throws NamingException {
970: return search(name.toString(), filterExpr, filterArgs, cons);
971: }
972:
973: /**
974: * Searches in the named context or object for entries that satisfy the
975: * given search filter. Performs the search as specified by the search
976: * controls.
977: *
978: * @param name the name of the context or object to search
979: * @param filterExpr the filter expression to use for the search.
980: * The expression may contain variables of the form "{i}" where i is a
981: * nonnegative integer. May not be null.
982: * @param filterArgs the array of arguments to substitute for the
983: * variables in filterExpr. The value of filterArgs[i] will replace each
984: * occurrence of "{i}". If null, equivalent to an empty array.
985: * @param cons the search controls that control the search. If null, the
986: * default search controls are used (equivalent to (new SearchControls())).
987: * @return an enumeration of SearchResults of the objects that satisy the
988: * filter; never null
989: * @throws ArrayIndexOutOfBoundsException if filterExpr contains {i}
990: * expressions where i is outside the bounds of the array filterArgs
991: * @throws NamingException if a naming exception is encountered
992: */
993: public abstract NamingEnumeration search(String name,
994: String filterExpr, Object[] filterArgs, SearchControls cons)
995: throws NamingException;
996:
997: // ------------------------------------------------------ Protected Methods
998:
999: }
|