9.3. The Naming InitialContext Factories
The JBoss JNDI provider currently supports several different
InitialContext
factory implementations.
9.3.1. The standard naming context factory
The most commonly used factory is the
org.jnp.interfaces.NamingContextFactory
implementation. Its properties include:
- java.naming.factory.initial: The name of the environment property for specifying the initial context factory to use. The value of the property should be the fully qualified class name of the factory class that will create an initial context. If it is not specified, a
javax.naming.NoInitialContextException
will be thrown when anInitialContext
object is created. - java.naming.provider.url: The name of the environment property for specifying the location of the JBoss JNDI service provider the client will use. The
NamingContextFactory
class uses this information to know which JBossNS server to connect to. The value of the property should be a URL string. For JBossNS the URL format isjnp://host:port/[jndi_path]
. Thejnp:
portion of the URL is the protocol and refers to the socket/RMI based protocol used by JBoss. Thejndi_path
portion of the URL is an optional JNDI name relative to the root context, for example,apps
orapps/tmp
. Everything but the host component is optional. The following examples are equivalent because the default port value is 1099.jnp://www.jboss.org:1099/
www.jboss.org:1099
www.jboss.org
- java.naming.factory.url.pkgs: The name of the environment property for specifying the list of package prefixes to use when loading in URL context factories. The value of the property should be a colon-separated list of package prefixes for the class name of the factory class that will create a URL context factory. For the JBoss JNDI provider this must be
org.jboss.naming:org.jnp.interfaces
. This property is essential for locating thejnp:
andjava:
URL context factories of the JBoss JNDI provider. - jnp.socketFactory: The fully qualified class name of the
javax.net.SocketFactory
implementation to use to create the bootstrap socket. The default value isorg.jnp.interfaces.TimedSocketFactory
. TheTimedSocketFactory
is a simpleSocketFactory
implementation that supports the specification of a connection and read timeout. These two properties are specified by: - jnp.timeout: The connection timeout in milliseconds. The default value is 0 which means the connection will block until the VM TCP/IP layer times out.
- jnp.sotimeout: The connected socket read timeout in milliseconds. The default value is 0 which means reads will block. This is the value passed to the
Socket.setSoTimeout
on the newly connected socket.
When a client creates an
InitialContext
with these JBossNS properties available, the org.jnp.interfaces.NamingContextFactory
object is used to create the Context
instance that will be used in subsequent operations. The NamingContextFactory
is the JBossNS implementation of the javax.naming.spi.InitialContextFactory
interface. When the NamingContextFactory
class is asked to create a Context
, it creates an org.jnp.interfaces.NamingContext
instance with the InitialContext
environment and name of the context in the global JNDI namespace. It is the NamingContext
instance that actually performs the task of connecting to the JBossNS server, and implements the Context
interface. The Context.PROVIDER_URL
information from the environment indicates from which server to obtain a NamingServer
RMI reference.
The association of the
NamingContext
instance to a NamingServer
instance is done in a lazy fashion on the first Context
operation that is performed. When a Context
operation is performed and the NamingContext
has no NamingServer
associated with it, it looks to see if its environment properties define a Context.PROVIDER_URL
. A Context.PROVIDER_URL
defines the host and port of the JBossNS server the Context
is to use. If there is a provider URL, the NamingContext
first checks to see if a Naming
instance keyed by the host and port pair has already been created by checking a NamingContext
class static map. It simply uses the existing Naming
instance if one for the host port pair has already been obtained. If no Naming
instance has been created for the given host and port, the NamingContext
connects to the host and port using a java.net.Socket
, and retrieves a Naming
RMI stub from the server by reading a java.rmi.MarshalledObject
from the socket and invoking its get method. The newly obtained Naming instance is cached in the NamingContext
server map under the host and port pair. If no provider URL was specified in the JNDI environment associated with the context, the NamingContext
simply uses the in VM Naming instance set by the Main
MBean.
The
NamingContext
implementation of the Context
interface delegates all operations to the Naming
instance associated with the NamingContext
. The NamingServer
class that implements the Naming
interface uses a java.util.Hashtable
as the Context
store. There is one unique NamingServer
instance for each distinct JNDI Name for a given JBossNS server. There are zero or more transient NamingContext
instances active at any given moment that refers to a NamingServer
instance. The purpose of the NamingContext
is to act as a Context
to the Naming
interface adaptor that manages translation of the JNDI names passed to the NamingContext
. Because a JNDI name can be relative or a URL, it needs to be converted into an absolute name in the context of the JBossNS server to which it refers. This translation is a key function of the NamingContext
.