How to configure remote naming in JBoss EAP 6
Environment
Red Hat JBoss Enterprise Application Platform (EAP) 6.x
Issue
- How to configure remote naming in JBoss EAP 6
- How to configured JNDI for hornetq connections in JBoss EAP 6?
- What port does JNDI use in JBoss EAP 6?
Resolution
Note: For invoking remote ejbs see this article: How to configure an EJB client in JBoss EAP 6, as Remote Naming is not intended for invoking remote EJBs.
Remote Naming allows remote clients to look up objects in JNDI in JBoss EAP 6. Only objects bound in java:jboss/exported/ are remotely visible. Remote naming using the remoting port which defaults to 4447. Remote clients can only lookup objects in JNDI, they cannot bind into it directly (an EJB, Web Service or other running in the JBoss server could bind for a remote client).
Note: A Remote Naming Context can NOT be shared across threads. There is a connection tied to the context and it is not thread safe.
Example
import javax.naming.Context;
import javax.naming.InitialContext;
public Context getRemoteNamingInitialContext() throws Exception {
Hashtable<String, String> env = new Hashtable<String, String>();
env.put(Context.INITIAL_CONTEXT_FACTORY, "org.jboss.naming.remote.client.InitialContextFactory");
env.put(Context.PROVIDER_URL, "remote://" + host1 + ":" + port1 + ", " + "remote://" + host2 + ":" + port2);
env.put(Context.SECURITY_PRINCIPAL, username);
env.put(Context.SECURITY_CREDENTIALS, password);
return new InitialContext(env);
}
Module dependency
If the application is running inside of JBoss EAP 6, a module dependency on the org.jboss.remote-naming will be necessary to access the classes. The dependency can be specified either by jboss-deployment-structure.xml or by MANIFEST.MF
jboss-deployment-structure.xml
The jboss-deployment-structure.xml goes only in the the top level application. If the top level application is a war, this file goes in WEB-INF, if it is an ear or other deployment type, it goes in the META-INF. This export=true means if application is an ear, then it will make this module visible to all of the ears sub deployments.
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
<deployment>
<dependencies>
<module name="org.jboss.remote-naming" export="true"/>
</dependencies>
</deployment>
</jboss-deployment-structure>
MANIFEST.MF
Dependencies: org.jboss.remote-naming
Java Naming Properties
javax.naming.Context.INITIAL_CONTEXT_FACTORY (java.naming.factory.initial)
Constant that holds 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. This property may be specified in the environment parameter passed to the initial context constructor, an applet parameter, a system property, or an application resource file. If it is not specified in any of these sources, NoInitialContextException is thrown when an initial context is required to complete an operation.
Set to org.jboss.naming.remote.client.InitialContextFactory
javax.naming.Context.OBJECT_FACTORIES (java.naming.factory.object)
Constant that holds the name of the environment property for specifying the list of object factories to use. The value of the property should be a colon-separated list of the fully qualified class names of factory classes that will create an object given information about the object. This property may be specified in the environment, an applet parameter, a system property, or one or more resource files.
javax.naming.Context.URL_PKG_PREFIXES (java.naming.factory.url.pkgs)
Constant that holds 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. This property may be specified in the environment, an applet parameter, a system property, or one or more resource files. The prefix com.sun.jndi.url is always appended to the possibly empty list of package prefixes.
javax.naming.Context.PROVIDER_URL (java.naming.provider.url)
Constant that holds the name of the environment property for specifying configuration information for the service provider to use. The value of the property should contain a URL string (e.g. "remote://somehost:389"). This property may be specified in the environment, an applet parameter, a system property, or a resource file. If it is not specified in any of these sources, the default configuration is determined by the service provider.
Set to a single remote://host:port or a comma separated list of remote://host:port which will provide failover. The default port to use in JBoss EAP 6.x is 4447
javax.naming.Context.SECURITY_PRINCIPAL (java.naming.security.principal)
Constant that holds the name of the environment property for specifying the identity of the principal for authenticating the caller to the service. The format of the principal depends on the authentication scheme. If this property is unspecified, the behaviour is determined by the service provider.
Used to specify the username to be used in authentication
javax.naming.Context.SECURITY_CREDENTIALS (java.naming.security.credentials)
Constant that holds the name of the environment property for specifying the credentials of the principal for authenticating the caller to the service. The value of the property depends on the authentication scheme. For example, it could be a hashed password, clear-text password, key, certificate, and so on. If this property is unspecified, the behaviour is determined by the service provider.
Used to specify the password to be used in authentication. Note: if jboss.naming.client.security.password.base64 is specified, it will take precedence over java.naming.security.credentials
JBoss Naming Properties
jboss.naming.client.connect.timeout:
Connection timeout in milliseconds, defaults to **5000** ms (5 s)
jboss.naming.client.random.server:
If this is set to true then a server will be picked at random to connect to, rather than using the first one in the list
jboss.naming.client.security.callback.handler.class
Allows you to specify a JAAS Callback Handler class
If no callback handler class is specified, but username/password are specified, AuthenticationCallbackHandler will be used. If no username/password are specified, then AnonymousCallbackHandler will be used.
jboss.naming.client.security.password.base64
base64 encoded password, if specified it will take precedence over Context.SECURITY_CREDENTIALS
jboss.naming.client.security.realm
Used with callback handler, if no callback handler class is specified AuthenticationCallbackHandler is used
XNIO connection options
XNIO connection options can be set via the naming properties, with the appropriate prefix. For example to enable TCP keep-alive, add jboss.naming.client.connect.options.org.xnio.Options.KEEP_ALIVE with the value true
Remoting connection options
Remoting connection options can be set via the naming properties, with the appropriate prefix. For example to enable Remoting heartbeat, add this property:
jboss.naming.client.connect.options.org.jboss.remoting3.RemotingOptions.HEARTBEAT_INTERVAL with the value in milliseconds for the heartbeat interval such as 60000 for 60 seconds
JBoss Remote Naming Properties file configuration
**jboss-naming-client.properties** - remote-naming will look for a file named jboss-naming-client.properties on the classpath, if it finds it, it will load the properties from it, these values can be overridden by passing in properties to the InitialContext(...) creation.
Note: The jndi.properties file should NOT be packaged in an application running in an application server as it sets global settings for the whole JVM which will interfere with other applications and defaults. The jndi.properties should only be used in a standalone JVM application.
The jboss-naming-client.properties can be used within an application deployed in JBoss EAP 6.x as it is isolated to the application / classloader.
JBoss Remote Naming failover
Remote naming store that has the ability to re-establish a connection to a destination server, if the connection breaks at some point in time. This remote naming store also has the ability to connect to multiple different destination hosts/servers. At a given time, the naming store will be connected to at most one server and it will "failover" to the "next" server if the connection with the current server breaks.
Related Solutions
NullPointerException in org.jboss.naming.remote.protocol.v1.Protocol in JBoss EAP 6.x
This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.