The org.jnp.interfaces.NamingContextFactory

The NamingContextFactory is an InitialContextFactory implementation for connecting to the jboss JNDI service. It uses a socket bootstrap to obtain an RMI connection to the naming service. Its supported InitialContext environment properties include:

• java.naming.factory.initial (or Context.INITIAL_CONTEXT_FACTORY), 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 an InitialContext  object is created.

• java.naming.provider.url (or Context.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, or a comma separated list of URL strings if multiple hosts should be tried in the order specified. For JBossNS the URL format is jnp://host:port/[Jndi_path|jndi_path]. The jnp: portion of the URL is the protocol and refers to the socket/RMI based protocol used by JBoss. The jndi_path portion of the URL is an optional JNDI name relative to the root context, for example, "apps" or "apps/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 (or Context.URL_PKG_PREFIXES), 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 the jnp: and java: 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 is org.jnp.interfaces.TimedSocketFactory. The TimedSocketFactory is a simple SocketFactory 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.

• jnp.localAddress, The local address to bind the connected bootstrap socket to. This also controls the interface over which any multicast discovery packets are sent (see below).

• jnp.localPort, The local port to bind the connected bootstrap socket to.

• jnp.useRelativeName, A flag indicating the style of names passed to javax.naming.spi.NamingManager methods. True for the relative names described by the NamingManager API, false for absolute names as used historically by the JBoss naming implementation.

• jnp.maxRetries, An integer that controls the number of connection retry attempts that will be made on the initial connection to the naming server. This only applies to ConnectException failures. A value <= 1 means that only one attempt will be made. Default is one.

Automatic Discovery of HA-JNDI Servers

The org.jnp.interfaces.NamingContextFactory also features the ability to automatically discover naming servers running the JBoss HA-JNDI service. Discovery occurs when either no Context.PROVIDER_URL is specified, or no valid naming service could be located among the URLs specified. When discovery is attempted, a multicast packet will be sent out, requesting that any HA-JNDI servers reply with an announcement of their availability.  If any replies are received, the NamingContext can then connect to the replying server.

In addition to the environment properties described above, org.jnp.interfaces.NamingContextFactory also supports tte following properties related to automatic discovery:

• jnp.partitionName, The cluster partition name discovery should be restricted to. If you are running in an environment with multiple clusters, you may want to restrict the naming discovery to a particular cluster. There is no default value, meaning that any cluster response will be accepted.

• jnp.discoveryGroup, The multicast IP/address to which the discovery query is sent. The default is 230.0.0.4. Note that if JBoss AS is started with the -u or --udp switches, the HA-JNDI service will be listening on the multicast address specified by the switch, not on the default 230.0.0.4.  In this case, jnp.discoveryGroup should be configured.

• jnp.discoveryPort, The port to which the discovery query is sent. The default is 1102.

• jnp.discoveryTimeout, The time in milliseconds to wait for a discovery query response. The default value is 5000 (5 seconds).

• jnp.discoveryTTL, The time-to-live for the multicast discovery packets.  Useful in development environments where isolating clusters via jnp.partitionName, jnp.discoveryGroup and jnp.discoveryPort may not be practical.

• jnp.disableDiscovery, A flag indicating that the discovery process should not be attempted. If the jnp.disableDiscovery flag is true, then discovery will not be attempted.

The org.jboss.naming.NamingContextFactory

This version of the InitialContextFactory implementation is a simple extension of the jnp version which differs from the jnp version in that it caches in a public ThreadLocal a reference to the last Hashtable passed to its InitialContextFactory.getInitialContext(Hashtable env) method. This cached reference is used by ejb handles and other JNDI-sensitive objects like the UserTransaction factory to remember the JNDI context that was in effect when they were created. If you want this environment to be bound to the object even after it is serialized across vm boundaries, then you should use the org.jboss.naming.NamingContextFactory. If you want the environment that is defined in the current vm jndi.properties or system properties, then you should use the org.jnp.interfaces.NamingContextFactory version.

Referenced by: