-/* Context.java --
- Copyright (C) 2000 Free Software Foundation, Inc.
+/* Context.java -- A naming context
+ Copyright (C) 2000, 2006 Free Software Foundation, Inc.
This file is part of GNU Classpath.
import java.util.Hashtable;
+import javax.naming.directory.InvalidAttributesException;
+
public interface Context
{
- // Property with name of the inital context factory to use
- String INITIAL_CONTEXT_FACTORY
- = "java.naming.factory.initial";
-
- // Property with colon-separated list of object factories to use.
- String OBJECT_FACTORIES
- = "java.naming.factory.object";
-
- // Property with colon-separated list of state factories to use.
- String STATE_FACTORIES
- = "java.naming.factory.state";
-
- // Property with colon-separated list of package prefixes to use.
- String URL_PKG_PREFIXES
- = "java.naming.factory.url.pkgs";
-
- // Property with URL specifying configuration for the service
- // provider to use.
- String PROVIDER_URL
- = "java.naming.provider.url";
+ /**
+ * Property with name of the inital context factory to use
+ */
+ String INITIAL_CONTEXT_FACTORY = "java.naming.factory.initial";
+
+ /**
+ * Property with colon-separated list of object factories to use.
+ */
+ String OBJECT_FACTORIES = "java.naming.factory.object";
+
+ /**
+ * Property with colon-separated list of state factories to use.
+ */
+ String STATE_FACTORIES = "java.naming.factory.state";
+
+ /**
+ * Property with colon-separated list of package prefixes to use.
+ */
+ String URL_PKG_PREFIXES = "java.naming.factory.url.pkgs";
+
+ /**
+ * Property with URL specifying configuration for the service provider to use.
+ */
+ String PROVIDER_URL = "java.naming.provider.url";
+
+ /**
+ * Property with the DNS host and domain names to use.
+ */
+ String DNS_URL = "java.naming.dns.url";
+
+ /**
+ * Property with the authoritativeness of the service requested.
+ */
+ String AUTHORITATIVE = "java.naming.authoritative";
+
+ /**
+ * Property with the batch size to use when returning data via the service's
+ * protocol.
+ */
+ String BATCHSIZE = "java.naming.batchsize";
+
+ /**
+ * Property defining how referrals encountered by the service provider are to
+ * be processed.
+ */
+ String REFERRAL = "java.naming.referral";
+
+ /**
+ * Property specifying the security protocol to use.
+ */
+ String SECURITY_PROTOCOL = "java.naming.security.protocol";
+
+ /**
+ * Property specifying the security level to use.
+ */
+ String SECURITY_AUTHENTICATION = "java.naming.security.authentication";
+
+ /**
+ * Property for the identity of the principal for authenticating the caller to
+ * the service.
+ */
+ String SECURITY_PRINCIPAL = "java.naming.security.principal";
+
+ /**
+ * Property specifying the credentials of the principal for authenticating the
+ * caller to the service.
+ */
+ String SECURITY_CREDENTIALS = "java.naming.security.credentials";
+
+ /**
+ * Property for specifying the preferred language to use with the service.
+ */
+ String LANGUAGE = "java.naming.language";
+
+ /**
+ * Property for the initial context constructor to use when searching for
+ * other properties.
+ */
+ String APPLET = "java.naming.applet";
+
+ /**
+ * Give the specified name for the specified object. The passed name must not
+ * be already bound to some other object.
+ *
+ * @param name the name that will be given to the object (in the scope of this
+ * context).
+ * @param obj the object being named.
+ * @throws NameAlreadyBoundException if this name is already used to name some
+ * object.
+ * @throws InvalidAttributesException if the object does not supply all
+ * required attributes.
+ * @throws NamingException if the naming operation has failed due other
+ * reasons.
+ */
+ void bind(Name name, Object obj) throws NamingException;
+
+ /**
+ * Give the specified name for the specified object. The passed name must not
+ * be already bound to some other object.
+ *
+ * @param name the name that will be given to the object (in the scope of this
+ * context).
+ * @param obj the object being named.
+ * @throws NameAlreadyBoundException if this name is already used to name some
+ * object.
+ * @throws InvalidAttributesException if the object does not supply all
+ * required attributes.
+ * @throws NamingException if the naming operation has failed due other
+ * reasons.
+ */
+ void bind(String name, Object obj) throws NamingException;
+
+ /**
+ * Gets the previously named object by name. If the passed name is empty, the
+ * method should return a cloned instance of this naming context.
+ *
+ * @param name the name of the object being searched in this context
+ * @return the named object
+ * @throws NamingException if the naming fails.
+ */
+ Object lookup(Name name) throws NamingException;
+
+ /**
+ * Gets the previously named object by name. If the passed name is empty, the
+ * method should return a cloned instance of this naming context.
+ *
+ * @param name the name of the object being searched in this context
+ * @return the named object
+ * @throws NamingException if the naming fails.
+ */
+ Object lookup(String name) throws NamingException;
+
+ /**
+ * Give the specified name for the specified object. Unlike bind, this method
+ * silently replaces the existing binding for this name, if one exists.
+ *
+ * @param name the name that will be given to the object (in the scope of this
+ * context).
+ * @param obj the object being named.
+ * @throws InvalidAttributesException if the object does not supply all
+ * required attributes.
+ * @throws NamingException if the naming operation has failed due other
+ * reasons.
+ */
+ void rebind(Name name, Object obj) throws NamingException;
+
+ /**
+ * Give the specified name for the specified object. Unlike bind, this method
+ * silently replaces the existing binding for this name, if one exists.
+ *
+ * @param name the name that will be given to the object (in the scope of this
+ * context).
+ * @param obj the object being named.
+ * @throws InvalidAttributesException if the object does not supply all
+ * required attributes.
+ * @throws NamingException if the naming operation has failed due other
+ * reasons.
+ */
+ void rebind(String name, Object obj) throws NamingException;
+
+ /**
+ * Removes the name - object mapping from the current context. This method
+ * returns without action if the name is not bound to an object in the
+ * terminal context, but throws {@link NameNotFoundException} if one of the
+ * intermadiate contexts does not exist.
+ *
+ * @param name the name to be removed
+ * @throws NameNotFoundException if one of the intermediate naming contexts
+ * does not exist. Will not be thrown if just the terminal binding
+ * is missing.
+ * @throws NamingException if the naming operation has failed due other
+ * reasons.
+ */
+ void unbind(Name name) throws NamingException;
+
+ /**
+ * Removes the name - object mapping from the current context. This method
+ * returns without action if the name is not bound to an object in the
+ * terminal context, but throws {@link NameNotFoundException} if one of the
+ * intermadiate contexts does not exist.
+ *
+ * @param name the name to be removed
+ * @throws NameNotFoundException if one of the intermediate naming contexts
+ * does not exist. Will not be thrown if just the terminal binding
+ * is missing.
+ * @throws NamingException if the naming operation has failed due other
+ * reasons.
+ */
+ void unbind(String name) throws NamingException;
+
+ /**
+ * Renames the existing binding, removing the existing and giving the new name
+ * for the same object.
+ *
+ * @param oldName the existing name of the known object
+ * @param newName the new name of the same object
+ * @throws NameNotFoundException if the oldName is unknown for this context
+ * @throws NamingException if the naming operation has failed due other
+ * reasons.
+ */
+ void rename(Name oldName, Name newName) throws NamingException;
+
+ /**
+ * Renames the existing binding, removing the existing and giving the new name
+ * for the same object.
+ *
+ * @param oldName the existing name of the known object
+ * @param newName the new name of the same object
+ * @throws NameNotFoundException if the oldName is unknown for this context
+ * @throws NamingException if the naming operation has failed due other
+ * reasons.
+ */
+ void rename(String oldName, String newName) throws NamingException;
+
+ /**
+ * Creates and returns the enumeration over the name bindings that are present
+ * the given subcontext. The enumeration elements have the type of
+ * {@link NameClassPair}, providing also information about the class of the
+ * bound object. The behaviour in the case if the bindings are added or
+ * removed later is not defined. The contents of the subcontexts are not
+ * included.
+ *
+ * @param name the name of the subcontext
+ * @return the enumeration over the names, known for the given subcontext.
+ * @throws NamingException
+ */
+ NamingEnumeration list(Name name) throws NamingException;
+
+ /**
+ * Creates and returns the enumeration over the name bindings that are present
+ * the given subcontext. The enumeration elements have the type of
+ * {@link NameClassPair}, providing also information about the class of the
+ * bound object. The behaviour in the case if the bindings are added or
+ * removed later is not defined. The contents of the subcontexts are not
+ * included.
+ *
+ * @param name the name of the subcontext
+ * @return the enumeration over the names, known for the given subcontext.
+ * @throws NamingException
+ */
+ NamingEnumeration list(String name) throws NamingException;
+
+ /**
+ * Creates and returns the enumeration over the name - object bindings that
+ * are present the given subcontext. The enumeration elements have the type of
+ * {@link Binding}, providing also information about the class of the bound
+ * object. The behaviour in the case if the bindings are added or removed
+ * later is not defined. The contents of the subcontexts are not included.
+ *
+ * @param name the name of the subcontext
+ * @return the enumeration over the names, known for the given subcontext.
+ * @throws NamingException
+ */
+ NamingEnumeration listBindings(Name name) throws NamingException;
+
+ /**
+ * Creates and returns the enumeration over the name - object bindings that
+ * are present the given subcontext. The enumeration elements have the type of
+ * {@link Binding}, providing also information about the class of the bound
+ * object. The behaviour in the case if the bindings are added or removed
+ * later is not defined. The contents of the subcontexts are not included.
+ *
+ * @param name the name of the subcontext
+ * @return the enumeration over the names, known for the given subcontext.
+ * @throws NamingException
+ */
+ NamingEnumeration listBindings(String name) throws NamingException;
+
+ /**
+ * Creates the new naming subcontext and binds it to the current (this)
+ * context.
+ *
+ * @param name the name of the new context being created
+ * @return the newly created context, bound to the instance of the context on
+ * that the method has been called
+ * @throws NameAlreadyBoundException if this name is already bound
+ * @throws InvalidAttributesException if the creation of the new context
+ * requires the missing mandatory attributes
+ * @throws NamingException
+ */
+ Context createSubcontext(Name name) throws NamingException;
+
+ /**
+ * Creates the new naming subcontext and binds it to the current (this)
+ * context.
+ *
+ * @param name the name of the new context being created
+ * @return the newly created context, bound to the instance of the context on
+ * that the method has been called
+ * @throws NameAlreadyBoundException if this name is already bound
+ * @throws InvalidAttributesException if the creation of the new context
+ * requires the missing mandatory attributes
+ * @throws NamingException
+ */
+ Context createSubcontext(String name) throws NamingException;
+
+ /**
+ * Removes the naming subcontext from this naming context. Returns without
+ * action if such subcontext does not exist. The context being destroyed must
+ * be empty.
+ *
+ * @param name the name of the subcontext beig removed.
+ * @throws ContextNotEmptyException if the named context is not empty.
+ * @throws NamingException
+ */
+ void destroySubcontext(Name name) throws NamingException;
+
+ /**
+ * Removes the naming subcontext from this naming context. Returns without
+ * action if such subcontext does not exist. The context being destroyed must
+ * be empty.
+ *
+ * @param name the name of the subcontext beig removed.
+ * @throws ContextNotEmptyException if the named context is not empty.
+ * @throws NamingException
+ */
+ void destroySubcontext(String name) throws NamingException;
+
+ /**
+ * Retrieves the named object, not following the link of the terminal atomic
+ * component of the name. If the object, named by the passed name, is not a
+ * link, returns that object itself. The intermediate links, if present, are
+ * followed.
+ *
+ * @param name the name of the object that may be a link, leading to another
+ * object.
+ * @return the named object, not following the terminal link (if present).
+ * @throws NamingException
+ */
+ Object lookupLink(Name name) throws NamingException;
+
+ /**
+ * Retrieves the named object, not following the link of the terminal atomic
+ * component of the name. If the object, named by the passed name, is not a
+ * link, returns that object itself. The intermediate links, if present, are
+ * followed.
+ *
+ * @param name the name of the object that may be a link, leading to another
+ * object.
+ * @return the named object, not following the terminal link (if present).
+ * @throws NamingException
+ */
+ Object lookupLink(String name) throws NamingException;
- // Property with the DNS host and domain names to use.
- String DNS_URL
- = "java.naming.dns.url";
+ /**
+ * Obtains the name parser for parsing the names of the given naming
+ * subcontext.
+ *
+ * @param name the name of the subcontext for that the parser must be obtained
+ * @return the parser to parse the names of that context
+ * @throws NamingException
+ */
+ NameParser getNameParser(Name name) throws NamingException;
+
+ /**
+ * Obtains the name parser for parsing the names of the given naming
+ * subcontext.
+ *
+ * @param name the name of the subcontext for that the parser must be obtained
+ * @return the parser to parse the names of that context
+ * @throws NamingException
+ */
+ NameParser getNameParser(String name) throws NamingException;
- // Property with the authoritativeness of the service requested.
- String AUTHORITATIVE
- = "java.naming.authoritative";
+ /**
+ * Composes the name of this context together with another name, related to
+ * this context.
+ *
+ * @param name a name, defined in the scope of this context
+ * @param prefix a name of this context itself, defined in the scope of some
+ * ancestor
+ * @return the name of the same object as named by the first parameter, but
+ * related to the context of the specified ancestor.
+ * @throws NamingException
+ */
+ Name composeName(Name name, Name prefix) throws NamingException;
+
+ /**
+ * Composes the name of this context together with another name, related to
+ * this context.
+ *
+ * @param name a name, defined in the scope of this context
+ * @param prefix a name of this context itself, defined in the scope of some
+ * ancestor
+ * @return the name of the same object as named by the first parameter, but
+ * related to the context of the specified ancestor.
+ * @throws NamingException
+ */
+ String composeName(String name, String prefix) throws NamingException;
- // Property with the batch size to use when returning data via the
- // service's protocol.
- String BATCHSIZE
- = "java.naming.batchsize";
+ /**
+ * Add new environment property to the environment of this context. Both name
+ * and value of the new property must not be null. If the property is already
+ * defined, is current value is replaced by the propVal.
+ *
+ * @param propName the name of the new property
+ * @param propVal the value of the new property
+ * @return the previous value of this property or null if the property has not
+ * been previously defined
+ * @throws NamingException
+ */
+ Object addToEnvironment(String propName, Object propVal)
+ throws NamingException;
- // Property defining how referrals encountered by the service
- // provider are to be processed.
- String REFERRAL
- = "java.naming.referral";
-
- // Property specifying the security protocol to use.
- String SECURITY_PROTOCOL
- = "java.naming.security.protocol";
-
- // Property specifying the security level to use.
- String SECURITY_AUTHENTICATION
- = "java.naming.security.authentication";
-
- // Property for the identity of the principal for authenticating
- // the caller to the service.
- String SECURITY_PRINCIPAL
- = "java.naming.security.principal";
-
- // Property specifying the credentials of the principal for
- // authenticating the caller to the service.
- String SECURITY_CREDENTIALS
- = "java.naming.security.credentials";
-
- // Property for specifying the preferred language to use with the
- // service.
- String LANGUAGE
- = "java.naming.language";
-
- // Property for the initial context constructor to use when searching
- // for other properties.
- String APPLET
- = "java.naming.applet";
-
- void bind (Name name, Object obj) throws NamingException;
- void bind (String name, Object obj) throws NamingException;
-
- Object lookup (Name name) throws NamingException;
- Object lookup (String name) throws NamingException;
-
- void rebind (Name name, Object obj) throws NamingException;
- void rebind (String name, Object obj) throws NamingException;
-
- void unbind (Name name) throws NamingException;
- void unbind (String name) throws NamingException;
-
- void rename (Name oldName, Name newName) throws NamingException;
- void rename (String oldName, String newName) throws NamingException;
-
- NamingEnumeration list (Name name) throws NamingException;
- NamingEnumeration list (String name) throws NamingException;
-
- NamingEnumeration listBindings (Name name) throws NamingException;
- NamingEnumeration listBindings (String name) throws NamingException;
-
- void destroySubcontext (Name name) throws NamingException;
- void destroySubcontext (String name) throws NamingException;
-
- Context createSubcontext (Name name) throws NamingException;
- Context createSubcontext (String name) throws NamingException;
-
- Object lookupLink (Name name) throws NamingException;
- Object lookupLink (String name) throws NamingException;
-
- NameParser getNameParser (Name name) throws NamingException;
- NameParser getNameParser (String name) throws NamingException;
-
- Name composeName (Name name, Name prefix) throws NamingException;
- String composeName (String name,
- String prefix) throws NamingException;
-
- Object addToEnvironment (String propName,
- Object propVal) throws NamingException;
-
- Object removeFromEnvironment (String propName) throws NamingException;
-
- Hashtable getEnvironment () throws NamingException;
-
- void close () throws NamingException;
-
- String getNameInNamespace () throws NamingException;
+ /**
+ * Removes the property with the given name from the environment. Returns
+ * without action if this property is not defined.
+ *
+ * @param propName the name of the property being removed.
+ * @return the value of the property that has been removed or null if the
+ * property was not defined.
+ * @throws NamingException
+ */
+ Object removeFromEnvironment(String propName) throws NamingException;
+
+ /**
+ * Returns the environment, associated with this naming context. The returned
+ * table should never be modified by the caller. Use {@link #addToEnvironment}
+ * and {@link #removeFromEnvironment} to modify the environement, if needed.
+ *
+ * @return the table, representing the environment of this context
+ * @throws NamingException
+ */
+ Hashtable getEnvironment() throws NamingException;
+
+ /**
+ * Releases all resources, associated with this context. The close() method
+ * can be called several times, but after it has been once invoked, it is not
+ * allowed to call any other method of this context,
+ *
+ * @throws NamingException
+ */
+ void close() throws NamingException;
+
+ /**
+ * Returs the full name of this naming context. The returned string is not a
+ * JNDI composite name and should not be passed directly to the methods of the
+ * naming context.
+ *
+ * @return the full name of this naming context, in its own namespace.
+ * @throws OperationNotSupportedException if the naming system, represented by
+ * this context, does not support the notation of the full name.
+ * @throws NamingException
+ */
+ String getNameInNamespace() throws NamingException;
}
-
OSDN Git Service
