0001: /*
0002: * Copyright 1999,2004 The Apache Software Foundation.
0003: *
0004: * Licensed under the Apache License, Version 2.0 (the "License");
0005: * you may not use this file except in compliance with the License.
0006: * You may obtain a copy of the License at
0007: *
0008: * http://www.apache.org/licenses/LICENSE-2.0
0009: *
0010: * Unless required by applicable law or agreed to in writing, software
0011: * distributed under the License is distributed on an "AS IS" BASIS,
0012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0013: * See the License for the specific language governing permissions and
0014: * limitations under the License.
0015: */
0016:
0017: package org.apache.naming.resources;
0018:
0019: import java.util.Hashtable;
0020:
0021: import javax.naming.Context;
0022: import javax.naming.Name;
0023: import javax.naming.NameParser;
0024: import javax.naming.NamingEnumeration;
0025: import javax.naming.NamingException;
0026: import javax.naming.directory.Attributes;
0027: import javax.naming.directory.DirContext;
0028: import javax.naming.directory.ModificationItem;
0029: import javax.naming.directory.SearchControls;
0030:
0031: import org.apache.naming.NameParserImpl;
0032: import org.apache.naming.StringManager;
0033:
0034: /**
0035: * Directory Context implementation helper class.
0036: *
0037: * @author Remy Maucherat
0038: * @version $Revision: 1.4 $ $Date: 2004/02/27 14:58:54 $
0039: */
0040:
0041: public abstract class BaseDirContext implements DirContext {
0042:
0043: // -------------------------------------------------------------- Constants
0044:
0045: // ----------------------------------------------------------- Constructors
0046:
0047: /**
0048: * Builds a base directory context.
0049: */
0050: public BaseDirContext() {
0051: this .env = new Hashtable();
0052: }
0053:
0054: /**
0055: * Builds a base directory context using the given environment.
0056: */
0057: public BaseDirContext(Hashtable env) {
0058: this .env = env;
0059: }
0060:
0061: // ----------------------------------------------------- Instance Variables
0062:
0063: /**
0064: * The debugging detail level for this component.
0065: */
0066: protected int debug = 0;
0067:
0068: /**
0069: * The document base path.
0070: */
0071: protected String docBase = null;
0072:
0073: /**
0074: * Environment.
0075: */
0076: protected Hashtable env;
0077:
0078: /**
0079: * The string manager for this package.
0080: */
0081: protected StringManager sm = StringManager
0082: .getManager(Constants.Package);
0083:
0084: /**
0085: * Name parser for this context.
0086: */
0087: protected final NameParser nameParser = new NameParserImpl();
0088:
0089: /**
0090: * Cached.
0091: */
0092: protected boolean cached = true;
0093:
0094: /**
0095: * Cache TTL.
0096: */
0097: protected int cacheTTL = 5000; // 5s
0098:
0099: /**
0100: * Max size of resources which will have their content cached.
0101: */
0102: protected int cacheMaxSize = 10240; // 10 MB
0103:
0104: // ------------------------------------------------------------- Properties
0105:
0106: /**
0107: * Return the debugging detail level for this component.
0108: */
0109: public int getDebug() {
0110: return (this .debug);
0111: }
0112:
0113: /**
0114: * Set the debugging detail level for this component.
0115: *
0116: * @param debug The new debugging detail level
0117: */
0118: public void setDebug(int debug) {
0119: this .debug = debug;
0120: }
0121:
0122: /**
0123: * Return the document root for this component.
0124: */
0125: public String getDocBase() {
0126: return (this .docBase);
0127: }
0128:
0129: /**
0130: * Set the document root for this component.
0131: *
0132: * @param docBase The new document root
0133: *
0134: * @exception IllegalArgumentException if the specified value is not
0135: * supported by this implementation
0136: * @exception IllegalArgumentException if this would create a
0137: * malformed URL
0138: */
0139: public void setDocBase(String docBase) {
0140:
0141: // Validate the format of the proposed document root
0142: if (docBase == null)
0143: throw new IllegalArgumentException(sm
0144: .getString("resources.null"));
0145:
0146: // Change the document root property
0147: this .docBase = docBase;
0148:
0149: }
0150:
0151: /**
0152: * Set cached.
0153: */
0154: public void setCached(boolean cached) {
0155: this .cached = cached;
0156: }
0157:
0158: /**
0159: * Is cached ?
0160: */
0161: public boolean isCached() {
0162: return cached;
0163: }
0164:
0165: /**
0166: * Set cache TTL.
0167: */
0168: public void setCacheTTL(int cacheTTL) {
0169: this .cacheTTL = cacheTTL;
0170: }
0171:
0172: /**
0173: * Get cache TTL.
0174: */
0175: public int getCacheTTL() {
0176: return cacheTTL;
0177: }
0178:
0179: /**
0180: * Return the maximum size of the cache in KB.
0181: */
0182: public int getCacheMaxSize() {
0183: return cacheMaxSize;
0184: }
0185:
0186: /**
0187: * Set the maximum size of the cache in KB.
0188: */
0189: public void setCacheMaxSize(int cacheMaxSize) {
0190: this .cacheMaxSize = cacheMaxSize;
0191: }
0192:
0193: // --------------------------------------------------------- Public Methods
0194:
0195: /**
0196: * Allocate resources for this directory context.
0197: */
0198: public void allocate() {
0199: ; // No action taken by the default implementation
0200: }
0201:
0202: /**
0203: * Release any resources allocated for this directory context.
0204: */
0205: public void release() {
0206: ; // No action taken by the default implementation
0207: }
0208:
0209: // -------------------------------------------------------- Context Methods
0210:
0211: /**
0212: * Retrieves the named object. If name is empty, returns a new instance
0213: * of this context (which represents the same naming context as this
0214: * context, but its environment may be modified independently and it may
0215: * be accessed concurrently).
0216: *
0217: * @param name the name of the object to look up
0218: * @return the object bound to name
0219: * @exception NamingException if a naming exception is encountered
0220: */
0221: public Object lookup(Name name) throws NamingException {
0222: return lookup(name.toString());
0223: }
0224:
0225: /**
0226: * Retrieves the named object.
0227: *
0228: * @param name the name of the object to look up
0229: * @return the object bound to name
0230: * @exception NamingException if a naming exception is encountered
0231: */
0232: public abstract Object lookup(String name) throws NamingException;
0233:
0234: /**
0235: * Binds a name to an object. All intermediate contexts and the target
0236: * context (that named by all but terminal atomic component of the name)
0237: * must already exist.
0238: *
0239: * @param name the name to bind; may not be empty
0240: * @param obj the object to bind; possibly null
0241: * @exception NameAlreadyBoundException if name is already bound
0242: * @exception InvalidAttributesException if object did not supply all
0243: * mandatory attributes
0244: * @exception NamingException if a naming exception is encountered
0245: */
0246: public void bind(Name name, Object obj) throws NamingException {
0247: bind(name.toString(), obj);
0248: }
0249:
0250: /**
0251: * Binds a name to an object.
0252: *
0253: * @param name the name to bind; may not be empty
0254: * @param obj the object to bind; possibly null
0255: * @exception NameAlreadyBoundException if name is already bound
0256: * @exception InvalidAttributesException if object did not supply all
0257: * mandatory attributes
0258: * @exception NamingException if a naming exception is encountered
0259: */
0260: public void bind(String name, Object obj) throws NamingException {
0261: bind(name, obj, null);
0262: }
0263:
0264: /**
0265: * Binds a name to an object, overwriting any existing binding. All
0266: * intermediate contexts and the target context (that named by all but
0267: * terminal atomic component of the name) must already exist.
0268: * <p>
0269: * If the object is a DirContext, any existing attributes associated with
0270: * the name are replaced with those of the object. Otherwise, any
0271: * existing attributes associated with the name remain unchanged.
0272: *
0273: * @param name the name to bind; may not be empty
0274: * @param obj the object to bind; possibly null
0275: * @exception InvalidAttributesException if object did not supply all
0276: * mandatory attributes
0277: * @exception NamingException if a naming exception is encountered
0278: */
0279: public void rebind(Name name, Object obj) throws NamingException {
0280: rebind(name.toString(), obj);
0281: }
0282:
0283: /**
0284: * Binds a name to an object, overwriting any existing binding.
0285: *
0286: * @param name the name to bind; may not be empty
0287: * @param obj the object to bind; possibly null
0288: * @exception InvalidAttributesException if object did not supply all
0289: * mandatory attributes
0290: * @exception NamingException if a naming exception is encountered
0291: */
0292: public void rebind(String name, Object obj) throws NamingException {
0293: rebind(name, obj, null);
0294: }
0295:
0296: /**
0297: * Unbinds the named object. Removes the terminal atomic name in name
0298: * from the target context--that named by all but the terminal atomic
0299: * part of name.
0300: * <p>
0301: * This method is idempotent. It succeeds even if the terminal atomic
0302: * name is not bound in the target context, but throws
0303: * NameNotFoundException if any of the intermediate contexts do not exist.
0304: *
0305: * @param name the name to bind; may not be empty
0306: * @exception NameNotFoundException if an intermediate context does not
0307: * exist
0308: * @exception NamingException if a naming exception is encountered
0309: */
0310: public void unbind(Name name) throws NamingException {
0311: unbind(name.toString());
0312: }
0313:
0314: /**
0315: * Unbinds the named object.
0316: *
0317: * @param name the name to bind; may not be empty
0318: * @exception NameNotFoundException if an intermediate context does not
0319: * exist
0320: * @exception NamingException if a naming exception is encountered
0321: */
0322: public abstract void unbind(String name) throws NamingException;
0323:
0324: /**
0325: * Binds a new name to the object bound to an old name, and unbinds the
0326: * old name. Both names are relative to this context. Any attributes
0327: * associated with the old name become associated with the new name.
0328: * Intermediate contexts of the old name are not changed.
0329: *
0330: * @param oldName the name of the existing binding; may not be empty
0331: * @param newName the name of the new binding; may not be empty
0332: * @exception NameAlreadyBoundException if newName is already bound
0333: * @exception NamingException if a naming exception is encountered
0334: */
0335: public void rename(Name oldName, Name newName)
0336: throws NamingException {
0337: rename(oldName.toString(), newName.toString());
0338: }
0339:
0340: /**
0341: * Binds a new name to the object bound to an old name, and unbinds the
0342: * old name.
0343: *
0344: * @param oldName the name of the existing binding; may not be empty
0345: * @param newName the name of the new binding; may not be empty
0346: * @exception NameAlreadyBoundException if newName is already bound
0347: * @exception NamingException if a naming exception is encountered
0348: */
0349: public abstract void rename(String oldName, String newName)
0350: throws NamingException;
0351:
0352: /**
0353: * Enumerates the names bound in the named context, along with the class
0354: * names of objects bound to them. The contents of any subcontexts are
0355: * not included.
0356: * <p>
0357: * If a binding is added to or removed from this context, its effect on
0358: * an enumeration previously returned is undefined.
0359: *
0360: * @param name the name of the context to list
0361: * @return an enumeration of the names and class names of the bindings in
0362: * this context. Each element of the enumeration is of type NameClassPair.
0363: * @exception NamingException if a naming exception is encountered
0364: */
0365: public NamingEnumeration list(Name name) throws NamingException {
0366: return list(name.toString());
0367: }
0368:
0369: /**
0370: * Enumerates the names bound in the named context, along with the class
0371: * names of objects bound to them.
0372: *
0373: * @param name the name of the context to list
0374: * @return an enumeration of the names and class names of the bindings in
0375: * this context. Each element of the enumeration is of type NameClassPair.
0376: * @exception NamingException if a naming exception is encountered
0377: */
0378: public abstract NamingEnumeration list(String name)
0379: throws NamingException;
0380:
0381: /**
0382: * Enumerates the names bound in the named context, along with the
0383: * objects bound to them. The contents of any subcontexts are not
0384: * included.
0385: * <p>
0386: * If a binding is added to or removed from this context, its effect on
0387: * an enumeration previously returned is undefined.
0388: *
0389: * @param name the name of the context to list
0390: * @return an enumeration of the bindings in this context.
0391: * Each element of the enumeration is of type Binding.
0392: * @exception NamingException if a naming exception is encountered
0393: */
0394: public NamingEnumeration listBindings(Name name)
0395: throws NamingException {
0396: return listBindings(name.toString());
0397: }
0398:
0399: /**
0400: * Enumerates the names bound in the named context, along with the
0401: * objects bound to them.
0402: *
0403: * @param name the name of the context to list
0404: * @return an enumeration of the bindings in this context.
0405: * Each element of the enumeration is of type Binding.
0406: * @exception NamingException if a naming exception is encountered
0407: */
0408: public abstract NamingEnumeration listBindings(String name)
0409: throws NamingException;
0410:
0411: /**
0412: * Destroys the named context and removes it from the namespace. Any
0413: * attributes associated with the name are also removed. Intermediate
0414: * contexts are not destroyed.
0415: * <p>
0416: * This method is idempotent. It succeeds even if the terminal atomic
0417: * name is not bound in the target context, but throws
0418: * NameNotFoundException if any of the intermediate contexts do not exist.
0419: *
0420: * In a federated naming system, a context from one naming system may be
0421: * bound to a name in another. One can subsequently look up and perform
0422: * operations on the foreign context using a composite name. However, an
0423: * attempt destroy the context using this composite name will fail with
0424: * NotContextException, because the foreign context is not a "subcontext"
0425: * of the context in which it is bound. Instead, use unbind() to remove
0426: * the binding of the foreign context. Destroying the foreign context
0427: * requires that the destroySubcontext() be performed on a context from
0428: * the foreign context's "native" naming system.
0429: *
0430: * @param name the name of the context to be destroyed; may not be empty
0431: * @exception NameNotFoundException if an intermediate context does not
0432: * exist
0433: * @exception NotContextException if the name is bound but does not name
0434: * a context, or does not name a context of the appropriate type
0435: */
0436: public void destroySubcontext(Name name) throws NamingException {
0437: destroySubcontext(name.toString());
0438: }
0439:
0440: /**
0441: * Destroys the named context and removes it from the namespace.
0442: *
0443: * @param name the name of the context to be destroyed; may not be empty
0444: * @exception NameNotFoundException if an intermediate context does not
0445: * exist
0446: * @exception NotContextException if the name is bound but does not name
0447: * a context, or does not name a context of the appropriate type
0448: */
0449: public abstract void destroySubcontext(String name)
0450: throws NamingException;
0451:
0452: /**
0453: * Creates and binds a new context. Creates a new context with the given
0454: * name and binds it in the target context (that named by all but
0455: * terminal atomic component of the name). All intermediate contexts and
0456: * the target context must already exist.
0457: *
0458: * @param name the name of the context to create; may not be empty
0459: * @return the newly created context
0460: * @exception NameAlreadyBoundException if name is already bound
0461: * @exception InvalidAttributesException if creation of the subcontext
0462: * requires specification of mandatory attributes
0463: * @exception NamingException if a naming exception is encountered
0464: */
0465: public Context createSubcontext(Name name) throws NamingException {
0466: return createSubcontext(name.toString());
0467: }
0468:
0469: /**
0470: * Creates and binds a new context.
0471: *
0472: * @param name the name of the context to create; may not be empty
0473: * @return the newly created context
0474: * @exception NameAlreadyBoundException if name is already bound
0475: * @exception InvalidAttributesException if creation of the subcontext
0476: * requires specification of mandatory attributes
0477: * @exception NamingException if a naming exception is encountered
0478: */
0479: public Context createSubcontext(String name) throws NamingException {
0480: return createSubcontext(name, null);
0481: }
0482:
0483: /**
0484: * Retrieves the named object, following links except for the terminal
0485: * atomic component of the name. If the object bound to name is not a
0486: * link, returns the object itself.
0487: *
0488: * @param name the name of the object to look up
0489: * @return the object bound to name, not following the terminal link
0490: * (if any).
0491: * @exception NamingException if a naming exception is encountered
0492: */
0493: public Object lookupLink(Name name) throws NamingException {
0494: return lookupLink(name.toString());
0495: }
0496:
0497: /**
0498: * Retrieves the named object, following links except for the terminal
0499: * atomic component of the name.
0500: *
0501: * @param name the name of the object to look up
0502: * @return the object bound to name, not following the terminal link
0503: * (if any).
0504: * @exception NamingException if a naming exception is encountered
0505: */
0506: public abstract Object lookupLink(String name)
0507: throws NamingException;
0508:
0509: /**
0510: * Retrieves the parser associated with the named context. In a
0511: * federation of namespaces, different naming systems will parse names
0512: * differently. This method allows an application to get a parser for
0513: * parsing names into their atomic components using the naming convention
0514: * of a particular naming system. Within any single naming system,
0515: * NameParser objects returned by this method must be equal (using the
0516: * equals() test).
0517: *
0518: * @param name the name of the context from which to get the parser
0519: * @return a name parser that can parse compound names into their atomic
0520: * components
0521: * @exception NamingException if a naming exception is encountered
0522: */
0523: public NameParser getNameParser(Name name) throws NamingException {
0524: return new NameParserImpl();
0525: }
0526:
0527: /**
0528: * Retrieves the parser associated with the named context.
0529: *
0530: * @param name the name of the context from which to get the parser
0531: * @return a name parser that can parse compound names into their atomic
0532: * components
0533: * @exception NamingException if a naming exception is encountered
0534: */
0535: public NameParser getNameParser(String name) throws NamingException {
0536: return new NameParserImpl();
0537: }
0538:
0539: /**
0540: * Composes the name of this context with a name relative to this context.
0541: * <p>
0542: * Given a name (name) relative to this context, and the name (prefix)
0543: * of this context relative to one of its ancestors, this method returns
0544: * the composition of the two names using the syntax appropriate for the
0545: * naming system(s) involved. That is, if name names an object relative
0546: * to this context, the result is the name of the same object, but
0547: * relative to the ancestor context. None of the names may be null.
0548: *
0549: * @param name a name relative to this context
0550: * @param prefix the name of this context relative to one of its ancestors
0551: * @return the composition of prefix and name
0552: * @exception NamingException if a naming exception is encountered
0553: */
0554: public Name composeName(Name name, Name prefix)
0555: throws NamingException {
0556: prefix = (Name) name.clone();
0557: return prefix.addAll(name);
0558: }
0559:
0560: /**
0561: * Composes the name of this context with a name relative to this context.
0562: *
0563: * @param name a name relative to this context
0564: * @param prefix the name of this context relative to one of its ancestors
0565: * @return the composition of prefix and name
0566: * @exception NamingException if a naming exception is encountered
0567: */
0568: public String composeName(String name, String prefix)
0569: throws NamingException {
0570: return prefix + "/" + name;
0571: }
0572:
0573: /**
0574: * Adds a new environment property to the environment of this context. If
0575: * the property already exists, its value is overwritten.
0576: *
0577: * @param propName the name of the environment property to add; may not
0578: * be null
0579: * @param propVal the value of the property to add; may not be null
0580: * @exception NamingException if a naming exception is encountered
0581: */
0582: public Object addToEnvironment(String propName, Object propVal)
0583: throws NamingException {
0584: return env.put(propName, propVal);
0585: }
0586:
0587: /**
0588: * Removes an environment property from the environment of this context.
0589: *
0590: * @param propName the name of the environment property to remove;
0591: * may not be null
0592: * @exception NamingException if a naming exception is encountered
0593: */
0594: public Object removeFromEnvironment(String propName)
0595: throws NamingException {
0596: return env.remove(propName);
0597: }
0598:
0599: /**
0600: * Retrieves the environment in effect for this context. See class
0601: * description for more details on environment properties.
0602: * The caller should not make any changes to the object returned: their
0603: * effect on the context is undefined. The environment of this context
0604: * may be changed using addToEnvironment() and removeFromEnvironment().
0605: *
0606: * @return the environment of this context; never null
0607: * @exception NamingException if a naming exception is encountered
0608: */
0609: public Hashtable getEnvironment() throws NamingException {
0610: return env;
0611: }
0612:
0613: /**
0614: * Closes this context. This method releases this context's resources
0615: * immediately, instead of waiting for them to be released automatically
0616: * by the garbage collector.
0617: * This method is idempotent: invoking it on a context that has already
0618: * been closed has no effect. Invoking any other method on a closed
0619: * context is not allowed, and results in undefined behaviour.
0620: *
0621: * @exception NamingException if a naming exception is encountered
0622: */
0623: public void close() throws NamingException {
0624: env.clear();
0625: }
0626:
0627: /**
0628: * Retrieves the full name of this context within its own namespace.
0629: * <p>
0630: * Many naming services have a notion of a "full name" for objects in
0631: * their respective namespaces. For example, an LDAP entry has a
0632: * distinguished name, and a DNS record has a fully qualified name. This
0633: * method allows the client application to retrieve this name. The string
0634: * returned by this method is not a JNDI composite name and should not be
0635: * passed directly to context methods. In naming systems for which the
0636: * notion of full name does not make sense,
0637: * OperationNotSupportedException is thrown.
0638: *
0639: * @return this context's name in its own namespace; never null
0640: * @exception OperationNotSupportedException if the naming system does
0641: * not have the notion of a full name
0642: * @exception NamingException if a naming exception is encountered
0643: */
0644: public abstract String getNameInNamespace() throws NamingException;
0645:
0646: // ----------------------------------------------------- DirContext Methods
0647:
0648: /**
0649: * Retrieves all of the attributes associated with a named object.
0650: *
0651: * @return the set of attributes associated with name.
0652: * Returns an empty attribute set if name has no attributes; never null.
0653: * @param name the name of the object from which to retrieve attributes
0654: * @exception NamingException if a naming exception is encountered
0655: */
0656: public Attributes getAttributes(Name name) throws NamingException {
0657: return getAttributes(name.toString());
0658: }
0659:
0660: /**
0661: * Retrieves all of the attributes associated with a named object.
0662: *
0663: * @return the set of attributes associated with name
0664: * @param name the name of the object from which to retrieve attributes
0665: * @exception NamingException if a naming exception is encountered
0666: */
0667: public Attributes getAttributes(String name) throws NamingException {
0668: return getAttributes(name, null);
0669: }
0670:
0671: /**
0672: * Retrieves selected attributes associated with a named object.
0673: * See the class description regarding attribute models, attribute type
0674: * names, and operational attributes.
0675: *
0676: * @return the requested attributes; never null
0677: * @param name the name of the object from which to retrieve attributes
0678: * @param attrIds the identifiers of the attributes to retrieve. null
0679: * indicates that all attributes should be retrieved; an empty array
0680: * indicates that none should be retrieved
0681: * @exception NamingException if a naming exception is encountered
0682: */
0683: public Attributes getAttributes(Name name, String[] attrIds)
0684: throws NamingException {
0685: return getAttributes(name.toString(), attrIds);
0686: }
0687:
0688: /**
0689: * Retrieves selected attributes associated with a named object.
0690: *
0691: * @return the requested attributes; never null
0692: * @param name the name of the object from which to retrieve attributes
0693: * @param attrIds the identifiers of the attributes to retrieve. null
0694: * indicates that all attributes should be retrieved; an empty array
0695: * indicates that none should be retrieved
0696: * @exception NamingException if a naming exception is encountered
0697: */
0698: public abstract Attributes getAttributes(String name,
0699: String[] attrIds) throws NamingException;
0700:
0701: /**
0702: * Modifies the attributes associated with a named object. The order of
0703: * the modifications is not specified. Where possible, the modifications
0704: * are performed atomically.
0705: *
0706: * @param name the name of the object whose attributes will be updated
0707: * @param mod_op the modification operation, one of: ADD_ATTRIBUTE,
0708: * REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE
0709: * @param attrs the attributes to be used for the modification; may not
0710: * be null
0711: * @exception AttributeModificationException if the modification cannot be
0712: * completed successfully
0713: * @exception NamingException if a naming exception is encountered
0714: */
0715: public void modifyAttributes(Name name, int mod_op, Attributes attrs)
0716: throws NamingException {
0717: modifyAttributes(name.toString(), mod_op, attrs);
0718: }
0719:
0720: /**
0721: * Modifies the attributes associated with a named object.
0722: *
0723: * @param name the name of the object whose attributes will be updated
0724: * @param mod_op the modification operation, one of: ADD_ATTRIBUTE,
0725: * REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE
0726: * @param attrs the attributes to be used for the modification; may not
0727: * be null
0728: * @exception AttributeModificationException if the modification cannot be
0729: * completed successfully
0730: * @exception NamingException if a naming exception is encountered
0731: */
0732: public abstract void modifyAttributes(String name, int mod_op,
0733: Attributes attrs) throws NamingException;
0734:
0735: /**
0736: * Modifies the attributes associated with a named object using an an
0737: * ordered list of modifications. The modifications are performed in the
0738: * order specified. Each modification specifies a modification operation
0739: * code and an attribute on which to operate. Where possible, the
0740: * modifications are performed atomically.
0741: *
0742: * @param name the name of the object whose attributes will be updated
0743: * @param mods an ordered sequence of modifications to be performed; may
0744: * not be null
0745: * @exception AttributeModificationException if the modification cannot be
0746: * completed successfully
0747: * @exception NamingException if a naming exception is encountered
0748: */
0749: public void modifyAttributes(Name name, ModificationItem[] mods)
0750: throws NamingException {
0751: modifyAttributes(name.toString(), mods);
0752: }
0753:
0754: /**
0755: * Modifies the attributes associated with a named object using an an
0756: * ordered list of modifications.
0757: *
0758: * @param name the name of the object whose attributes will be updated
0759: * @param mods an ordered sequence of modifications to be performed; may
0760: * not be null
0761: * @exception AttributeModificationException if the modification cannot be
0762: * completed successfully
0763: * @exception NamingException if a naming exception is encountered
0764: */
0765: public abstract void modifyAttributes(String name,
0766: ModificationItem[] mods) throws NamingException;
0767:
0768: /**
0769: * Binds a name to an object, along with associated attributes. If attrs
0770: * is null, the resulting binding will have the attributes associated
0771: * with obj if obj is a DirContext, and no attributes otherwise. If attrs
0772: * is non-null, the resulting binding will have attrs as its attributes;
0773: * any attributes associated with obj are ignored.
0774: *
0775: * @param name the name to bind; may not be empty
0776: * @param obj the object to bind; possibly null
0777: * @param attrs the attributes to associate with the binding
0778: * @exception NameAlreadyBoundException if name is already bound
0779: * @exception InvalidAttributesException if some "mandatory" attributes
0780: * of the binding are not supplied
0781: * @exception NamingException if a naming exception is encountered
0782: */
0783: public void bind(Name name, Object obj, Attributes attrs)
0784: throws NamingException {
0785: bind(name.toString(), obj, attrs);
0786: }
0787:
0788: /**
0789: * Binds a name to an object, along with associated attributes.
0790: *
0791: * @param name the name to bind; may not be empty
0792: * @param obj the object to bind; possibly null
0793: * @param attrs the attributes to associate with the binding
0794: * @exception NameAlreadyBoundException if name is already bound
0795: * @exception InvalidAttributesException if some "mandatory" attributes
0796: * of the binding are not supplied
0797: * @exception NamingException if a naming exception is encountered
0798: */
0799: public abstract void bind(String name, Object obj, Attributes attrs)
0800: throws NamingException;
0801:
0802: /**
0803: * Binds a name to an object, along with associated attributes,
0804: * overwriting any existing binding. If attrs is null and obj is a
0805: * DirContext, the attributes from obj are used. If attrs is null and obj
0806: * is not a DirContext, any existing attributes associated with the object
0807: * already bound in the directory remain unchanged. If attrs is non-null,
0808: * any existing attributes associated with the object already bound in
0809: * the directory are removed and attrs is associated with the named
0810: * object. If obj is a DirContext and attrs is non-null, the attributes
0811: * of obj are ignored.
0812: *
0813: * @param name the name to bind; may not be empty
0814: * @param obj the object to bind; possibly null
0815: * @param attrs the attributes to associate with the binding
0816: * @exception InvalidAttributesException if some "mandatory" attributes
0817: * of the binding are not supplied
0818: * @exception NamingException if a naming exception is encountered
0819: */
0820: public void rebind(Name name, Object obj, Attributes attrs)
0821: throws NamingException {
0822: rebind(name.toString(), obj, attrs);
0823: }
0824:
0825: /**
0826: * Binds a name to an object, along with associated attributes,
0827: * overwriting any existing binding.
0828: *
0829: * @param name the name to bind; may not be empty
0830: * @param obj the object to bind; possibly null
0831: * @param attrs the attributes to associate with the binding
0832: * @exception InvalidAttributesException if some "mandatory" attributes
0833: * of the binding are not supplied
0834: * @exception NamingException if a naming exception is encountered
0835: */
0836: public abstract void rebind(String name, Object obj,
0837: Attributes attrs) throws NamingException;
0838:
0839: /**
0840: * Creates and binds a new context, along with associated attributes.
0841: * This method creates a new subcontext with the given name, binds it in
0842: * the target context (that named by all but terminal atomic component of
0843: * the name), and associates the supplied attributes with the newly
0844: * created object. All intermediate and target contexts must already
0845: * exist. If attrs is null, this method is equivalent to
0846: * Context.createSubcontext().
0847: *
0848: * @param name the name of the context to create; may not be empty
0849: * @param attrs the attributes to associate with the newly created context
0850: * @return the newly created context
0851: * @exception NameAlreadyBoundException if the name is already bound
0852: * @exception InvalidAttributesException if attrs does not contain all
0853: * the mandatory attributes required for creation
0854: * @exception NamingException if a naming exception is encountered
0855: */
0856: public DirContext createSubcontext(Name name, Attributes attrs)
0857: throws NamingException {
0858: return createSubcontext(name.toString(), attrs);
0859: }
0860:
0861: /**
0862: * Creates and binds a new context, along with associated attributes.
0863: *
0864: * @param name the name of the context to create; may not be empty
0865: * @param attrs the attributes to associate with the newly created context
0866: * @return the newly created context
0867: * @exception NameAlreadyBoundException if the name is already bound
0868: * @exception InvalidAttributesException if attrs does not contain all
0869: * the mandatory attributes required for creation
0870: * @exception NamingException if a naming exception is encountered
0871: */
0872: public abstract DirContext createSubcontext(String name,
0873: Attributes attrs) throws NamingException;
0874:
0875: /**
0876: * Retrieves the schema associated with the named object. The schema
0877: * describes rules regarding the structure of the namespace and the
0878: * attributes stored within it. The schema specifies what types of
0879: * objects can be added to the directory and where they can be added;
0880: * what mandatory and optional attributes an object can have. The range
0881: * of support for schemas is directory-specific.
0882: *
0883: * @param name the name of the object whose schema is to be retrieved
0884: * @return the schema associated with the context; never null
0885: * @exception OperationNotSupportedException if schema not supported
0886: * @exception NamingException if a naming exception is encountered
0887: */
0888: public DirContext getSchema(Name name) throws NamingException {
0889: return getSchema(name.toString());
0890: }
0891:
0892: /**
0893: * Retrieves the schema associated with the named object.
0894: *
0895: * @param name the name of the object whose schema is to be retrieved
0896: * @return the schema associated with the context; never null
0897: * @exception OperationNotSupportedException if schema not supported
0898: * @exception NamingException if a naming exception is encountered
0899: */
0900: public abstract DirContext getSchema(String name)
0901: throws NamingException;
0902:
0903: /**
0904: * Retrieves a context containing the schema objects of the named
0905: * object's class definitions.
0906: *
0907: * @param name the name of the object whose object class definition is to
0908: * be retrieved
0909: * @return the DirContext containing the named object's class
0910: * definitions; never null
0911: * @exception OperationNotSupportedException if schema not supported
0912: * @exception NamingException if a naming exception is encountered
0913: */
0914: public DirContext getSchemaClassDefinition(Name name)
0915: throws NamingException {
0916: return getSchemaClassDefinition(name.toString());
0917: }
0918:
0919: /**
0920: * Retrieves a context containing the schema objects of the named
0921: * object's class definitions.
0922: *
0923: * @param name the name of the object whose object class definition is to
0924: * be retrieved
0925: * @return the DirContext containing the named object's class
0926: * definitions; never null
0927: * @exception OperationNotSupportedException if schema not supported
0928: * @exception NamingException if a naming exception is encountered
0929: */
0930: public abstract DirContext getSchemaClassDefinition(String name)
0931: throws NamingException;
0932:
0933: /**
0934: * Searches in a single context for objects that contain a specified set
0935: * of attributes, and retrieves selected attributes. The search is
0936: * performed using the default SearchControls settings.
0937: *
0938: * @param name the name of the context to search
0939: * @param matchingAttributes the attributes to search for. If empty or
0940: * null, all objects in the target context are returned.
0941: * @param attributesToReturn the attributes to return. null indicates
0942: * that all attributes are to be returned; an empty array indicates that
0943: * none are to be returned.
0944: * @return a non-null enumeration of SearchResult objects. Each
0945: * SearchResult contains the attributes identified by attributesToReturn
0946: * and the name of the corresponding object, named relative to the
0947: * context named by name.
0948: * @exception NamingException if a naming exception is encountered
0949: */
0950: public NamingEnumeration search(Name name,
0951: Attributes matchingAttributes, String[] attributesToReturn)
0952: throws NamingException {
0953: return search(name.toString(), matchingAttributes,
0954: attributesToReturn);
0955: }
0956:
0957: /**
0958: * Searches in a single context for objects that contain a specified set
0959: * of attributes, and retrieves selected attributes.
0960: *
0961: * @param name the name of the context to search
0962: * @param matchingAttributes the attributes to search for. If empty or
0963: * null, all objects in the target context are returned.
0964: * @param attributesToReturn the attributes to return. null indicates
0965: * that all attributes are to be returned; an empty array indicates that
0966: * none are to be returned.
0967: * @return a non-null enumeration of SearchResult objects. Each
0968: * SearchResult contains the attributes identified by attributesToReturn
0969: * and the name of the corresponding object, named relative to the
0970: * context named by name.
0971: * @exception NamingException if a naming exception is encountered
0972: */
0973: public abstract NamingEnumeration search(String name,
0974: Attributes matchingAttributes, String[] attributesToReturn)
0975: throws NamingException;
0976:
0977: /**
0978: * Searches in a single context for objects that contain a specified set
0979: * of attributes. This method returns all the attributes of such objects.
0980: * It is equivalent to supplying null as the atributesToReturn parameter
0981: * to the method search(Name, Attributes, String[]).
0982: *
0983: * @param name the name of the context to search
0984: * @param matchingAttributes the attributes to search for. If empty or
0985: * null, all objects in the target context are returned.
0986: * @return a non-null enumeration of SearchResult objects. Each
0987: * SearchResult contains the attributes identified by attributesToReturn
0988: * and the name of the corresponding object, named relative to the
0989: * context named by name.
0990: * @exception NamingException if a naming exception is encountered
0991: */
0992: public NamingEnumeration search(Name name,
0993: Attributes matchingAttributes) throws NamingException {
0994: return search(name.toString(), matchingAttributes);
0995: }
0996:
0997: /**
0998: * Searches in a single context for objects that contain a specified set
0999: * of attributes.
1000: *
1001: * @param name the name of the context to search
1002: * @param matchingAttributes the attributes to search for. If empty or
1003: * null, all objects in the target context are returned.
1004: * @return a non-null enumeration of SearchResult objects. Each
1005: * SearchResult contains the attributes identified by attributesToReturn
1006: * and the name of the corresponding object, named relative to the
1007: * context named by name.
1008: * @exception NamingException if a naming exception is encountered
1009: */
1010: public abstract NamingEnumeration search(String name,
1011: Attributes matchingAttributes) throws NamingException;
1012:
1013: /**
1014: * Searches in the named context or object for entries that satisfy the
1015: * given search filter. Performs the search as specified by the search
1016: * controls.
1017: *
1018: * @param name the name of the context or object to search
1019: * @param filter the filter expression to use for the search; may not be
1020: * null
1021: * @param cons the search controls that control the search. If null,
1022: * the default search controls are used (equivalent to
1023: * (new SearchControls())).
1024: * @return an enumeration of SearchResults of the objects that satisfy
1025: * the filter; never null
1026: * @exception InvalidSearchFilterException if the search filter specified
1027: * is not supported or understood by the underlying directory
1028: * @exception InvalidSearchControlsException if the search controls
1029: * contain invalid settings
1030: * @exception NamingException if a naming exception is encountered
1031: */
1032: public NamingEnumeration search(Name name, String filter,
1033: SearchControls cons) throws NamingException {
1034: return search(name.toString(), filter, cons);
1035: }
1036:
1037: /**
1038: * Searches in the named context or object for entries that satisfy the
1039: * given search filter. Performs the search as specified by the search
1040: * controls.
1041: *
1042: * @param name the name of the context or object to search
1043: * @param filter the filter expression to use for the search; may not be
1044: * null
1045: * @param cons the search controls that control the search. If null,
1046: * the default search controls are used (equivalent to
1047: * (new SearchControls())).
1048: * @return an enumeration of SearchResults of the objects that satisfy
1049: * the filter; never null
1050: * @exception InvalidSearchFilterException if the search filter
1051: * specified is not supported or understood by the underlying directory
1052: * @exception InvalidSearchControlsException if the search controls
1053: * contain invalid settings
1054: * @exception NamingException if a naming exception is encountered
1055: */
1056: public abstract NamingEnumeration search(String name,
1057: String filter, SearchControls cons) throws NamingException;
1058:
1059: /**
1060: * Searches in the named context or object for entries that satisfy the
1061: * given search filter. Performs the search as specified by the search
1062: * controls.
1063: *
1064: * @param name the name of the context or object to search
1065: * @param filterExpr the filter expression to use for the search.
1066: * The expression may contain variables of the form "{i}" where i is a
1067: * nonnegative integer. May not be null.
1068: * @param filterArgs the array of arguments to substitute for the
1069: * variables in filterExpr. The value of filterArgs[i] will replace each
1070: * occurrence of "{i}". If null, equivalent to an empty array.
1071: * @param cons the search controls that control the search. If null, the
1072: * default search controls are used (equivalent to (new SearchControls())).
1073: * @return an enumeration of SearchResults of the objects that satisy the
1074: * filter; never null
1075: * @exception ArrayIndexOutOfBoundsException if filterExpr contains {i}
1076: * expressions where i is outside the bounds of the array filterArgs
1077: * @exception InvalidSearchControlsException if cons contains invalid
1078: * settings
1079: * @exception InvalidSearchFilterException if filterExpr with filterArgs
1080: * represents an invalid search filter
1081: * @exception NamingException if a naming exception is encountered
1082: */
1083: public NamingEnumeration search(Name name, String filterExpr,
1084: Object[] filterArgs, SearchControls cons)
1085: throws NamingException {
1086: return search(name.toString(), filterExpr, filterArgs, cons);
1087: }
1088:
1089: /**
1090: * Searches in the named context or object for entries that satisfy the
1091: * given search filter. Performs the search as specified by the search
1092: * controls.
1093: *
1094: * @param name the name of the context or object to search
1095: * @param filterExpr the filter expression to use for the search.
1096: * The expression may contain variables of the form "{i}" where i is a
1097: * nonnegative integer. May not be null.
1098: * @param filterArgs the array of arguments to substitute for the
1099: * variables in filterExpr. The value of filterArgs[i] will replace each
1100: * occurrence of "{i}". If null, equivalent to an empty array.
1101: * @param cons the search controls that control the search. If null, the
1102: * default search controls are used (equivalent to (new SearchControls())).
1103: * @return an enumeration of SearchResults of the objects that satisy the
1104: * filter; never null
1105: * @exception ArrayIndexOutOfBoundsException if filterExpr contains {i}
1106: * expressions where i is outside the bounds of the array filterArgs
1107: * @exception InvalidSearchControlsException if cons contains invalid
1108: * settings
1109: * @exception InvalidSearchFilterException if filterExpr with filterArgs
1110: * represents an invalid search filter
1111: * @exception NamingException if a naming exception is encountered
1112: */
1113: public abstract NamingEnumeration search(String name,
1114: String filterExpr, Object[] filterArgs, SearchControls cons)
1115: throws NamingException;
1116:
1117: // ------------------------------------------------------ Protected Methods
1118:
1119: }
|