Naming on JBoss
This chapter is from the book
This chapter is from the book
This chapter is from the book
In This Chapter
- An Overview of JNDI
- The JBossNS Architecture
This chapter discusses the JBoss JNDI-based naming service, JBossNS, and the role of JNDI in JBoss and J2EE. It also provides an introduction to the basic JNDI API and common usage conventions. In this chapter, you'll also learn about the JBoss-specific configuration of J2EE component-naming environments defined by the standard deployment descriptors. The final topic in this chapter is the configuration and architecture of the JBoss naming service.
The JBoss naming service plays a key role in J2EE because it provides a naming service that allows a user to map a name to 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's Domain Name System (DNS). DNS allows you to refer to hosts by 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 JDK 1.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 of JNDI implementation, based on the SPI classes. Note that J2EE component developers do not need the JNDI SPI.
For a thorough introduction and tutorial on JNDI, which covers both the client and service provider APIs, see Sun’s tutorial at http://java.sun.com/products/jndi/tutorial/.
The JNDI API
The main JNDI API package is the javax.naming package. It contains 5 interfaces, 10 classes, and several exceptions. There is one key class, InitialContext, and there are 2 key interfaces, Context and Name.
Names in JNDI
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 that have 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.
For 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 the 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 is the hostname and file combination commonly used with Unix commands such as scp. For example, the following 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—that is, it is a string that cannot be parsed into smaller components. A file pathname in the Unix file system is an example of a compound name. 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. You can later retrieve the object by using its name, via the Context lookup method. A context typically provides 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.
For example, consider a file directory that has a pathname /usr and 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 the pathname /usr/jboss names a jboss context that is a subcontext of usr. As 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 by 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.InitialContext 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:
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 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, which allows the code to externalize the JNDI provider-specific information so that changing JNDI providers will not require changes to the code or recompilation.
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 classname of the javax.naming.spi.InitialContextFactory implementation. You obtain the name of the InitialContextFactory class from the naming service provider you are using.
Listing 3.1 gives a sample jndi.properties file that 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 JBoss JNDI implementation requires. Other JNDI providers have different properties and values.
Listing 3.1 A Sample jndi.properties File
### JBossNS properties java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory java.naming.provider.url=jnp://localhost:1099java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
J2EE and JNDI: The Application Component Environment
JNDI is a fundamental aspect of the J2EE specifications. One key usage of the JNDI is to isolate 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 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 the JNDI Context interface. The participants involved in the life cycle of a J2EE component utilize the ENC in the following ways:
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. Application component business logic should be coded to access information from its ENC.
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.4 specification, which is available at http://java.sun.com/j2ee/download.html.
An application component instance locates the ENC by 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. Listing 3.2 illustrates the prototypical lines of code a component uses to access its ENC.
Listing 3.2 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 vice 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 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. Components A and B, for example, 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 JBoss: names under java:comp, names under java:, and any other names. As discussed, the java:comp context and its subcontexts are available only to the application component associated with that particular context. Subcontexts and object bindings directly under java: are visible only within the JBoss server virtual machine and not to remote clients. Any other context or object binding is available to remote clients, provided that the context or object supports serialization. You’ll see how the isolation of these naming scopes is achieved in the next section.
An example of where restricting a binding to the java: context is useful is a javax.sql.DataSource connection factory that can be used only inside the JBoss server where the associated database pool resides. On the other hand, an EJB home interface would be bound to a globally visible name that should be accessible by remote clients.
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 can be stored in and retrieved from JNDI, including the following:
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 deploymentdescriptor 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.
Environment Entries Environment entries are the simplest form of information stored in a component ENC, and they are similar to operating system environment variables, like those found on Unix or Windows. An environment entry is a name-to-value binding that allows a component to externalize a value and refer to the value by using a name.
You declare an environment entry by 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 that gives the name of the entry relative to java:comp/env
-
An env-entry-type element that gives the Java type of the entry value, which must be one of the following:
-
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 that gives the value of the entry as a string
Listing 3.3 shows an example of an env-entry fragment from an ejb-jar.xml deployment descriptor. There is no JBoss-specific deployment descriptor element because an env-entry is a complete name and value specification. Listing 3.4 shows a sample code fragment for accessing the maxExemptions and taxRate env-entry values declared in the deployment descriptor.
Listing 3.3 An Example of an ejb-jar.xml env-entry Fragment
<!-- ... -->
<session>
<ejb-name>ASessionBean</ejb-name>
<!-- ... -->
<env-entry>
<description>The maximum number of tax exemptions allowed </description>
<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>
<env-entry>
<description>The tax rate </description>
<env-entry-name>taxRate</env-entry-name>
<env-entry-type>java.lang.Float</env-entry-type>
<env-entry-value>0.23</env-entry-value>
</env-entry>
</session>
<!-- ... -->
Listing 3.4 An ENC env-entry Access Code Fragment
InitialContext iniCtx = new InitialContext();
Context envCtx = (Context) iniCtx.lookup("java:comp/env");
Integer maxExemptions = (Integer) envCtx.lookup("maxExemptions");
Float taxRate = (Float) envCtx.lookup("taxRate");
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, a component developer needs to have a way 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, you use the form ejb/link-name 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 classname of the EJB home interface.
A remote element that gives the fully qualified classname of the EJB remote interface.
An optional ejb-link element that links the reference to another Enterprise Bean in the same EJB JAR 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 a pathname that specifies the location of the ejb-jar file that contains the referenced component. The pathname is relative to the referencing ejb-jar file. The application assembler appends the ejb-name of the referenced bean to the pathname, 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 naming conflict. Listing 3.5 provides an ejb-jar.xml fragment that illustrates the use of the ejb-ref element. Listing 3.6 provides a code sample that illustrates accessing the ShoppingCartHome reference declared in Listing 3.5.
Listing 3.5 An Example of an ejb-jar.xml ejb-ref Descriptor Fragment
<description>This is a reference to the store products entity </description>
<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>
</session>
<session>
<ejb-ref>
<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>
</ejb-ref>
</session>
<entity>
<description>The Product entity bean </description>
<ejb-name>ProductBean</ejb-name>
<!--...-->
</entity>
<!--...-->
Listing 3.6 An ENC ejb-ref Access Code Fragment
InitialContext iniCtx = new InitialContext();
Context ejbCtx = (Context) iniCtx.lookup("java:comp/env/ejb");
ShoppingCartHome home = (ShoppingCartHome) ejbCtx.lookup("ShoppingCartHome");
EJB References with jboss.xml and jboss-web.xml The JBoss-specific 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 ShoppingCart-Bean 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 involves 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 an ejb-ref needs to access an external EJB, you can specify the JNDI name of the deployed EJB home by 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 includes the following:
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
Listing 3.7 provides an example jboss.xml descriptor fragment that illustrates the following usage points:
The ProductBeanUser ejb-ref link destination is set to the deployment name jboss/store/ProductHome
The deployment JNDI name of the ProductBean is set to jboss/store/ProductHome
Listing 3.7 An Example of a jboss.xml ejb-ref Fragment
<!-- ... -->
<session>
<ejb-name>ProductBeanUser</ejb-name>
<ejb-ref>
<ejb-ref-name>ejb/ProductHome</ejb-ref-name>
<jndi-name>jboss/store/ProductHome</jndi-name>
</ejb-ref>
</session>
<entity>
<ejb-name>ProductBean</ejb-name>
<jndi-name>jboss/store/ProductHome</jndi-name>
<!-- ... -->
</entity>
<!-- ... -->
EJB Local References EJB 2.0 added 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.
You declare an EJB local reference by 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, you 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 classname of the EJB local home interface.
A local element that gives the fully qualified classname 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 pathname that specifies the location of the ejb-jar file that contains the referenced component. The pathname is relative to the referencing ejb-jar file. The application assembler appends the ejb-name of the referenced bean to the pathname, 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 naming conflict. Listing 3.8 provides an ejb-jar.xml fragment that illustrates the use of the ejb-local-ref element. Listing 3.9 provides a code sample that illustrates accessing the ProbeLocalHome reference declared in Listing 3.8.
Listing 3.8 An Example of an ejb-jar.xml ejb-local-ref Descriptor Fragment
<!-- ... -->
<session>
<ejb-name>Probe</ejb-name>
<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>
</session>
<session>
<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>
<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-link>Probe</ejb-link>
</ejb-ref>
<ejb-local-ref>
<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>
<local>org.jboss.test.perf.interfaces.ProbeLocal</local>
<ejb-link>Probe</ejb-link>
</ejb-local-ref>
</session>
<!-- ... -->
Listing 3.9 An ENC ejb-local-ref Access Code Fragment
InitialContext iniCtx = new InitialContext();
Context ejbCtx = (Context) iniCtx.lookup("java:comp/env/ejb");
ProbeLocalHome home = (ProbeLocalHome) ejbCtx.lookup("ProbeLocalHome");
Resource Manager Connection Factory References Application component code can refer to resource factories by 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 shortly.)
A res-type element that specifies the fully qualified classname of the resource manager connection factory.
A res-auth element that indicates whether the application component code performs resource sign-on programmatically or whether the container signs on to the resource based on the principal mapping information supplied by the deployer. It must be either Application or Container.
An optional 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 mapping 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.
Listing 3.10 shows an example of a web.xml descriptor fragment that illustrates the resource-ref element usage. Listing 3.11 provides a code fragment that an application component would use to access the DefaultMail resource declared by the resource-ref.
Listing 3.10 A web.xml resource-ref Descriptor Fragment
<web>
<!-- ... -->
<servlet>
<servlet-name>AServlet</servlet-name>
<!-- ... -->
</servlet>
<!-- ... -->
<!-- JDBC DataSources (java:comp/env/jdbc) -->
<resource-ref>
<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>
</resource-ref>
<!-- JavaMail Connection Factories (java:comp/env/mail) -->
<resource-ref>
<description>Default Mail</description>
<res-ref-name>mail/DefaultMail</res-ref-name>
<res-type>javax.mail.Session</res-type>
<res-auth>Container</res-auth>
</resource-ref>
<!-- JMS Connection Factories (java:comp/env/jms) -->
<resource-ref>
<description>Default QueueFactory</description>
<res-ref-name>jms/QueueFactory</res-ref-name>
<res-type>javax.jms.QueueConnectionFactory</res-type>
<res-auth>Container</res-auth>
</resource-ref>
</web>
Listing 3.11 An ENC resource-ref Access Sample Code Fragment
Context initCtx = new InitialContext();
javax.mail.Session s = (javax.mail.Session)
initCtx.lookup("java:comp/env/mail/DefaultMail");
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 classname 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
Listing 3.12 provides a sample jboss-web.xml descriptor fragment that shows sample mappings of the resource-ref elements given in Listing 3.10.
Listing 3.12 A Sample jboss-web.xml resource-ref Descriptor Fragment
<jboss-web>
<!-- ... -->
<resource-ref>
<res-ref-name>jdbc/DefaultDS</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<jndi-name>java:/DefaultDS</jndi-name>
</resource-ref>
<resource-ref>
<res-ref-name>mail/DefaultMail</res-ref-name>
<res-type>javax.mail.Session</res-type>
<jndi-name>java:/Mail</jndi-name>
</resource-ref>
<resource-ref>
<res-ref-name>jms/QueueFactory</res-ref-name>
<res-type>javax.jms.QueueConnectionFactory</res-type>
<jndi-name>QueueConnectionFactory</jndi-name>
</resource-ref>
<!-- ... -->
</jboss-web>
Resource Environment References A resource environment reference is an element that refers to an administered object that is associated with a resource (for example, JMS destinations), using a logical name. 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 object’s location in the target operational environment by 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 classname of the referenced object. For example, in the case of a JMS queue, the value would be javax.jms.Queue.
Listing 3.13 provides an example resource-ref-env element declaration by a session bean. Listing 3.14 provides a code fragment that illustrates how to look up the StockInfo queue declared by the resource-env-ref.
Listing 3.13 An Example of an ejb -jar.xml resource-env-ref Fragment
<session>
<ejb-name>MyBean</ejb-name>
<resource-env-ref>
<description>This is a reference to a JMS queue used in the
processing of Stock info
</description>
<resource-env-ref-name>jms/StockInfo</resource-env-ref-name>
<resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
</resource-env-ref>
<!-- ... -->
</session>
Listing 3.14 An ENC resource-env-ref Access Code Fragment
InitialContext iniCtx = new InitialContext();
javax.jms.Queue q = (javax.jms.Queue)
envCtx.lookup("java:comp/env/jms/StockInfo");
Resource Environment 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 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
Listing 3.15 provides a sample jboss.xml descriptor fragment that shows a sample mapping for the StockInfo resource-env-ref.
Listing 3.15 A Sample jboss.xml resource-env-ref Descriptor Fragment
<session>
<ejb-name>MyBean</ejb-name>
<resource-env-ref>
<resource-env-ref-name>jms/StockInfo</resource-env-ref-name>
<jndi-name>queue/StockInfoQueue</jndi-name>
</resource-env-ref>
<!-- ... -->
</session>