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