CHAPTER 3 Naming on JBoss - The JNDI Naming Service
This chapter discusses the JBoss JNDI based naming service and the role of JNDI in JBoss and J2EE. An introduction to the basic JNDI API and common usage conventions will also be discussed. The JBoss specific configuration of J2EE component naming environments defined by the standard deployment descriptors will also be addressed. The final topic is the configuration and architecture of the JBoss naming service component, Naming/JBoss.
The JBoss naming service is an implementation of the Java Naming and Directory Interface (JNDI). JNDI plays a key role in J2EE because it provides a naming service that allows a user to map a name onto an object. This is a fundamental need in any programming environment because developers and administrators want to be able to refer to objects and services by recognizable names. A good example of a pervasive naming service is the Internet Domain Name System (DNS). The DNS service allows you to refer to hosts using logical names, rather than their numeric Internet addresses. JNDI serves a similar role in J2EE by enabling developers and administrators to create name-to-object bindings for use in J2EE components.
An Overview of JNDI
JNDI is a standard Java API that is bundled with JDK1.3 and higher. JNDI provides a common interface to a variety of existing naming services: DNS, LDAP, Active Directory, RMI registry, COS registry, NIS, and file systems. The JNDI API is divided logically into a client API that is used to access naming services, and a service provider interface (SPI) that allows the user to create JNDI implementations for naming services.
The SPI layer is an abstraction that naming service providers must implement to enable the core JNDI classes to expose the naming service using the common JNDI client interface. An implementation of JNDI for a naming service is referred to as a JNDI provider. JBoss naming is an example JNDI implementation, based on the SPI classes. Note that the JNDI SPI is not needed by J2EE component developers.
For a thorough introduction and tutorial on JNDI, which covers both the client and service provider APIs, see the Sun tutorial at http://java.sun.com/products/jndi/tutorial/ .
The JNDI API
The main JNDI API package is the javax.naming package. It contains five interfaces, 10 classes, and several exceptions. There is one key class, InitialContext , and two key interfaces, Context and Name .
Names
The notion of a name is of fundamental importance in JNDI. The naming system determines the syntax that the name must follow. The syntax of the naming system allows the user to parse string representations of names into its components. A name is used with a naming system to locate objects. In the simplest sense, a naming system is just a collection of objects with unique names. To locate an object in a naming system you provide a name to the naming system, and the naming system returns the object store under the name.
As an example, consider the Unix file system's naming convention. Each file is named from its path relative to the root of the file system, with each component in the path separated by the forward slash character ("/"). The file's path is ordered from left to right. The pathname, /usr/jboss/readme.txt, for example, names a file readme.txt in the directory jboss, under the directory usr, located in the root of the file system. JBoss naming uses a Unix-style namespace as its naming convention.
The javax.naming. Name interface represents a generic name as an ordered sequence of components. It can be a composite name (one that spans multiple namespaces), or a compound name (one that is used within a single hierarchical naming system). The components of a name are numbered. The indexes of a name with N components range from 0 up to, but not including, N. The most significant component is at index 0. An empty name has no components.
A composite name is a sequence of component names that span multiple namespaces. An example of a composite name would be the hostname+file commonly used with Unix commands like scp. For example, this command copies localfile.txt to the file remotefile.txt in the tmp directory on host ahost.someorg.org:
scp localfile.txt ahost.someorg.org:/tmp/remotefile.txt
A compound name is derived from a hierarchical namespace. Each component in a compound name is an atomic name, meaning a string that cannot be parsed into smaller components. A file pathname in the Unix file system is an example of a compound name.The ahost.someorg.org:/tmp/remotefile.txt is a composite name that spans the DNS and Unix file system namespaces. The components of the composite name are ahost.someorg.org and /tmp/remotefile.txt. A 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 javax.naming.CompoundName class. The JNDI API provides the javax.naming.CompositeName class as the implementation of the Name interface for composite names.
Contexts
The javax.naming.Context interface is the primary interface for interacting with a naming service. The Context interface represents a set of name-to-object bindings. Every context has an associated naming convention that determines how the context parses string names into javax.naming.Name instances. To create a name to object binding you invoke the bind method of a Context and specify a name and an object as arguments. The object can later be retrieved using its name using the Context lookup method. A Context will typically provide operations for binding a name to an object, unbinding a name, and obtaining a listing of all name-to-object bindings. The object you bind into a Context can itself be of type Context . The Context object that is bound is referred to as a subcontext of the Context on which the bind method was invoked.
As an example, consider a file directory with a pathname /usr, which is a context in the Unix file system. A file directory named relative to another file directory is a subcontext (commonly referred to as a subdirectory). A file directory with a pathname /usr/jboss names a jboss context that is a subcontext of usr . In another example, a DNS domain, such as org, is a context. A DNS domain named relative to another DNS domain is another example of a subcontext. In the DNS domain jboss.org, the DNS domain jboss is a subcontext of org because DNS names are parsed right to left.
Obtaining a Context using InitialContext
All naming service operations are performed on some implementation of the Context interface. Therefore, you need a way to obtain a Context for the naming service you are interested in using. The javax.naming.IntialContext class implements the Context interface, and provides the starting point for interacting with a naming service.
When you create an InitialContext , it is initialized with properties from the environment. JNDI determines each property's value by merging the values from the following two sources, in order such as:
- The first occurrence of the property from the constructor's environment parameter and (for appropriate properties) the applet parameters and system properties.
- All jndi.properties resource files found on the classpath.
For each property found in both of these two sources, 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, all of the values are concatenated into a single, colon-separated list. For other properties, only the first value found is used. The preferred method of specifying the JNDI environment properties is through a jndi.properties file. The reason is that this allows your code to externalize the JNDI provider specific information, and changing JNDI providers will not require changes to your code; thus it avoids the need to recompile to be able to see the change.
The Context implementation used internally by the InitialContext class is determined at runtime. The default policy uses the environment property "java.naming.factory.initial", which contains the class name of the javax.naming.spi.InitialContextFactory implementation. You obtain the name of the InitialContextFactory class from the naming service provider you are using.
See A sample jndi.properties file. gives a sample jndi.properties file a client application would use to connect to a JBossNS service running on the local host at port 1099. The client application would need to have the jndi.properties file available on the application classpath. These are the properties that the JBossNS JNDI implementation requires. Other JNDI providers will have different properties and values.
J2EE and JNDI - The Application Component Environment
JNDI is a fundamental aspect of the J2EE specifications. One key usage is the isolation of J2EE component code from the environment in which the code is deployed. Use of the application component's environment allows the application component to be customized without the need to access or change the application component's source code. The application component environment is sometimes referred to as the enterprise naming context (ENC). It is the responsibility of the application component container to make an ENC available to the container components in the form of JNDI Context . The ENC is utilized by the participants involved in the life cycle of a J2EE component in the following ways:
- Application component business logic should be coded to access information from its ENC. The component provider uses the standard deployment descriptor for the component to specify the required ENC entries. The entries are declarations of the information and resources the component requires at runtime.
- The container provides tools that allow a deployer of a component to map the ENC references made by the component developer to the deployment environment entity that satisfies the reference.
- The component deployer utilizes the container tools to ready a component for final deployment.
- The component container uses the deployment package information to build the complete component ENC at runtime
The complete specification regarding the use of JNDI in the J2EE platform can be found in Section 5 of the J2EE 1.3 specification. The J2EE specification is available at http://java.sun.com/j2ee/download.html .
An application component instance locates the ENC using the JNDI API. An application component instance creates a javax.naming.InitialContext object by using the no argument constructor and then looks up the naming environment under the name java:comp/env. The application component's environment entries are stored directly in the ENC, or in its subcontexts.See ENC access sample code. illustrates the prototypical lines of code a component uses to access its ENC.
ENC access sample code
// Obtain the application component's ENC
Context iniCtx = new InitialContext();
Context compEnv = (Context) iniCtx.lookup("java:comp/env");
An application component environment is a local environment that is accessible only by the component when the application server container thread of control is interacting with the application component. This means that an EJB Bean1 cannot access the ENC elements of EJB Bean2, and visa-versa. Similarly, Web application Web1 cannot access the ENC elements of Web application Web2 or Bean1 or Bean2 for that matter. Also, arbitrary client code, whether it is executing inside of the application server VM or externally cannot access a component's java:comp JNDI context. The purpose of the ENC is to provide an isolated, read-only namespace that the application component can rely on regardless of the type of environment in which the component is deployed. The ENC must be isolated from other components because each component defines its own ENC content, and components A and B may define the same name to refer to different objects. For example, EJB Bean1 may define an environment entry java:comp/env/red to refer to the hexadecimal value for the RGB color for red, while Web application Web1 may bind the same name to the deployment environment language locale representation of red.
There are three commonly used levels of naming scope in the JBossNS implementation - names under java:comp, names under java:, and any other name. As discussed, the java:comp context and its subcontexts are only available to the application component associated with the java:comp context. Subcontexts and object bindings directly under java: are only visible within the JBoss server virtual machine. Any other context or object binding is available to remote clients, provided the context or object supports serialization. You'll see how the isolation of these naming scopes is achieved in the section titled "The JBossNS Architecture"
An example of where the restricting a binding to the java: context is useful would be a javax.sql.DataSource connection factory that can only be used inside of the JBoss VM where the associated database pool resides. An example of a globally visible name that should accessible by remote client is an EJB home interface.
ENC Usage Conventions
JNDI is used as the API for externalizing a great deal of information from an application component. The JNDI name that the application component uses to access the information is declared in the standard ejb-jar.xml deployment descriptor for EJB components, and the standard web.xml deployment descriptor for Web components. Several different types of information may be stored in and retrieved from JNDI including:
- Environment entries as declared by the env-entry elements
- EJB references as declared by ejb-ref and ejb-local-ref elements.
- Resource manager connection factory references as declared by the resource-ref elements
- Resource environment references as declared by the resource-env-ref elements
Each type of deployment descriptor element has a JNDI usage convention with regard to the name of the JNDI context under which the information is bound. Also, in addition to the standard deployment descriptor element, there is a JBoss server specific deployment descriptor element that maps the JNDI name as used by the application component to the deployment environment JNDI name.
The ejb-jar.xml ENC Elements
The EJB 2.0 deployment descriptor describes a collection of EJB components and their environment. Each of the three types of EJB components--session, entity, and message-driven--support the specification of an EJB local naming context. The ejb-jar.xml description is a logical view of the environment that the EJB needs to operate. Because the EJB component developer generally cannot know into what environment the EJB will be deployed, the developer describes the component environment in a deployment environment independent manner using logical names. It is the responsibility of a deployment administrator to link the EJB component logical names to the corresponding deployment environment resources.
See The ENC elements in the standard ejb-jar.xml 2.0 deployment descriptor.. gives a graphical view of the EJB deployment descriptor DTD without the non-ENC elements. Only the session element is shown fully expanded as the ENC elements for entity and mesage-driven are identical. The full ejb-jar.xml DTD is available from the Sun Web site at the ENC elements in the standard EJB 2.0 ejb-jar.xml deployment descriptor.
The web.xml ENC Elements
The Servlet 2.3 deployment descriptor describes a collection of Web components and their environment. The ENC for a Web application is declared globally for all servlets and JSP pages in the Web application. Because the Web application developer generally cannot know into what environment the Web application will be deployed, the developer describes the component environment in a deployment environment independent manner using logical names. It is the responsibility of a deployment administrator to link the Web component logical names to the corresponding deployment environment resources.
See The ENC elements in the standard servlet 2.3 web.xml deployment descriptor.. gives a graphical view of the Web application deployment descriptor DTD without the non-ENC elements. The full web.xml DTD is available from the Sun Web site at http://java.sun.com/dtd/web-app_2_3.dtd .
The jboss.xml ENC Elements
The JBoss EJB deployment descriptor provides the mapping from the EJB component ENC JNDI names to the actual deployed JNDI name. It is the responsibility of the application deployer to map the logical references made by the application component to the corresponding physical resource deployed in a given application server configuration. In JBoss, this is done for the ejb-jar.xml descriptor using the jboss.xml deployment descriptor. See The ENC elements in the JBoss 3.2 jboss.xml deployment descriptor.. gives a graphical view of the JBoss EJB deployment descriptor DTD without the non-ENC elements. This is virtually identical to the corresponding elements of the ejb-jar.xml for the levels shown.
The jboss-web.xml ENC Elements
The JBoss Web deployment descriptor provides the mapping from the Web application ENC JNDI names to the actual deployed JNDI name. It is the responsibility of the application deployer to map the logical references made by the Web application to the corresponding physical resource deployed in a given application server configuration. In JBoss, this is done for the web.xml descriptor using the jboss-web.xml deployment descriptor.See The ENC elements in the JBoss 3.2 jboss-web.xml deployment descriptor.. gives a graphical view of the JBoss Web deployment descriptor DTD without the non-ENC elements. The full jboss-web.xml DTD is available from the JBoss Web site at http://www.jboss.org/j2ee/dtd/jboss_web_3_2.dtd as well as the docs/dtd directory of the distribution.
Environment Entries
Environment entries are the simplest form of information stored in a component ENC, and are similar to operating system environment variables like those found on Unix or Windows. Environment entries are a name-to-value binding that allows a component to externalize a value and refer to the value using a name.
An environment entry is declared using an env-entry element in the standard deployment descriptors. The env-entry element contains the following child elements:
- An optional description element that provides a description of the entry
- An env-entry-name element giving the name of the entry relative to java:comp/env
- An env-entry-type element giving the Java type of the entry value that must be one of:
- java.lang.Byte
- java.lang.Boolean
- java.lang.Character
- java.lang.Double
- java.lang.Float
- java.lang.Integer
- java.lang.Long
- java.lang.Short
- java.lang.String
- An env-entry-value element giving the value of entry as a string
An example of an env-entry fragment from an ejb-jar.xml deployment descriptor is given in See An example ejb-jar.xml env-entry fragment.. There is no JBoss specific deployment descriptor element because an env-entry is a complete name and value specification. See ENC env-entry access code fragment. shows a sample code fragment for accessing the maxExemptions and taxRate env-entry values declared in See An example ejb-jar.xml env-entry fragment. .
An example ejb-jar.xml env-entry fragment
<ejb-name>ASessionBean</ejb-name>
<description>The maximum number of tax exemptions allowed
<env-entry-name>maxExemptions</env-entry-name>
<env-entry-type>java.lang.Integer</env-entry-type>
<env-entry-value>15</env-entry-value>
<env-entry-name>taxRate</env-entry-name>
<env-entry-type>java.lang.Float</env-entry-type>
EJB References
It is common for EJBs and Web components to interact with other EJBs. Because the JNDI name under which an EJB home interface is bound is a deployment time decision, there needs to be a way for a component developer to declare a reference to an EJB that will be linked by the deployer. EJB references satisfy this requirement.
An EJB reference is a link in an application component naming environment that points to a deployed EJB home interface. The name used by the application component is a logical link that isolates the component from the actual name of the EJB home in the deployment environment. The J2EE specification recommends that all references to enterprise beans be organized in the java:comp/env/ejb context of the application component's environment.
An EJB reference is declared using an ejb-ref element in the deployment descriptor. Each ejb-ref element describes the interface requirements that the referencing application component has for the referenced enterprise bean. The ejb-ref element contains the following child elements:
- An optional description element that provides the purpose of the reference.
- An ejb-ref-name element that specifies the name of the reference relative to the java:comp/env context. To place the reference under the recommended java:comp/env/ejb context, use an ejb/link-name form for the ejb-ref-name value.
- An ejb-ref-type element that specifies the type of the EJB. This must be either Entity or Session.
- A home element that gives the fully qualified class name of the EJB home interface.
- A remote element that gives the fully qualified class name of the EJB remote interface.
- An optional ejb-link element that links the reference to another enterprise bean in the ejb-jar file or in the same J2EE application unit. The ejb-link value is the ejb-name of the referenced bean. If there are multiple enterprise beans with the same ejb-name, the value uses the path name specifying the location of the ejb-jar file that contains the referenced component. The path name is relative to the referencing ejb-jar file. The Application Assembler appends the ejb-name of the referenced bean to the path name separated by #. This allows multiple beans with the same name to be uniquely identified.
An EJB reference is scoped to the application component whose declaration contains the ejb-ref element. This means that the EJB reference is not accessible from other application components at runtime, and that other application components may define ejb-ref elements with the same ejb-ref-name without causing a name conflict. See An example ejb-jar.xml ejb-ref descriptor fragment. provides an ejb-jar.xml fragment that illustrates the use of the ejb-ref element. A code sample that illustrates accessing the ShoppingCartHome reference declared in See An example ejb-jar.xml ejb-ref descriptor fragment. is given in See ENC ejb-ref access code fragment..
An example ejb-jar.xml ejb-ref descriptor fragment
<ejb-name>ShoppingCartBean</ejb-name>
<ejb-name>ProductBeanUser</ejb-name>
<description>This is a reference to the store products entity
<ejb-ref-name>ejb/ProductHome</ejb-ref-name>
<ejb-ref-type>Entity</ejb-ref-type>
<home>org.jboss.store.ejb.ProductHome</home>
</ejb-ref> <remote> org.jboss.store.ejb.Product</remote>
<ejb-name>ShoppingCartUser</ejb-name>
<ejb-ref-name>ejb/ShoppingCartHome</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<home>org.jboss.store.ejb.ShoppingCartHome</home>
<remote> org.jboss.store.ejb.ShoppingCart</remote>
<ejb-link>ShoppingCartBean</ejb-link>
<description>The Product entity bean
EJB References with jboss.xml and jboss-web.xml
The JBoss server jboss.xml EJB deployment descriptor affects EJB references in two ways. First, the jndi-name child element of the session and entity elements allows the user to specify the deployment JNDI name for the EJB home interface. In the absence of a jboss.xml specification of the jndi-name for an EJB, the home interface is bound under the ejb-jar.xml ejb-name value. For example, the session EJB with the ejb-name of ShoppingCartBean in Listing 3.5 would have its home interface bound under the JNDI name ShoppingCartBean in the absence of a jboss.xml jndi-name specification.
The second use of the jboss.xml descriptor with respect to ejb-refs is the setting of the destination to which a component's ENC ejb-ref refers. The ejb-link element cannot be used to refer to EJBs in another enterprise application. If your ejb-ref needs to access an external EJB, you can specify the JNDI name of the deployed EJB home using the jboss.xml ejb-ref/jndi-name element.
The jboss-web.xml descriptor is used only to set the destination to which a Web application ENC ejb-ref refers. The content model for the JBoss ejb-ref is as follows:
- An ejb-ref-name element that corresponds to the ejb-ref-name element in the ejb-jar.xml or web.xml standard descriptor
- A jndi-name element that specifies the JNDI name of the EJB home interface in the deployment environment
See An example jboss.xml ejb-ref fragment. provides an example jboss.xml descriptor fragment that illustrates the following usage points:
EJB Local References
In EJB 2.0 one can specify non-remote interfaces called local interfaces that do not use RMI call by value semantics. These interfaces use a call by reference semantic and therefore do not incur any RMI serialization overhead. An EJB local reference is a link in an application component naming environment that points to a deployed EJB local home interface. The name used by the application component is a logical link that isolates the component from the actual name of the EJB local home in the deployment environment. The J2EE specification recommends that all references to enterprise beans be organized in the java:comp/env/ejb context of the application component's environment.
An EJB local reference is declared using an ejb-local-ref element in the deployment descriptor. Each ejb-local-ref element describes the interface requirements that the referencing application component has for the referenced enterprise bean. The ejb-local-ref element contains the following child elements:
- An optional description element that provides the purpose of the reference.
- An ejb-ref-name element that specifies the name of the reference relative to the java:comp/env context. To place the reference under the recommended java:comp/env/ejb context, use an ejb/link-name form for the ejb-ref-name value.
- An ejb-ref-type element that specifies the type of the EJB. This must be either Entity or Session.
- A local-home element that gives the fully qualified class name of the EJB local home interface.
- A local element that gives the fully qualified class name of the EJB local interface.
- An ejb-link element that links the reference to another enterprise bean in the ejb-jar file or in the same J2EE application unit. The ejb-link value is the ejb-name of the referenced bean. If there are multiple enterprise beans with the same ejb-name, the value uses the path name specifying the location of the ejb-jar file that contains the referenced component. The path name is relative to the referencing ejb-jar file. The Application Assembler appends the ejb-name of the referenced bean to the path name separated by #. This allows multiple beans with the same name to be uniquely identified. An ejb-link element must be specified in JBoss to match the local reference to the corresponding EJB.
An EJB local reference is scoped to the application component whose declaration contains the ejb-local-ref element. This means that the EJB local reference is not accessible from other application components at runtime, and that other application components may define ejb-local-ref elements with the same ejb-ref-name without causing a name conflict. See An example ejb-jar.xml ejb-local-ref descriptor fragment. provides an ejb-jar.xml fragment that illustrates the use of the ejb-local-ref element. A code sample that illustrates accessing the ProbeLocalHome reference declared in See An example ejb-jar.xml ejb-local-ref descriptor fragment. is given in See ENC ejb-local-ref access code fragment..
An example ejb-jar.xml ejb-local-ref descriptor fragment
<home>org.jboss.test.perf.interfaces.ProbeHome</home>
<remote>org.jboss.test.perf.interfaces.Probe</remote>
<local-home>org.jboss.test.perf.interfaces.ProbeLocalHome</local-home>
<local>org.jboss.test.perf.interfaces.ProbeLocal</local>
<ejb-class>org.jboss.test.perf.ejb.ProbeBean</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Bean</transaction-type>
<ejb-name>PerfTestSession</ejb-name>
<home>org.jboss.test.perf.interfaces.PerfTestSessionHome</home>
<remote>org.jboss.test.perf.interfaces.PerfTestSession</remote>
<ejb-class>org.jboss.test.perf.ejb.PerfTestSessionBean</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
<ejb-ref-name>ejb/ProbeHome</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<home>org.jboss.test.perf.interfaces.SessionHome</home>
<remote>org.jboss.test.perf.interfaces.Session</remote>
<ejb-ref-name>ejb/ProbeLocalHome</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<local-home>org.jboss.test.perf.interfaces.ProbeLocalHome</local-home>
Resource Manager Connection Factory References
Resource manager connection factory references allow application component code to refer to resource factories using logical names called resource manager connection factory references. Resource manager connection factory references are defined by the resource-ref elements in the standard deployment descriptors. The Deployer binds the resource manager connection factory references to the actual resource manager connection factories that exist in the target operational environment using the jboss.xml and jboss-web.xml descriptors.
Each resource-ref element describes a single resource manager connection factory reference. The resource-ref element consists of the following child elements:
- An optional description element that provides the purpose of the reference.
- A res-ref-name element that specifies the name of the reference relative to the java:comp/env context. The resource type based naming convention for which subcontext to place the res-ref-name into is discussed in the next paragraph.
- A res-type element that specifies the fully qualified class name of the resource manager connection factory.
- A res-auth element that indicates whether the application component code performs resource signon programmatically, or whether the container signs on to the resource based on the principal mapping information supplied by the Deployer. It must be one of Application or Container.
- An option res-sharing-scope element. This currently is not supported by JBoss.
The J2EE specification recommends that all resource manager connection factory references be organized in the subcontexts of the application component's environment, using a different subcontext for each resource manager type. The recommended resource manager type to subcontext name is as follows:
- JDBC DataSource references should be declared in the java:comp/env/jdbc subcontext.
- JMS connection factories should be declared in the java:comp/env/jms subcontext.
- JavaMail connection factories should be declared in the java:comp/env/mail subcontext.
- URL connection factories should be declared in the java:comp/env/url subcontext.
See A web.xml resource-ref descriptor fragment. shows an example web.xml descriptor fragment that illustrates the resource-ref element usage. See ENC resource-ref access sample code fragment. provides a code fragment that an application component would use to access the DefaultMail resource defined in See A web.xml resource-ref descriptor fragment..
A web.xml resource-ref descriptor fragment
<servlet-name>AServlet</servlet-name>
<!-- JDBC DataSources (java:comp/env/jdbc) -->
<description>The default DS</description>
<res-ref-name>jdbc/DefaultDS</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
<!-- JavaMail Connection Factories (java:comp/env/mail) -->
<description>Default Mail</description>
<res-ref-name>mail/DefaultMail</res-ref-name>
<res-type>javax.mail.Session</res-type>
<res-auth>Container</res-auth>
<!-- JMS Connection Factories (java:comp/env/jms) -->
<description>Default QueueFactory</description>
<res-ref-name>jms/QueFactory</res-ref-name>
<res-type>javax.jms.QueueConnectionFactory</res-type>
Resource Manager Connection Factory References with jboss.xml and jboss-web.xml
The purpose of the JBoss jboss.xml EJB deployment descriptor and jboss-web.xml Web application deployment descriptor is to provide the link from the logical name defined by the res-ref-name element to the JNDI name of the resource factory as deployed in JBoss. This is accomplished by providing a resource-ref element in the jboss.xml or jboss-web.xml descriptor. The JBoss resource-ref element consists of the following child elements:
- A res-ref-name element that must match the res-ref-name of a corresponding resource-ref element from the ejb-jar.xml or web.xml standard descriptors
- An optional res-type element that specifies the fully qualified class name of the resource manager connection factory
- A jndi-name element that specifies the JNDI name of the resource factory as deployed in JBoss
- A res-url element that specifies the URL string in the case of a resource-ref of type java.net.URL
See A sample jboss-web.xml resource-ref descriptor fragment. provides a sample jboss-web.xml descriptor fragment that shows sample mappings of the resource-ref elements given in See A web.xml resource-ref descriptor fragment..
A sample jboss-web.xml resource-ref descriptor fragment
<res-ref-name>jdbc/DefaultDS</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<jndi-name>java:/DefaultDS</jndi-name>
<res-ref-name>mail/DefaultMail</res-ref-name>
<res-type>javax.mail.Session</res-type>
<jndi-name>java:/Mail</jndi-name>
<res-ref-name>jms/QueFactory</res-ref-name>
<res-type>javax.jms.QueueConnectionFactory</res-type>
Resource Environment References
Resource environment references are elements that refer to administered objects that are associated with a resource (for example, JMS destinations) by using logical names. Resource environment references are defined by the resource-env-ref elements in the standard deployment descriptors. The Deployer binds the resource environment references to the actual administered objects location in the target operational environment using the jboss.xml and jboss-web.xml descriptors.
Each resource-env-ref element describes the requirements that the referencing application component has for the referenced administered object. The resource-env-ref element consists of the following child elements:
- An optional description element that provides the purpose of the reference.
- A resource-env-ref-name element that specifies the name of the reference relative to the java:comp/env context. Convention places the name in a subcontext that corresponds to the associated resource factory type. For example, a JMS queue reference named MyQueue should have a resource-env-ref-name of jms/MyQueue.
- A resource-env-ref-type element that specifies the fully qualified class name of the referenced object. For example, in the case of a JMS queue, the value would be javax.jms.Queue.
See An example ejb-jar.xml resource-env-ref fragment. provides an example resource-ref-env element declaration by a session bean. See ENC resource-env-ref access code fragment. gives a code fragment that illustrates
Resource Environment References and jboss.xml, jboss-web.xml
The purpose of the JBoss jboss.xml EJB deployment descriptor and jboss-web.xml Web application deployment descriptor is to provide the link from the logical name defined by the resource-env-ref-name element to the JNDI name of the administered object deployed in JBoss. This is accomplished by providing a resource-env-ref element in the jboss.xml or jboss-web.xml descriptor. The JBoss resource-env-ref element consists of the following child elements:
- A resource-env-ref-name element that must match the resource-env-ref-name of a corresponding resource-env-ref element from the ejb-jar.xml or web.xml standard descriptors
- A jndi-name element that specifies the JNDI name of the resource as deployed in JBoss
See A sample jboss.xml resource-env-ref descriptor fragment. provides a sample jboss.xml descriptor fragment that shows a sample mapping for the resource-env-ref element given in See An example ejb-jar.xml resource-env-ref fragment..
The JBossNS Architecture
The JBossNS architecture is a Java socket/RMI based implementation of the j avax.naming.Context interface. It is a client/server implementation that can be accessed remotely. The implementation is optimized so that access from within the same VM in which the JBossNS server is running does not involve sockets. Same VM access occurs through an object reference available as a global singleton.See Key components in the JBossNS architecture.. illustrates some of the key classes in the JBossNS implementation and their relationships.
FIGURE 3-5. Key components in the JBossNS architecture.
We will start with the NamingService MBean. The NamingService MBean provides the JNDI naming service. This is a key service used pervasively by the J2EE technology components. The configurable attributes for the NamingService are as follows:
- Port: The jnp protocol listening port for the NamingService . If not specified default is 1099, the same as the RMI registry default port.
- RmiPort: The RMI port on which the RMI Naming implementation will be exported. If not specified the default is 0 which means use any available port.
- BindAddress: The specific address the NamingService listens on. This can be used on a multi-homed host for a java.net.ServerSocket that will only accept connect requests on one of its addresses.
- RmiBindAddress: The specific address the RMI server portion of the NamingService listens on. This can be used on a multi-homed host for a java.net.ServerSocket that will only accept connect requests on one of its addresses. If this is not specified and the BindAddress is, the RmiBindAddress defaults to the BindAddress value.
- Backlog: The maximum queue length for incoming connection indications (a request to connect) is set to the backlog parameter. If a connection indication arrives when the queue is full, the connection is refused.
- ClientSocketFactory: An optional custom java.rmi.server.RMIClientSocketFactory implementation class name. If not specified the default RMIClientSocketFactory is used.
- ServerSocketFactory: An optional custom java.rmi.server.RMIServerSocketFactory implementation class name. If not specified the default RMIServerSocketFactory is used.
- JNPServerSocketFactory, An optional custom javax.net.ServerSocketFactory implementation class name. This is the factory for the ServerSocket used to bootstrap the download of the JBossNS Naming interface. If not specified the javax.net.ServerSocketFactory.getDefault() method value is used.
The NamingService also creates the java:comp context such that access to this context is isolated based on the context ClassLoader of the thread that accesses the java:comp context. This provides the application component private ENC that is required by the J2EE specs. The segregation of java:comp by ClassLoader is accomplished by binding a javax.naming.Reference to a Context that uses the org.jboss.naming.ENCFactory as its javax.naming.ObjectFactory . When a client performs a lookup of java:comp, or any subcontext, the ENCFactory checks the thread context ClassLoader, and performs a lookup into a map using the ClassLoader as the key. If a Context instance does not exist for the ClassLoader instance, one is created and associated with the ClassLoader in the ENCFactory map. Thus, correct isolation of an application component's ENC relies on each component receiving a unique ClassLoader that is associated with the component threads of execution.The NamingService delegates its functionality to an org.jnp.server.Main MBean. The reason for the duplicate MBeans is because JBossNS started out as a stand-alone JNDI implementation, and can still be run as such. The NamingService MBean embeds the Main instance into the JBoss server so that usage of JNDI with the same VM as the JBoss server does not incur any socket overhead. The configurable attributes of the NamingService are really the configurable attributes of the JBossNS Main MBean. The setting of any attributes on the NamingService MBean simply set the corresponding attributes on the Main MBean the NamingService contains. When the NamingService is started, it starts the contained Main MBean to activate the JNDI naming service. In addition, the NamingService exposes the Naming interface operations through a JMX detyped invoke operation. This allows the naming service to be accessed via arbitrary protocol to JMX adaptors. We will look at an example of how HTTP can be used to access the naming service using the invoke operation later in this chapter.
The details of threads and the thread context class loader won't be explored here, but the JNDI tutorial provides a concise discussion that is applicable. See http://java.sun.com/products/jndi/tutorial/beyond/misc/classloader.html for the details.
When the Main MBean is started, it performs the following tasks:
- Instantiates an org.jnp.naming.NamingService instance and sets this as the local VM server instance. This is used by any org.jnp.interfaces.NamingContext instances that are created within the JBoss server VM to avoid RMI calls over TCP/IP.
- Exports the NamingServer instance's org.jnp.naming.interfaces.Naming RMI interface using the configured RmiPort, ClientSocketFactory, ServerSocketFactory attributes.
- Creates a socket that listens on the interface given by the BindAddress and Port attributes.
- Spawns a thread to accept connections on the socket.
The Naming InitialContext Factories
The JBoss JNDI provider currently supports three different InitialContext factory implementations. The most commonly used factory is the org.jnp.interfaces.NamingContextFactory implementation. Its 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. For JBossNS the URL format is jnp://host:port/[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 option 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.
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 .
Naming Discovery in Clustered Environments
When running in a clustered JBoss environment, you can choose not to specify a Context.PROVIDER_URL value and let the client query the network for available naming services. This only works with JBoss servers running with the all configuration, or an equivalent configuration that has org.jboss.ha.framework.server.ClusterPartition and org.jboss.ha.jndi.HANamingService services deployed. The discovery process consists of sending a multicast request packet to the discovery address/port and waiting for any node to respond. The response is a HA-RMI version of the Naming interface. The following InitialContext proerties affect the discovery configuration:
- 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.
- 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.disableDiscovery, A flag indicating if the discovery process should be avoided. Discovery occurs when either no Context.PROVIDER_URL is specified, or no valid naming service could be located among the URLs specified. If the jnp.disableDiscovery flag is true, then discovery will not be attempted.
The HTTP InitialContext Factory Implementation
The JNDI naming service can be accessed over HTTP. From a JNDI client's perspective this is a transparent change as they continue to use the JNDI Context interface. Operations through the Context interface are translated into HTTP posts to a servlet that passes the request to the NamingService using its JMX invoke operation. Advantages of using HTTP as the access protocol include better access through firewalls and proxies setup to allow HTTP, as well as the ability to secure access to the JNDI service using standard servlet role based security.
To access JNDI over HTTP you use the org.jboss.naming.HttpNamingContextFactory as the factory implementation. The complete set of support InitialContext environment properties for this factory are:
- java.naming.factory.initial (or Context.INITIAL_CONTEXT_FACTORY ), The name of the environment property for specifying the initial context factory, which must be org.jboss.naming.HttpNamingContextFactory .
- java.naming.provider.url (or Context.PROVIDER_URL ), This must be set to the http URL of the JMX invoker servlet. It depends on the configuration of the http-invoker.sar and its contained war, but the default setup places the JMX invoker servlet under /invoker/JMXInvokerServlet. The full http URL would be the public URL of the JBoss servlet container + "/invoker/JMXInvokerServlet". Examples include
- http://www.jboss.org:8080/invoker/JMXInvokerServlet
- http://www.jboss.org/invoker/JMXInvokerServlet
- https://www.jboss.org/invoker/JMXInvokerServlet
- java.naming.factory.url.pkgs (or Context.URL_PKG_PREFIXES ), For all 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.
where the first accesses the servlet using the port 8080, the second uses the standar HTTP port 80, and the third uses an SSL encrypted connection to the standard HTTPS port 443.
The JNDI Context implementation returned by the HttpNamingContextFactory is a proxy that delegates invocations made on it to a bridge servlet which forwards the invocation to the NamingService through the JMX bus, and marshalls the reply back over HTTP. The proxy needs to know what the URL of the bridge servlet is in order to operate. This value may have been bound on the server side if the JBoss web server has a well known public interface. If the JBoss web server is sitting behind one or more firewalls or proxies, the proxy cannot know what URL is required. In this case, the proxy will be associated with a system property value that must be set in the client VM. For more information on the operation of JNDI over HTTP See Accessing JNDI over HTTP.
The Login InitialContext Factory Implementation
Historically JBoss has not supported providing login information via the IntialContext factory environment. The reason being that JAAS provides a much more flexible framework. For simplicity and migration from other application server environment that do make use of this mechanism, JBoss-3.0.3 adds a new InitialContext factory implementation that allows this. JAAS is still used under in the implementation, but there is no manifest use of the JAAS interfaces in the client application.
The factory class that provides this capability is the org.jboss.security.jndi.LoginInitialContextFactory . The complete set of support InitialContext environment properties for this factory are:
- java.naming.factory.initial (or Context.INITIAL_CONTEXT_FACTORY ), The name of the environment property for specifying the initial context factory, which must be org.jboss.security.jndi.LoginInitialContextFactory .
- java.naming.provider.url (or Context.PROVIDER_URL ), This must be set to a NamingContextFactory provider URL. The LoginIntialContext is really just a wrapper around the NamingContextFactory that adds a JAAS login to the existing NamingContextFactory behavior.
- java.naming.factory.url.pkgs (or Context.URL_PKG_PREFIXES ), For all 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.
- java.naming.security.principal (or Context.SECURITY_PRINCIPAL ), The principal to authenticate. This may be either a java.security.Principal implementation or a string representing the name of a principal.
- java.naming.security.credentials (or Context.SECURITY_CREDENTIALS ), The credentials that should be used to authenticate the principal, e.g., password, session key, etc.
- java.naming.security.protocol (or Context.SECURITY_PROTOCOL ), This gives the name of the JAAS login module to use for the authentication of the principal and credentials.
Accessing JNDI over HTTP
In addition to the legacy RMI/JRMP with a socket bootstrap protocol, JBoss-3.0.3 provides support for accessing its JNDI naming service using HTTP. This capability is provided by the http-invoker.sar deployment and its contained services and servlets. The structure of the http-invoker.sar is:
| +- WEB-INF/classes/org/jboss/invocation/http/servlet/InvokerServlet.class
| +- WEB-INF/classes/org/jboss/invocation/http/servlet/NamingFactoryServlet.class
| +- WEB-INF/classes/org/jboss/invocation/http/servlet/ReadOnlyAccessFilter.class
| +- WEB-INF/classes/roles.properties
| +- WEB-INF/classes/users.properties
The http-invoker.sar jboss-service.xml descriptor defines the HttpInvoker and HttpInvokerHA MBeans. These services handle the routing of methods invocations that are sent via HTTP to the approriate target MBean on the JMX bus.
The http-invoker.war web application contains servlets that handle the details of the HTTP transport. The NamingFactoryServlet handles creation requests for the JBoss JNDI naming service javax.naming.Context implementation. The InvokerServlet handles invocations made by RMI/HTTP clients. The ReadOnlyAccessFilter allows one to secure the JNDI naming service while making a single JNDI context available for read-only access by unauthenticated clients.
FIGURE 3-6. The HTTP invoker proxy/server structure for a JNDI Context
Before looking at the configurations let's overview the operation of the http-invoker services. See The HTTP invoker proxy/server structure for a JNDI Context. shows a logical view of the structure of a JBoss JNDI proxy and its relationship to the JBoss server side components of the http-invoker. The proxy is obtained from the NamingFactoryServlet using an InitialContext with the Context.INITIAL_CONTEXT_FACTORY property set to org.jboss.naming.HttpNamingContextFactory , and the Context.PROVIDER_URL property set to the http URL of the NamingFactoryServlet . The resulting proxy is embedded in an org.jnp.interfaces.NamingContext instance that provides the Context interface implementation.
The proxy is an instance of org.jboss.invocation.http.interfaces.HttpInvokerProxy , and implements the org.jnp.interfaces.Naming interface. Internally the HttpInvokerProxy contains an invoker that marshalls the Naming interface method invocations to the InvokerServlet via HTTP posts. The InvokerServlet translates these posts into JMX invocations to the NamingService , and returns the invocation response back to the proxy in the HTTP post reponse.
There are several configuration values that need to be set to tie all of these components together and See The relationship between configuration files and JNDI/HTTP component. illustrates the relationship between configuration files and the corresponding components.
FIGURE 3-7. The relationship between configuration files and JNDI/HTTP component
The http-invoker.sar/META-INF/jboss-service.xml descriptor defines the HttpProxyFactory that creates the HttpInvokerProxy for the NamingService . The attributes that need to be configured for the HttpProxyFactory include:
- InvokerName, the JMX ObjectName of the NamingService defined in the conf/jboss-service.xml descriptor. The standard setting used in the JBoss distributions is "jboss:service=Naming".
- InvokerURL, or InvokerURLPrefix + InvokerURLSuffix + UseHostName. You can specify the full http URL to the InvokerServlet using the InvokerURL attribute, or you can specify the hostname independent parts of the URL and have the HttpProxyFactory fill them in. An example InvokerURL value would be "http://jbosshost1.dot.com:8080/invoker/JMXInvokerServlet". This can be broken down into:
- InvokerURLPrefix, the url prefix prior to the hostname. Typically this will be "http://" or "https://" is SSL is to be used. For the example InvokerURL value the InvokerURLPrefix would be "http://" without the quotes.
- InvokerURLSuffix, the url suffix after the hostname. This will include the port number of the web server as well as the deployed path to the InvokerServlet . For the example InvokerURL value the InvokerURLSuffix would be ":8080/invoker/JMXInvokerServlet" without the quotes. The port number is determined by the web container service settings. The path to the InvokerServlet is specified in the http-invoker.sar/invoker.war/WEB-INF/web.xml descriptor.
- UseHostName, a flag indicating if the hostname or host IP address should be used when building the hostname portion of the full InvokerURL. If true, InetAddress.getLocalHost().getHostName method will be used, else, the InetAddress.getLocalHost().getHostAddress() method is used.
- ExportedInterface, is the org.jnp.interfaces.Naming interface the proxy will expose to clients. The actual client of this proxy is the JBoss JNDI implementation NamingContext class, which JNDI client obtain from InitialContext lookups when using the JBoss JNDI provider.
- JndiName, is the name in JNDI under which the proxy is bound. This needs to be set to a blank/empty string to indicate the interface should not be bound into JNDI. We can't use the JNDI to bootstrap itself. This is the role of the NamingFactoryServlet.
The http-invoker.sar/invoker.war/WEB-INF/web.xml descriptor defines the mappings of the NamingFactoryServlet and InvokerServet along with their initialzation parameters. The configuration of the NamingFactoryServlet relevant to JNDI/HTTP is the JNDIFactory entry which defines:
- A namingProxyMBean initialzation parameter that maps to the HttpProxyFactory MBean name. This is used by the NamingFactoryServlet to obtain the Naming proxy which it will return in response to http posts. For the default http-invoker.sar/META-INF/jboss-service.xml settings the name "jboss:service=invoker,type=http,target=Naming".
- A proxy initialzation parameter that defines the name of the namingProxyMBean attribute to query for the Naming proxy value. This defaults to an attribute name of "Proxy".
- The servlet mapping for the JNDIFactory configuration. The default setting for the unsecured mapping is "/JNDIFactory/*". This is relative to the context root of the http-invoker.sar/invoker.war, which by default is the war name minus the ".war" suffix.
The configuration of the InvokerServlet relevant to JNDI/HTTP is the JMXInvokerServlet which defines:
Accessing JNDI over HTTPS
To be able to access JNDI over HTTP/SSL you need to enable an SSL connector on the web container. The details of this are convered in the Integrating Servlet Containers for Tomcat. We will demonstrate the use of HTTPS with a simple example client that uses an https URL as the JNDI provider URL. We will provide an SSL connector configuration for the example, so unless you are interested in the details of the SSL connector setup, the example is self contained.
We also provide a configuration of the HttpProxyFactory setup to use an https URL. shows the section of the http-invoker.sar jboss-service.xml descriptor that the example installs to provide this configuration. All the has changed relative to the standard http configuration are the InvokerURLPrefix and InvokerURLSuffix attributes, which setup an https URL using the 8443 port.
<!-- Expose the Naming service interface via HTTPS -->
<mbean code="org.jboss.invocation.http.server.HttpProxyFactory"
name="jboss:service=invoker,type=https,target=Naming">
<!-- The Naming service we are proxying -->
<attribute name="InvokerName">jboss:service=Naming</attribute>
<!-- Compose the invoker URL from the cluster node address -->
<attribute name="InvokerURLPrefix">https://</attribute>
<attribute name="InvokerURLSuffix">:8443/invoker/JMXInvokerServlet
<attribute name="UseHostName">true</attribute>
<attribute name="ExportedInterface">org.jnp.interfaces.Naming
<attribute name="JndiName"></attribute>
<attribute name="ClientInterceptors">
<interceptor>org.jboss.proxy.ClientMethodInterceptor
<interceptor>org.jboss.proxy.SecurityInterceptor</interceptor>
<interceptor>org.jboss.naming.interceptors.ExceptionInterceptor
<interceptor>org.jboss.invocation.InvokerInterceptor
At a minimum, a JNDI client using HTTPS requires setting up a https URL protocol handler. We will be using the Java Secure Socket Extension (JSSE) for HTTPS. The JSSE documentation does a good job of describing what is necessary to use https, and the following steps were needed to configure the example client shown in See A JNDI client that uses HTTPS as the transport.:
- A protocol handler for https URLs must be made available to Java. The JSSE release includes an https handler in the com.sun.net.ssl.internal.www.protocol package. To enable the use of https URLs you include this package in the standard URL protocol handler search property, java.protocol.handler.pkgs. We set the java.protocol.handler.pkgs property in the Ant script.
- The JSSE security provider must be installed in order for SSL to work. This can be done either by installing the JSSE jars as an extension package, or programatically. We use the programatic approach in the example since this is less intrusive. Line 18 of the ExClient code demonstrates how this is done.
- The JNDI provider URL must use https as the protocol. Lines 24-25 of the ExClient code specify an HTTP/SSL connection to the localhost on port 8443. The hostname and port are defined by the web container SSL connector.
- The validation of the https URL hostname against the server certificate must be disabled. By default, the JSSE https protocol handler employs a strict validation of the hostname portion of the https URL against the common name of the server certificate. This is the same check done by web browsers when you connect to secured web site. We are using a self-signed server certificate that uses a common name of "Chapter8 SSL Example" rather than a particular hostname, and this is likely to be common in development environments or intranets. The JBoss HttpInvokerProxy will override the default hostname checking if a org.jboss.security.ignoreHttpsHost system property exists and has a value of true. We set the org.jboss.security.ignoreHttpsHost property to true in the Ant script.
A JNDI client that uses HTTPS as the transport
- package org.jboss.chap3.ex1;
- import java.security.Security;
- import java.util.Properties;
- import javax.naming.Context;
- import javax.naming.InitialContext;
- /** A simple JNDI client that uses HTTPS as the transport.
- *
- * @author [email protected]
- * @version $Revision: 1.1 $
- */
- public class ExClient
- {
- public static void main(String args[]) throws Exception
- {
- // Install the Sun JSSE provider since we may not have JSSE installed
- Security.addProvider(new com.sun.net.ssl.internal.ssl.Provider());
- System.out.println("Added JSSE security provider");
- Properties env = new Properties();
- env.setProperty(Context.INITIAL_CONTEXT_FACTORY,
- "org.jboss.naming.HttpNamingContextFactory");
- env.setProperty(Context.PROVIDER_URL,
- "https://localhost:8443/invoker/JNDIFactory");
- Context ctx = new InitialContext(env);
- System.out.println("Created InitialContext, env="+env);
- Object data = ctx.lookup("jmx/rmi/RMIAdaptor");
- System.out.println("lookup(jmx/rmi/RMIAdaptor): "+data);
- }
- }
To test the client given in See A JNDI client that uses HTTPS as the transport. , first build the chapter 3 example to create the chap3 configuration fileset as follows:
[nr@toki examples]$ ant -Dchap=chap3 config
[java] ImplementationTitle: JBoss [WonderLand]
[java] ImplementationVendor: JBoss.org
[java] ImplementationVersion: 3.2.3 (build: CVSTag=JBoss_3_2_3 date=200311301445)
[java] SpecificationTitle: JBoss
[java] SpecificationVendor: JBoss (http://www.jboss.org/)
[java] SpecificationVersion: 3.2.3
[java] JBoss version is: 3.2.3
[echo] Using jboss.dist=/tmp/jboss-3.2.3
[echo] Preparing chap3 configuration fileset
[mkdir] Created dir: /tmp/jboss-3.2.3/server/chap3
[copy] Copying 151 files to /tmp/jboss-3.2.3/server/chap3
[copy] Copied 3 empty directories to /tmp/jboss-3.2.3/server/chap3
[copy] Copying 1 file to /tmp/jboss-3.2.3/server/chap3/conf
[copy] Copying 1 file to /tmp/jboss-3.2.3/server/chap3/conf
[copy] Copying 1 file to /tmp/jboss-3.2.3/server/chap3/deploy/jbossweb-tomcat41.sar/META-INF
[copy] Copying 1 file to /tmp/jboss-3.2.3/server/chap3/deploy/http-invoker.sar/META-INF
[copy] Copying 1 file to /tmp/jboss-3.2.3/server/chap3/deploy/http-invoker.sar/invoker.war/WEB-INF
Next, start the JBoss server using the chap3 configuration fileset:
[nr@toki bin] ./run.sh -c chap3
===============================================================================
And finally, run the ExClient using:
[nr@toki examples]$ ant -Dchap=chap3 -Dex=1 run-example
[java] ImplementationTitle: JBoss [WonderLand]
[java] ImplementationVendor: JBoss.org
[java] ImplementationVersion: 3.2.3 (build: CVSTag=JBoss_3_2_3 date=200311301445)
[java] SpecificationTitle: JBoss
[java] SpecificationVendor: JBoss (http://www.jboss.org/)
[java] SpecificationVersion: 3.2.3
[java] JBoss version is: 3.2.3
[echo] Using jboss.dist=/tmp/jboss-3.2.3
[java] Created InitialContext, env={java.naming.provider.url=https://localhost:8443/invoker/JNDIFactorySSL, java.naming.factory.initial=org.jboss.naming.HttpNamingContextFactory}
[java] lookup(jmx/rmi/RMIAdaptor): org.jboss.invocation.jrmp.interfaces.JRMPInvokerProxy@781288
Securing Access to JNDI over HTTP
One benefit to accessing JNDI over HTTP is that it is easy to secure access to the JNDI InitialContext factory as well as the naming operations using standard web declarative security. This is possible because the server side handling of the JNDI/HTTP transport is implemented with two servlets. These servlets are included in the http-invoker.sar/invoker.war directory found in the default and all configuration deploy directories as shown previously. To enable secured access to JNDI you need to edit the invoker.war/WEB-INF/web.xml descriptor and remove all unsecured servlet mappings. For example, the web.xml descriptor shown in See An example web.xml descriptor for secured access to the JNDI servlets. only allows access to the invoker.war servlets if the user has been authenticated and has a role of HttpInvoker.
An example web.xml descriptor for secured access to the JNDI servlets
<?xml version="1.0" encoding="UTF-8"?>
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<servlet-name>JMXInvokerServlet</servlet-name>
<servlet-class>org.jboss.invocation.http.servlet.InvokerServlet</servlet-class>
<load-on-startup>1</load-on-startup>
<servlet-name>JNDIFactory</servlet-name>
<servlet-class>org.jboss.invocation.http.servlet.NamingFactoryServlet</servlet-class>
<param-name>namingProxyMBean</param-name>
<param-value>jboss:service=invoker,type=http,target=Naming</param-value>
<param-name>proxyAttribute</param-name>
<param-value>Proxy</param-value>
<load-on-startup>2</load-on-startup>
<servlet-name>JNDIFactory</servlet-name>
<url-pattern>/restricted/JNDIFactory/*</url-pattern>
<servlet-name>JMXInvokerServlet</servlet-name>
<url-pattern>/restricted/JMXInvokerServlet/*</url-pattern>
<web-resource-name>HttpInvokers</web-resource-name>
<description>An example security config that only allows users with the
role HttpInvoker to access the HTTP invoker servlets
<url-pattern>/restricted/*</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
<role-name>HttpInvoker</role-name>
<auth-method>BASIC</auth-method>
<realm-name>JBoss HTTP Invoker</realm-name>
<role-name>HttpInvoker</role-name>
The web.xml descriptor only defines which sevlets are secured, and which roles are allowed to access the secured servlets. You must additionally define the security domain that will handle the authentication and authorization for the war. This is done through the jboss-web.xml descriptor, and an example that uses the "http-invoker" security domain is given in .
An example jboss-web.xml descriptor to assign the
<security-domain>java:/jaas/http-invoker</security-domain>
The security-domain element defines the name of the security domain that will be used for the JAAS login module configuration used for authentication and authorization. See Enabling Declarative Security in JBoss for additional details on the meaning and configuration of the security domain name.
Securing Access to JNDI with a Read-Only Unsecured Context
Another feature available for the JNDI/HTTP naming service is the ability to define a context that can be accessed by unauthenticated users in read-only mode. This can be important for services used by the authentication layer. For example, the SRPLoginModule needs to lookup the SRP server interface used to perform authentication. To enable this, some additional web.xml descriptor settings are needed. See The additional web.xml descriptor elements needed for read-only access. shows the necessary elements.
The additional web.xml descriptor elements needed for read-only access
<filter-name>ReadOnlyAccessFilter</filter-name>
<filter-class>org.jboss.invocation.http.servlet.ReadOnlyAccessFilter</filter-class>
<param-name>readOnlyContext</param-name>
<param-value>readonly-context</param-value>
<param-name>invokerName</param-name>
<param-value>jboss:service=Naming</param-value>
<filter-name>ReadOnlyAccessFilter</filter-name>
<url-pattern>/readonly/*</url-pattern>
<servlet-name>ReadOnlyJNDIFactory</servlet-name>
<servlet-class>org.jboss.invocation.http.servlet.NamingFactoryServlet</servlet-class>
<param-name>namingProxyMBean</param-name>
<param-value>jboss:service=invoker,type=http,target=Naming,readonly=true</param-value>
<param-name>proxyAttribute</param-name>
<param-value>Proxy</param-value>
<load-on-startup>2</load-on-startup>
<!-- A mapping for the JMXInvokerServlet that only allows invocations
of lookups under a read-only context. This is enforced by the
<servlet-name>JMXInvokerServlet</servlet-name>
<url-pattern>/readonly/JMXInvokerServlet/*</url-pattern>
With these settings, one may perform Context.lookup operations on the "readonly-context" or its subcontexts, but no other operations on this context. Also, no operations of any kind may be performed on other contexts. Here is a code fragment for a lookup of the "readonly-context/data" binding:
Properties env = new Properties();
env.setProperty(Context.INITIAL_CONTEXT_FACTORY,
"org.jboss.naming.HttpNamingContextFactory");
env.setProperty(Context.PROVIDER_URL,
"http://localhost:8080/invoker/ReadOnlyJNDIFactory");
Additional Naming MBeans
In addition to the NamingService MBean that configures an embedded JBossNS server within JBoss, there are three additional MBean services related to naming that ship with JBoss. They are the ExternalContext , NamingAlias , and JNDIView .
org.jboss.naming.ExternalContext MBean
The ExternalContext MBean allows you to federate external JNDI contexts into the JBoss server JNDI namespace. The term external refers to any naming service external to the JBossNS naming service running inside of the JBoss server VM. You can incorporate LDAP servers, file systems, DNS servers, and so on, even if the JNDI provider root context is not serializable. The federation can be made available to remote clients if the naming service supports remote access.
To incorporate an external JNDI naming service, you have to add a configuration of the ExternalContext MBean service to the jboss.jcml configuration file. The configurable attributes of the ExternalContext service are as follows:
- JndiName--The JNDI name under which the external context is to be bound.
- RemoteAccess--A boolean flag indicating if the external InitialContext should be bound using a Serializable form that allows a remote client to create the external InitialContext . When a remote client looks up the external context via the JBoss JNDI InitialContext , they effectively create an instance of the external InitialContext using the same env properties passed to the ExternalContext MBean. This will only work if the client could do a 'new InitialContext(env)' remotely. This requires that the Context.PROVIDER_URL value of env is resolvable in the remote VM that is accessing the context. This should work for the LDAP example. For the file system example this most likely won't work unless the file system path refers to a common network path. If this property is not given it defaults to false.
- CacheContext--The cacheContext flag. When set to true, the external Context is only created when the MBean is started and then stored as an in memory object until the MBean is stopped. If cacheContext is set to false, the external Context is created on each lookup using the MBean properties and InitialContext class. When the uncached Context is looked up by a client, the client should invoke close() on the Context to prevent resource leaks.
- InitialContext--The fully qualified class name of the InitialContext implementation to use. Must be one of: javax.naming.InitialContext , javax.naming.directory.InitialDirContext or javax.naming.ldap.InitialLdapContext . In the case of the InitialLdapContext , a null Controls array is used. The default is javax.naming.InitialContex .
- Properties--Set the jndi.properties information for the external InitialContext . This is either a URL string or a classpath resource name. Examples are as follows:
- file:///config/myldap.properties
- http://config.mycompany.com/myldap.properties
- /conf/myldap.properties
- myldap.properties
The jboss.jcml fragment shown in See ExternalContext MBean configurations. shows two configurations--one for an LDAP server, and the other for a local file system directory.
ExternalContext MBean configurations
<!-- Bind a remote LDAP server -->
<mbean code="org.jboss.naming.ExternalContext"
name="jboss.jndi:service=ExternalContext,jndiName=external/ldap/jboss">
<attribute name="JndiName">external/ldap/jboss</attribute>
<attribute name="Properties">jboss.ldap</attribute>
<attribute name="InitialContext">
javax.naming.ldap.InitialLdapContext
</attribute>
<attribute name="RemoteAccess">true</attribute>
</mbean>
<!-- Bind the /usr/local file system directory -->
<mbean code="org.jboss.naming.ExternalContext"
name="jboss.jndi:service=ExternalContext,jndiName=external/fs/usr/local" >
<attribute name="JndiName">external/fs/usr/local</attribute>
<attribute name="Properties">local.props</attribute>
<attribute name="InitialContext">javax.naming.InitialContext</attribute>
</mbean>
The first configuration describes binding an external LDAP context into the JBoss JNDI namespace under the name "external/ldap/jboss". An example jboss.ldap properties file is as follows:
java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
java.naming.provider.url=ldap://ldaphost.jboss.org:389/o=jboss.org
java.naming.security.principal=cn=Directory Manager
java.naming.security.authentication=simple
java.naming.security.credentials=secret
With this configuration, you can access the external LDAP context located at ldap://ldaphost.jboss.org:389/o=jboss.org from within the JBoss VM using the following code fragment:
InitialContext iniCtx = new InitialContext();
LdapContext ldapCtx = iniCtx.lookup("external/ldap/jboss");
Using the same code fragment outside of the JBoss server VM will work in this case because the RemoteAccess property was set to true. If it were set to false, it would not work because the remote client would receive a Reference object with an ObjectFactory that would not be able to recreate the external IntialContext .
The second configuration describes binding a local file system directory /usr/local into the JBoss JNDI namespace under the name "external/fs/usr/local". An example local.props properties file is:
java.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory
java.naming.provider.url=file:///usr/local
With this configuration, you can access the external file system context located at file:///usr/local from within the JBoss VM using the following code fragment:
The org.jboss.naming.NamingAlias MBean
The NamingAlias MBean is a simple utility service that allows you to create an alias in the form of a JNDI javax.naming.LinkRef from one JNDI name to another. This is similar to a symbolic link in the Unix file system. To an alias you add a configuration of the NamingAlias MBean to the jboss.jcml configuration file. The configurable attributes of the NamingAlias service are as follows:
- FromName, The location where the LinkRef is bound under JNDI.
- ToName, The to name of the alias. This is the target name to which the LinkRef refers. The name is a URL, or a name to be resolved relative to the InitialContext, or if the first character of the name is., the name is relative to the context in which the link is bound.
An example that provides a mapping of the JNDI name "QueueConnectionFactory" to the name "ConnectionFactory" file is as follows:
<mbean code="org.jboss.naming.NamingAlias"
name="jboss.mq:service=NamingAlias,fromName=QueueConnectionFactory">
<attribute name="ToName">ConnectionFactory</attribute>
<attribute name="FromName">QueueConnectionFactory</attribute>
The org.jboss.naming.JNDIView MBean
The JNDIView MBean allows the user to view the JNDI namespace tree as it exists in the JBoss server using the JMX agent view interface. All that is required to use the JNDIView service is to add a configuration to jboss.jcml file. The JNDIView service has no configurable attributes, and so a suitable configuration is:
<mbean code="org.jboss.naming.JNDIView" name="jboss:service=JNDIView"/>
To view the JBoss JNDI namespace using the JNDIView MBean, you connect to the JMX Agent View using the http interface. The default settings put this at http://localhost:8080/jmx-console/ . On this page you will see a section that lists the registered MBeans by domain. It should look something like that shown in See The HTTP JMX agent view of the configured JBoss MBeans.., The HTTP JMX agent view of the configured JBoss MBeans., where the JNDIView MBean is under the mouse cursor.
FIGURE 3-8. The HTTP JMX agent view of the configured JBoss MBeans.
Selecting the JNDIView link takes you to the JNDIView MBean view, which will have a list of the JNDIView MBean operations. This view should look similar to that shown in See The HTTP JMX MBean view of the JNDIView MBean.., The HTTP JMX MBean view of the JNDIView MBean..
FIGURE 3-9. The HTTP JMX MBean view of the JNDIView MBean.
The list operation dumps out the JBoss server JNDI namespace as an html page using a simple text view. As an example, invoking the list operation for the default JBoss-3.0.1 distribution server produced the view shown in See The HTTP JMX view of the JNDIView list operation output.. .
