Generated by
JDiff

javax.naming Documentation Differences

This file contains all the changes in documentation in the package javax.naming as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Class AuthenticationException

This exception is thrown when an authentication error occurs while accessing the naming or directory service. An authentication error can happen for example when the credentials supplied by the user program is invalid or otherwise fails to authenticate the user to the naming/directory service.

If the program wants to handle this exception in particular it should catch AuthenticationException explicitly before attempting to catch NamingException. After catching AuthenticationException the program could reattempt the authentication by updating the resolved context's environment properties with the appropriate appropriate credentials.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class AuthenticationNotSupportedException

This exception is thrown when the particular flavor of authentication requested is not supported. For example if the program is attempting to use strong authentication but the directory/naming supports only simple authentication this exception would be thrown. Identification of a particular flavor of authentication is provider- and server-specific. It may be specified using specific authentication schemes such those identified using SASL or a generic authentication specifier (such as "simple" and "strong").

If the program wants to handle this exception in particular it should catch AuthenticationNotSupportedException explicitly before attempting to catch NamingException. After catching AuthenticationNotSupportedException the program could reattempt the authentication using a different authentication flavor by updating the resolved context's environment properties accordingly.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class BinaryRefAddr

This class represents the binary form of the address of a communications end-point.

A BinaryRefAddr consists of a type that describes the communication mechanism and an opaque buffer containing the address description specific to that communication mechanism. The format and interpretation of the address type and the contents of the opaque buffer are based on the agreement of three parties: the client that uses the address the object/server that can be reached using the address and the administrator or program that creates the address.

An example of a binary reference address is an BER X.500 presentation address. Another example of a binary reference address is a serialized form of a service's object handle.

A binary reference address is immutable in the sense that its fields once created cannot be replaced. However it is possible to access the byte array used to hold the opaque buffer. Programs are strongly recommended against changing this byte array. Changes to this byte array need to be explicitly synchronized. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @see RefAddr @see StringRefAddr @since 1.3


Class Binding

This class represents a name-to-object binding found in a context.

A context consists of name-to-object bindings. The Binding class represents such a binding. It consists of a name and an object. The Context.listBindings() method returns an enumeration of Binding.

Use subclassing for naming systems that generate contents of a binding dynamically.

A Binding instance is not synchronized against concurrent access by multiple threads. Threads that need to access a Binding concurrently should synchronize amongst themselves and provide the necessary locking. @author Rosanna Lee @author Scott Seligman @version 1.5 006 01/0212/0203 @since 1.3


Class CannotProceedException

This exception is thrown to indicate that the operation reached a point in the name where the operation cannot proceed any further. When performing an operation on a composite name a naming service provider may reach a part of the name that does not belong to its namespace. At that point it can construct a CannotProceedException and then invoke methods provided by javax.naming.spi.NamingManager (such as getContinuationContext()) to locate another provider to continue the operation. If this is not possible this exception is raised to the caller of the context operation.

If the program wants to handle this exception in particular it should catch CannotProceedException explicitly before attempting to catch NamingException.

A CannotProceedException instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify CannotProceedException should lock the object. @author Rosanna Lee @author Scott Seligman @version 1.7 01/0212/0903 @since 1.3


Class CommunicationException

This exception is thrown when the client is unable to communicate with the directory or naming service. The inability to communicate with the service might be a result of many factors such as network partitioning hardware or interface problems failures on either the client or server side. This exception is meant to be used to capture such communication problems.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class CompositeName

This class represents a composite name -- a sequence of component names spanning multiple namespaces. Each component is a string name from the namespace of a naming system. If the component comes from a hierarchical namespace that component can be further parsed into its atomic parts by using the CompoundName class.

The components of a composite name are numbered. The indexes of a composite name with N components range from 0 up to but not including N. This range may be written as [0 N). The most significant component is at index 0. An empty composite name has no components.

JNDI Composite Name Syntax

JNDI defines a standard string representation for composite names. This representation is the concatenation of the components of a composite name from left to right using the component separator (a forward slash character (/)) to separate each component. The JNDI syntax defines the following meta characters: Any occurrence of a leading quote an escape preceding any meta character an escape at the end of a component or a component separator character in an unquoted component must be preceded by an escape character when that component is being composed into a composite name string. Alternatively to avoid adding escape characters as described the entire component can be quoted using matching single quotes or matching double quotes. A single quote occurring within a double-quoted component is not considered a meta character (and need not be escaped) and vice versa.

When two composite names are compared the case of the characters is significant.

A leading component separator (the composite name string begins with a separator) denotes a leading empty component (a component consisting of an empty string). A trailing component separator (the composite name string ends with a separator) denotes a trailing empty component. Adjacent component separators denote an empty component.

Composite Name Examples

This table shows examples of some composite names. Each row shows the string form of a composite name and its corresponding structural form (CompositeName).

String Name CompositeName
"" {} (the empty name == new CompositeName("") == new CompositeName())
"x" {"x"}
"x/y" {"x" "y"}
"x/" {"x" ""}
"/x" {"" "x"}
"/" {""}
"//" {"" ""}
"/x/" {"" "x" ""}
"x//y" {"x" "" "y"}

Composition Examples

Here are some composition examples. The right column shows composing string composite names while the left column shows composing the corresponding CompositeNames. Notice that composing the string forms of two composite names simply involves concatenating their string forms together.

String Names CompositeNames
"x/y" + "/" = x/y/ {"x" "y"} + {""} = {"x" "y" ""}
"" + "x" = "x" {} + {"x"} = {"x"}
"/" + "x" = "/x" {""} + {"x"} = {"" "x"}
"x" + "" + "" = "x" {"x"} + {} + {} = {"x"}

Multithreaded Access

A CompositeName instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a CompositeName should lock the object. @author Rosanna Lee @author Scott Seligman @version 1.89 01/0212/0903 @since 1.3

Class CompoundName

This class represents a compound name -- a name from a hierarchical name space. Each component in a compound name is an atomic name.

The components of a compound name are numbered. The indexes of a compound name with N components range from 0 up to but not including N. This range may be written as [0 N). The most significant component is at index 0. An empty compound name has no components.

Compound Name Syntax

The syntax of a compound name is specified using a set of properties:
jndi.syntax.direction
Direction for parsing ("right_to_left" "left_to_right" "flat"). If unspecified defaults to "flat" which means the namespace is flat with no hierarchical structure.
jndi.syntax.separator
Separator between atomic name components. Required unless direction is "flat".
jndi.syntax.ignorecase
If present "true" means ignore the case when comparing name components. If its value is not "true" or if the property is not present case is considered when comparing name components.
jndi.syntax.escape
If present specifies the escape string for overriding separator escapes and quotes.
jndi.syntax.beginquote
If present specifies the string delimiting start of a quoted string.
jndi.syntax.endquote
String delimiting end of quoted string. If present specifies the string delimiting the end of a quoted string. If not present use syntax.beginquote as end quote.
jndi.syntax.beginquote2
Alternative set of begin/end quotes.
jndi.syntax.endquote2
Alternative set of begin/end quotes.
jndi.syntax.trimblanks
If present "true" means trim any leading and trailing whitespaces in a name component for comparison purposes. If its value is not "true" or if the property is not present blanks are significant.
jndi.syntax.separator.ava
If present specifies the string that separates attribute-value-assertions when specifying multiple attribute/value pairs. (e.g. " " in age=65 gender=male).
jndi.syntax.separator.typeval
If present specifies the string that separators attribute from value (e.g. "=" in "age=65")
These properties are interpreted according to the following rules:
  1. In a string without quotes or escapes any instance of the separator delimits two atomic names. Each atomic name is referred to as a component.
  2. A separator quote or escape is escaped if preceded immediately (on the left) by the escape.
  3. If there are two sets of quotes a specific begin-quote must be matched by its corresponding end-quote.
  4. A non-escaped begin-quote which precedes a component must be matched by a non-escaped end-quote at the end of the component. A component thus quoted is referred to as a quoted component. It is parsed by removing the being- and end- quotes and by treating the intervening characters as ordinary characters unless one of the rules involving quoted components listed below applies.
  5. Quotes embedded in non-quoted components are treated as ordinary strings and need not be matched.
  6. A separator that is escaped or appears between non-escaped quotes is treated as an ordinary string and not a separator.
  7. An escape string within a quoted component acts as an escape only when followed by the corresponding end-quote string. This can be used to embed an escaped quote within a quoted component.
  8. An escaped escape string is not treated as an escape string.
  9. An escape string that does not precede a meta string (quotes or separator) and is not at the end of a component is treated as an ordinary string.
  10. A leading separator (the compound name string begins with a separator) denotes a leading empty atomic component (consisting of an empty string). A trailing separator (the compound name string ends with a separator) denotes a trailing empty atomic component. Adjacent separators denote an empty atomic component.

The string form of the compound name follows the syntax described above. When the components of the compound name are turned into their string representation the reserved syntax rules described above are applied (e.g. embedded separators are escaped or quoted) so that when the same string is parsed it will yield the same components of the original compound name.

Multithreaded Access

A CompoundName instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a CompoundName should lock the object. @author Rosanna Lee @author Scott Seligman @version 1.5 007 01/0212/0203 @since 1.3

Class ConfigurationException

This exception is thrown when there is a configuration problem. This can arise when installation of a provider was not done correctly or if there are configuration problems with the server or if configuration information required to access the provider or service is malformed or missing. For example a request to use SSL as the security protocol when the service provider software was not configured with the SSL component would cause such an exception. Another example is if the provider requires that a URL be specified as one of the environment properties but the client failed to provide it.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class Context

This interface represents a naming context which consists of a set of name-to-object bindings. It contains methods for examining and updating these bindings.

Names

Each name passed as an argument to a Context method is relative to that context. The empty name is used to name the context itself. A name parameter may never be null.

Most of the methods have overloaded versions with one taking a Name parameter and one taking a String. These overloaded versions are equivalent in that if the Name and String parameters are just different representations of the same name then the overloaded versions of the same methods behave the same. In the method descriptions below only one version is fully documented. The second version instead has a link to the first: the same documentation applies to both.

For systems that support federation String name arguments to Context methods are composite names. Name arguments that are instances of CompositeName are treated as composite names while Name arguments that are not instances of CompositeName are treated as compound names (which might be instances of CompoundName or other implementations of compound names). This allows the results of NameParser.parse() to be used as arguments to the Context methods. Prior to JNDI 1.2 all name arguments were treated as composite names.

Furthermore for systems that support federation all names returned in a NamingEnumeration from list() and listBindings() are composite names represented as strings. See CompositeName for the string syntax of names.

For systems that do not support federation the name arguments (in either Name or String forms) and the names returned in NamingEnumeration may be names in their own namespace rather than names in a composite namespace at the discretion of the service provider.

Exceptions

All the methods in this interface can throw a NamingException or any of its subclasses. See NamingException and their subclasses for details on each exception.

Concurrent Access

A Context instance is not guaranteed to be synchronized against concurrent access by multiple threads. Threads that need to access a single Context instance concurrently should synchronize amongst themselves and provide the necessary locking. Multiple threads each manipulating a different Context instance need not synchronize. Note that the lookup method when passed an empty name will return a new Context instance representing the same naming context.

For purposes of concurrency control a Context operation that returns a NamingEnumeration is not considered to have completed while the enumeration is still in use or while any referrals generated by that operation are still being followed.

Parameters

A Name parameter passed to any method of the Context interface or one of its subinterfaces will not be modified by the service provider. The service provider may keep a reference to it for the duration of the operation including any enumeration of the method's results and the processing of any referrals generated. The caller should not modify the object during this time. A Name returned by any such method is owned by the caller. The caller may subsequently modify it; the service provider may not.

Environment Properties

JNDI applications need a way to communicate various preferences and properties that define the environment in which naming and directory services are accessed. For example a context might require specification of security credentials in order to access the service. Another context might require that server configuration information be supplied. These are referred to as the environment of a context. The Context interface provides methods for retrieving and updating this environment.

The environment is inherited from the parent context as context methods proceed from one context to the next. Changes to the environment of one context do not directly affect those of other contexts.

It is implementation-dependent when environment properties are used and/or verified for validity. For example some of the security-related properties are used by service providers to "log in" to the directory. This login process might occur at the time the context is created or the first time a method is invoked on the context. When and whether this occurs at all is implementation-dependent. When environment properties are added or removed from the context verifying the validity of the changes is again implementation-dependent. For example verification of some properties might occur at the time the change is made or at the time the next operation is performed on the context or not at all.

Any object with a reference to a context may examine that context's environment. Sensitive information such as clear-text passwords should not be stored there unless the implementation is known to protect it.

Resource Files

To simplify the task of setting up the environment required by a JNDI application application components and service providers may be distributed along with resource files. A JNDI resource file is a file in the properties file format (see java.util.Properties containing a list of key/value pairs. The key is the name of the property (e.g. "java.naming.factory.object") and the value is a string in the format defined for that property. Here is an example of a JNDI resource file:

 java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory 
The JNDI class library reads the resource files and makes the property values freely available. Thus JNDI resource files should be considered to be "world readable" and sensitive information such as clear-text passwords should not be stored there.

There are two kinds of JNDI resource files: provider and application.

Provider Resource Files
Each service provider has an optional resource that lists properties specific to that provider. The name of this resource is:
[prefix/]jndiprovider.properties
where prefix is the package name of the provider's context implementation(s) with each period (".") converted to a slash ("/"). For example suppose a service provider defines a context implementation with class name com.sun.jndi.ldap.LdapCtx. The provider resource for this provider is named com/sun/jndi/ldap/jndiprovider.properties. If the class is not in a package the resource's name is simply jndiprovider.properties.

Certain methods in the JNDI class library make use of the standard JNDI properties that specify lists of JNDI factories:

The JNDI library will consult the provider resource file when determining the values of these properties. Properties other than these may be set in the provider resource file at the discretion of the service provider. The service provider's documentation should clearly state which properties are allowed; other properties in the file will be ignored.
Application Resource Files
When an application is deployed it will generally have several codebase directories and JARs in its classpath. Similarly when an applet is deployed it will have a codebase and archives specifying where to find the applet's classes. JNDI locates (using ClassLoader.getResources() all application resource files named jndi.properties in the classpath. In addition if the file java.home/lib/jndi.properties exists and is readable JNDI treats it as an additional application resource file. (java.home indicates the directory named by the java.home system property.) All of the properties contained in these files are placed into the environment of the initial context. This environment is then inherited by other contexts.

For each property found in more than one application resource file JNDI uses the first value found or in a few cases where it makes sense to do so it concatenates all of the values (details are given below). For example if the "java.naming.factory.object" property is found in three jndi.properties resource files the list of object factories is a concatentationconcatenation of the property values from all three files. Using this scheme each deployable component is responsible for listing the factories that it exports. JNDI automatically collects and uses all of these export lists when searching for factory classes.

Application resource files are available beginning with the Java 2 Platform except that the file in java.home/lib may be used on earlier Java platforms as well.

Search Algorithm for Properties
When JNDI constructs an initial context the context's environment is initialized with properties defined in the environment parameter passed to the constructor the system properties the applet parameters and the application resource files. See InitialContext for details. This initial environment is then inherited by other context instances.

When the JNDI class library needs to determine the value of a property it does so by merging the values from the following two sources in order:

  1. The environment of the context being operated on.
  2. The provider resource file (jndiprovider.properties) for the context being operated on.
For each property found in both of these two sources JNDI determines the property's value as follows. If the property is one of the standard JNDI properties that specify a list of JNDI factories (listed above) the values are concatenated into a single colon-separated list. For other properties only the first value found is used.

When a service provider needs to determine the value of a property it will generally take that value directly from the environment. A service provider may define provider-specific properties to be placed in its own provider resource file. In that case it should merge values as described in the previous paragraph.

In this way each service provider developer can specify a list of factories to use with that service provider. These can be modified by the application resources specified by the deployer of the application or applet which in turn can be modified by the user. @author Rosanna Lee @author Scott Seligman @author R. Vasudevan @version 1.68 0001/0212/0203 @since 1.3


Class ContextNotEmptyException

This exception is thrown when attempting to destroy a context that is not empty.

If the program wants to handle this exception in particular it should catch ContextNotEmptyException explicitly before attempting to catch NamingException. For example after catching ContextNotEmptyException the program might try to remove the contents of the context before reattempting the destroy.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @see Context#destroySubcontext @since 1.3


Class InitialContext

This class is the starting context for performing naming operations.

All naming operations are relative to a context. The initial context implements the Context interface and provides the starting point for resolution of names.

When the initial context is constructed its environment is initialized with properties defined in the environment parameter passed to the constructor and in any application resource files. In addition a small number of standard JNDI properties may be specified as system properties or as applet parameters (through the use of Thes special properties are listed in the field detail sections of the Context and LdapContext interface documentation.

JNDI determines each property's value by merging the values from the following two sources in order:

  1. The first occurrence of the property from the constructor's environment parameter and (for appropriate properties) the applet parameters and system properties.
  2. The application resource files (jndi.properties).
For each property found in both of these two sources or in more than one application resource file the property's value is determined as follows. If the property is one of the standard JNDI properties that specify a list of JNDI factories (see Context) all of the values are concatenated into a single colon-separated list. For other properties only the first value found is used.

The initial context implementation is determined at runtime. The default policy uses the environment property "{@link Context#INITIAL_CONTEXT_FACTORY java.naming.factory.initial}" which contains the class name of the initial context factory. An exception to this policy is made when resolving URL strings as described below.

When a URL string (a String of the form scheme_id:rest_of_name) is passed as a name parameter to any method a URL context factory for handling that scheme is located and used to resolve the URL. If no such factory is found the initial context specified by "java.naming.factory.initial" is used. Similarly when a CompositeName object whose first component is a URL string is passed as a name parameter to any method a URL context factory is located and used to resolve the first name component. See NamingManager.getURLContext() for a description of how URL context factories are located.

This default policy of locating the initial context and URL context factories may be overridden by calling NamingManager.setInitialContextFactoryBuilder().

NoInitialContextException is thrown when an initial context cannot be instantiated. This exception can be thrown during any interaction with the InitialContext not only when the InitialContext is constructed. For example the implementation of the initial context might lazily retrieve the context only when actual methods are invoked on it. The application should not have any dependency on when the existence of an initial context is determined.

When the environment property "java.naming.factory.initial" is non-null the InitialContext constructor will attempt to create the initial context specified therein. At that time the initial context factory involved might throw an exception if a problem is encountered. However it is provider implementation-dependent when it verifies and indicates to the users of the initial context any environment property- or connection- related problems. It can do so lazily--delaying until an operation is performed on the context or eagerly at the time the context is constructed.

An InitialContext instance is not synchronized against concurrent access by multiple threads. Multiple threads each manipulating a different InitialContext instance need not synchronize. Threads that need to access a single InitialContext instance concurrently should synchronize amongst themselves and provide the necessary locking. @author Rosanna Lee @author Scott Seligman @version 1.8 009 01/0212/0203 @see Context @see NamingManager#setInitialContextFactoryBuilder NamingManager.setInitialContextFactoryBuilder @since JNDI 1.1 / Java 2 Platform Standard Edition v 1.3


Class InsufficientResourcesException

This exception is thrown when resources are not available to complete the requested operation. This might due to a lack of resources on the server or on the client. There are no restrictions to resource types as different services might make use of different resources. Such restrictions might be due to physical limits and/or adminstrative quotas. Examples of limited resources are internal buffers memory network bandwidth.

InsufficientResourcesException is different from LimitExceededException in that the latter is due to user/system specified limits. See LimitExceededException for details.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class InterruptedNamingException

This exception is thrown when the naming operation being invoked has been interrupted. For example an application might interrupt a thread that is performing a search. If the search supports being interrupted it will throw InterruptedNamingException. Whether an operation is interruptableinterruptible and when depends on its implementation (as provided by the service providers). Different implementations have different ways of protecting their resources and objects from being damaged due to unexpected interrupts.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.46 0001/0212/0203 @see Context @see javax.naming.directory.DirContext @see java.lang.Thread#interrupt @see java.lang.InterruptedException @since 1.3


Class InvalidNameException

This exception indicates that the name being specified does not conform to the naming syntax of a naming system. This exception is thrown by any of the methods that does name parsing (such as those in Context DirContext CompositeName and CompoundName).

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @see Context @see javax.naming.directory.DirContext @see CompositeName @see CompoundName @see NameParser @since 1.3


Class LimitExceededException

This exception is thrown when a method terminates abnormally due to a user or system specified limit. This is different from a InsufficientResourceException in that LimitExceededException is due to a user/system specified limit. For example running out of memory to complete the request would be an insufficient resource. The client asking for 10 answers and getting back 11 is a size limit exception.

Examples of these limits include client and server configuration limits such as size time number of hops etc.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class LinkException

This exception is used to describe problems encounter while resolving links. Addition information is added to the base NamingException for pinpointing the problem with the link.

Analogous to how NamingException captures name resolution information LinkException captures "link"-name resolution information pinpointing the problem encountered while resolving a link. All these fields may be null.

A LinkException instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a single LinkException instance should lock the object. @author Rosanna Lee @author Scott Seligman @version 1.5 006 01/0212/0203 @see Context#lookupLink @see LinkRef @since 1.3


Class LinkLoopException

This exception is thrown when a loop was detected will attempting to resolve a link or an implementation specific limit on link counts has been reached.

Synchronization and serialization issues that apply to LinkException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @see LinkRef @since 1.3


Class LinkRef

This class represents a Reference whose contents is a name called the link name that is bound to an atomic name in a context.

The name is a URL or a name to be resolved relative to the initial context or if the first character of the name is "." the name is relative to the context in which the link is bound.

Normal resolution of names in context operations always follow links. Resolution of the link name itself may cause resolution to pass through other links. This gives rise to the possibility of a cycle of links whose resolution could not terminate normally. As a simple means to avoid such non-terminating resolutions service providers may define limits on the number of links that may be involved in any single operation invoked by the caller.

A LinkRef contains a single StringRefAddr whose type is "LinkAddress" and whose contents is the link name. The class name field of the Reference is that of this (LinkRef) class.

LinkRef is bound to a name using the normal Context.bind()/rebind() and DirContext.bind()/rebind(). Context.lookupLink() is used to retrieve the link itself if the terminal atomic name is bound to a link.

Many naming systems support a native notion of link that may be used within the naming system itself. JNDI does not specify whether there is any relationship between such native links and JNDI links.

A LinkRef instance is not synchronized against concurrent access by multiple threads. Threads that need to access a LinkRef instance concurrently should synchronize amongst themselves and provide the necessary locking. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @see LinkException @see LinkLoopException @see MalformedLinkException @see Context#lookupLink @since 1.3


Class MalformedLinkException

This exception is thrown when a malformed link was encountered while resolving or constructing a link.

Synchronization and serialization issues that apply to LinkException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @see LinkRef#getLinkName @see LinkRef @since 1.3


Class Name

The Name interface represents a generic name -- an ordered sequence of components. It can be a composite name (names that span multiple namespaces) or a compound name (names that are used within individual hierarchical naming systems).

There can be different implementations of Name; for example composite names URLs or namespace-specific compound names.

The components of a name are numbered. The indexes of a name with N components range from 0 up to but not including N. This range may be written as [0 N). The most significant component is at index 0. An empty name has no components.

None of the methods in this interface accept null as a valid value for a parameter that is a name or a name component. Likewise methods that return a name or name component never return null.

An instance of a Name may not be synchronized against concurrent multithreaded access if that access is not read-only. @author Rosanna Lee @author Scott Seligman @author R. Vasudevan @version 1.5 006 01/0212/0203 @since 1.3


Class NameAlreadyBoundException

This exception is thrown by methods to indicate that a binding cannot be added because the name is already bound to another object.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @see Context#bind @see Context#rebind @see Context#createSubcontext @see javax.naming.directory.DirContext#bind @see javax.naming.directory.DirContext#rebind @see javax.naming.directory.DirContext#createSubcontext @since 1.3


Class NameClassPair

This class represents the object name and class name pair of a binding found in a context.

A context consists of name-to-object bindings. The NameClassPair class represents the name and the class of the bound object. It consists of a name and a string representing the package-qualified class name.

Use subclassing for naming systems that generate contents of a name/class pair dynamically.

A NameClassPair instance is not synchronized against concurrent access by multiple threads. Threads that need to access a NameClassPair concurrently should synchronize amongst themselves and provide the necessary locking. @author Rosanna Lee @author Scott Seligman @version 1.5 006 01/0212/0203 @see Context#list @since 1.3


Class NameNotFoundException

This exception is thrown when a component of the name cannot be resolved because it is not bound.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class NameParser

This interface is used for parsing names from a hierarchical namespace. The NameParser contains knowledge of the syntactic information (like left-to-right orientation name separator etc.) needed to parse names. The equals() method when used to compare two NameParsers returns true if and only if they serve the same namespace. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @see CompoundName @see Name @since 1.3

Class NamingEnumeration

This interface is for enumerating lists returned by methods in the javax.naming and javax.naming.directory packages. It extends Enumeration to allow as exceptions to be thrown during the enumeration.

When a method such as list() listBindings() or search() returns a NamingEnumeration any exceptions encountered are reserved until all results have been returned. At the end of the enumeration the exception is thrown (by hasMore());

For example if the list() is returning only a partial answer the corresponding exception would be PartialResultException. list() would first return a NamingEnumeration. When the last of the results has been returned by the NamingEnumeration's next() invoking hasMore() would result in PartialResultException being thrown.

In another example if a search() method was invoked with a specified size limit of 'n'. If the answer consists of more than 'n' results search() would first return a NamingEnumeration. When the n'th result has been returned by invoking next() on the NamingEnumeration a SizeLimitExceedException would then thrown when hasMore() is invoked.

Note that if the program uses hasMoreElements() and nextElement() instead to iterate through the NamingEnumeration because these methods cannot throw exceptions no exception will be thrown. Instead in the previous example after the n'th result has been returned by nextElement() invoking hasMoreElements() would return false.

Note also that NoSuchElementException is thrown if the program invokes next() or nextElement() when there are no elements left in the enumeration. The program can always avoid this exception by using hasMore() and hasMoreElements() to check whether the end of the enumeration has been reached.

If an exception is thrown during an enumeration the enumeration becomes invalid. Subsequent invocation of any method on that enumeration will yield undefined results. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @see Context#list @see Context#listBindings @see javax.naming.directory.DirContext#search @see javax.naming.directory.Attributes#getAll @see javax.naming.directory.Attributes#getIDs @see javax.naming.directory.Attribute#getAll @since 1.3


Class NamingException

This is the superclass of all exceptions thrown by operations in the Context and DirContext interfaces. The nature of the failure is described by the name of the subclass. This exception captures the information pinpointing where the operation failed such as where resolution last proceeded to. null is an acceptable value for any of these fields. When null it means that no such information has been recorded for that field.

A NamingException instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a single NamingException instance should lock the object. @author Rosanna Lee @author Scott Seligman @version 1.6 01/0212/0903 @since 1.3


Class NamingSecurityException

This is the superclass of security-related exceptions thrown by operations in the Context and DirContext interfaces. The nature of the failure is described by the name of the subclass.

If the program wants to handle this exception in particular it should catch NamingSecurityException explicitly before attempting to catch NamingException. A program might want to do this for example if it wants to treat security-related exceptions specially from other sorts of naming exception.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 006 01/0212/0203 @since 1.3

Class NamingSecurityException, constructor NamingSecurityException()

Constructs a new instance of NamingSecurityException. All fields are initiailizedinitialized to null.

Class NoInitialContextException

This exception is thrown when no initial context implementation can be created. The policy of how an initial context implementation is selected is described in the documentation of the InitialContext class.

This exception can be thrown during any interaction with the InitialContext not only when the InitialContext is constructed. For example the implementation of the initial context might lazily retrieve the context only when actual methods are invoked on it. The application should not have any dependency on when the existence of an initial context is determined.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @see InitialContext @see javax.naming.directory.InitialDirContext @see javax.naming.spi.NamingManager#getInitialContext @see javax.naming.spi.NamingManager#setInitialContextFactoryBuilder @since 1.3


Class NoPermissionException

This exception is thrown when attempting to perform an operation for which the client has no permission. The access control/permission model is dictated by the directory/naming server.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class NotContextException

This exception is thrown when a naming operation proceeds to a point where a context is required to continue the operation but the resolved object is not a context. For example Context.destroy() requires that the named object be a context. If it is not NotContextException is thrown. Another example is a non-context being encountered during the resolution phase of the Context methods.

It is also thrown when a particular subtype of context is required such as a DirContext and the resolved object is a context but not of the required subtype.

Synchronization and serialization issues that apply to NamingException apply directly here. @see Context#destroySubcontext @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class OperationNotSupportedException

This exception is thrown when a context implementation does not support the operation being invoked. For example if a server does not support the Context.bind() method it would throw OperationNotSupportedException when the bind() method is invoked on it.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class PartialResultException

This exception is thrown to indicate that the result being returned or returned so far is partial and that the operation cannot be completed. For example when listing a context this exception indicates that returned results only represents some of the bindings in the context.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @version 1.4 005 01/0212/0203 @author Scott Seligman @since 1.3


Class RefAddr

This class represents the address of a communications end-point. It consists of a type that describes the communication mechanism and an address contents determined by an RefAddr subclass.

For example an address type could be "BSD Printer Address" which specifies that it is an address to be used with the BSD printing protocol. Its contents could be the machine name identifying the location of the printer server that understands this protocol.

A RefAddr is contained within a Reference.

RefAddr is an abstract class. Concrete implementations of it determine its synchronization properties. @author Rosanna Lee @author Scott Seligman @version 1.6 01/0212/0903 @see Reference @see LinkRef @see StringRefAddr @see BinaryRefAddr @since 1.3


Class Reference

This class represents a reference to an object that is found outside of the naming/directory system.

Reference provides a way of recording address information about objects which themselves are not directly bound to the naming/directory system.

A Reference consists of an ordered list of addresses and class information about the object being referenced. Each address in the list identifies a communications endpoint for the same conceptual object. The "communications endpoint" is information that indicates how to contact the object. It could be for example a network address a location in memory on the local machine another process on the same machine etc. The order of the addresses in the list may be of significance to object factories that interpret the reference.

Multiple addresses may arise for various reasons such as replication or the object offering interfaces over more than one communication mechanism. The addresses are indexed starting with zero.

A Reference also contains information to assist in creating an instance of the object to which this Reference refers. It contains the class name of that object and the class name and location of the factory to be used to create the object. The class factory location is a space-separated list of URLs representing the class path used to load the factory. When the factory class (or any class or resource upon which it depends) needs to be loaded each URL is used (in order) to attempt to load the class.

A Reference instance is not synchronized against concurrent access by multiple threads. Threads that need to access a single Reference concurrently should synchronize amongst themselves and provide the necessary locking. @author Rosanna Lee @author Scott Seligman @version 1.6 01/0212/0903 @see RefAddr @see StringRefAddr @see BinaryRefAddr @since 1.3


Class Referenceable

This interface is implemented by an object that can provide a Reference to itself.

A Reference represents a way of recording address information about objects which themselves are not directly bound to the naming system. Such objects can implement the Referenceable interface as a way for programs that use that object to determine what its Reference is. For example when binding a object if an object implements the Referenceable interface getReference() can be invoked on the object to get its Reference to use for binding. @author Rosanna Lee @author Scott Seligman @author R. Vasudevan @version 1.4 005 01/0212/0203 @see Context#bind @see javax.naming.spi.NamingManager#getObjectInstance @see Reference @since 1.3


Class ReferralException

This abstract class is used to represent a referral exception which is generated in response to a referral such as that returned by LDAP v3 servers.

A service provider provides a subclass of ReferralException by providing implementations for getReferralInfo() and getReferralContext() (and appropriate constructors and/or corresponding "set" methods).

The following code sample shows how ReferralException can be used.

 while (true) { try { bindings = ctx.listBindings(name); while (bindings.hasMore()) { b = bindings.next(); ... } break; } catch (ReferralException e) { ctx = e.getReferralContext(); } } 

ReferralException is an abstract class. Concrete implementations determine its synchronization and serialization properties.

An environment parameter passed to the getReferralContext() method is owned by the caller. The service provider will not modify the object or keep a reference to it but may keep a reference to a clone of it. @author Rosanna Lee @author Scott Seligman @version 1.6 007 01/0212/0203 @since 1.3


Class ServiceUnavailableException

This exception is thrown when attempting to communcatecommunicate with a directory or naming service and that service is not available. It might be unavailbleunavailable for different reasons. For example the server might be too busy to service the request or the server might not be registered to service any requests etc.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 006 01/0212/0203 @since 1.3


Class SizeLimitExceededException

This exception is thrown when a method produces a result that exceeds a size-related limit. This can happen for example if the result contains more objects than the user requested or when the size of the result exceeds some implementation-specific limit.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3


Class StringRefAddr

This class represents the string form of the address of a communications end-point. It consists of a type that describes the communication mechanism and a string contents specific to that communication mechanism. The format and interpretation of the address type and the contents of the address are based on the agreement of three parties: the client that uses the address the object/server that can be reached using the address and the administrator or program that creates the address.

An example of a string reference address is a host name. Another example of a string reference address is a URL.

A string reference address is immutable: once created it cannot be changed. Multithreaded access to a single StringRefAddr need not be synchronized. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @see RefAddr @see BinaryRefAddr @since 1.3


Class TimeLimitExceededException

This exception is thrown when a method does not terminate within the specified time limit. This can happen for example if the user specifies that the method should take no longer than 10 seconds and the method fails to complete with 10 seconds.

Synchronization and serialization issues that apply to NamingException apply directly here. @author Rosanna Lee @author Scott Seligman @version 1.4 005 01/0212/0203 @since 1.3