diff options
Diffstat (limited to 'libjava/classpath/javax/naming/Context.java')
| -rw-r--r-- | libjava/classpath/javax/naming/Context.java | 558 |
1 files changed, 445 insertions, 113 deletions
diff --git a/libjava/classpath/javax/naming/Context.java b/libjava/classpath/javax/naming/Context.java index 9df82c68490..46b540304b4 100644 --- a/libjava/classpath/javax/naming/Context.java +++ b/libjava/classpath/javax/naming/Context.java @@ -1,5 +1,5 @@ -/* 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. @@ -40,121 +40,453 @@ package javax.naming; 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; } - |