Application local JNDI context
A Java EE application's local JNDI context is immutable and is only accessible by that Java EE application. The context is bound at java:comp/env for each application. It contains references to the resources and Java EE components that the application references.
Because this is an immutable context, we cannot bind anything into it programmatically by using the javax.naming.Context.bind method. However, we can specify all of the resources and components that we require to be bound in the context, in the Java EE deployment descriptor and the Apache Geronimo-specific deployment plan. The name specified in the ref-name element is the name under which the resource will be available in the application local JNDI context.
For example, if you specify a ref-name of jdbc/DataSource for a DataSource object as given in the XML fragment shown below:
<resource-ref> <res-ref-name>jdbc/DataSource</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> <res-sharing-scope>Shareable</res-sharing-scope> </resource-ref>
then it will be available at java:comp/env/jdbc/DataSource in the application local JNDI context. The Apache Geronimo-specific deployment plan will have a corresponding resource-ref tag that will map the resource-ref specified in the Java EE deployment descriptor to the actual resource deployed in the server. The following is an XML fragment from the deployment plan that maps the resource in this example:
<naming:resource-ref> <naming:ref-name>jdbc/DataSource</naming:ref-name> <naming:resource-link>DerbyTestPool</naming:resource-link> </naming:resource-ref>
Geronimo also provides a gbean-ref tag in the Apache Geronimo-specific deployment descriptor that can be used to bind GBeans to the application-specific JNDI Context. In the case of certain Java EE components, such as enterprise beans, each component has its own local JNDI context or component context. The component context can contain the same type of elements as the application context, and is also immutable. The way to configure this context is also the same, that is, through the deployment descriptors. We will look into how the different types of components and resources can be bound into the component context in the next section. The different types of references that can be specified in the deployment descriptors and deployment plans are as follows:
resource-ref
The resource-ref element is used to map resources (DataSources and ConnectionFactories) to the application or component's JNDI context as follows:
<resource-ref> <res-ref-name>jdbc/DataSource</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> <res-sharing-scope>Shareable</res-sharing-scope> </resource-ref>
The above listing shows the entry that we need to make in the Java EE deployment descriptor (for example, web.xml, ejb-jar.xml, and application-client.xml), while the next one shows the corresponding entry that is required in the Apache Geronimo —specific deployment plans (geronimo-web.xml, openejb-jar.xml, geronimo-application-client.xml, and geronimo-application.xml) for the previous entry to be mapped to a resource (a javax.sql.DataSource object, in this case) on the server with the name DerbyTestPool.
<naming:resource-ref> <naming:ref-name>jdbc/DataSource</naming:ref-name> <naming:resource-link>DerbyTestPool</naming:resource-link> </naming:resource-ref>
The namespace prefix naming maps to the namespace http://geronimo.apache.org/xml/ns/naming-1.2. This DataSource will be available in the application local or component local JNDI context of the application or component for which these resource-ref elements were specified under the JNDI name java:comp/env/jdbc/DataSource. You can look this resource up in your Java EE component in the traditional way or use the new dependency injection functionality in Java EE 5. Both of these methods are illustrated as follows:
// Traditional Approach
Context ctx = new InitialContext();
DataSource ds = ctx.lookup("java:comp/env/jdbc/DataSource");
// Dependency Injection
@Resource(name="jdbc/DataSource")
DataSource ds;
The other resources mentioned later in this chapter can also be accessed by using the same approach.
resource-env-ref
The resource-env-ref element is used to map administered objects (such as JMS queues and topics) to names in the JNDI context of the application or component. The next two listings show the entries that are required to be made in both the Java EE deployment descriptors (ejb-jar.xml, web.xml and application-client.xml) and the server-specific deployment plans (geronimo-web.xml,openejb-jar.xml , geronimo-application-client.xml, and geronimo-application.xml), so that references to administrative objects that are defined in resource adapter plans can be mapped to JNDI names in the application or component local contexts, as shown below:
<resource-env-ref> <description>Predefined Topic</description> <resource-env-ref-name> jms/Topic </resource-env-ref-name> <resource-env-ref-type> javax.jms.Topic</resource-env-ref-type> </resource-env-ref>
The above listing describes that an administered object of type javax.jms.Topic is required to be present in the application context or component context of the application to which this Java EE deployment descriptor entry belongs. The listing that maps the JNDI name to the actual object that is deployed in the Geronimo server is shown below:
<naming:resource-env-ref> <naming:ref-name>jms/Topic</naming:ref-name> <naming:message-destination-link> TextMessageTopic </naming:message-destination-link> </naming:resource-env-ref>
The namespace prefix naming maps to the namespace http://geronimo.apache.org/xml/ns/naming-1.2.
ejb-ref
The ejb-ref element is used to map the Enterprise Java Beans (EJB) to JNDI names in the component or application context. You can map both EJBs deployed on the same server as well as those deployed on remote servers, as shown below:
<ejb-ref> <ejb-ref-name>ejb/Suppliers</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <remote>com.packt.sample.Suppliers </remote> <ejb-link>SuppliersBean</ejb-link> </ejb-ref>
This illustration shows one way in which we can specify an EJB reference in the Java EE deployment descriptors (ejb-jar.xml and web.xml). Note that the ejb-link element is specified here, and Apache Geronimo will use it to resolve the EJB that this refers to, provided it is in the same application or a parent application. If we do not specify the ejb-link in the Java EE deployment descriptor, we will need to provide a mapping for it in the server-specific deployment plans (openejb-jar.xml, geronimo-web.xml, geronimo-application.xml, and geronimo-application-client.xml), as shown below:
<naming:ejb-ref> <naming:ref-name>ejb/Suppliers</naming:ref-name> <naming:ejb-link>SuppliersBean</naming:ejb-link> </naming:ejb-ref>
or
<naming:ejb-ref> <naming:ref-name>ejb/Suppliers</naming:ref-name> <naming:pattern> <naming:name>SuppliersBean</naming:name> </naming:pattern> </naming:ejb-ref>
There are other ways of referring to EJBs that are remote, by using the ns-corbaloc, name, and css or css-link elements in the server-specific deployment plan, which was illustrated in Chapter 7, CORBA.
ejb-local-ref
The ejb-local-ref element is used to map the Enterprise Java Beans (EJB) to JNDI names in the component or application context. You can map EJBs deployed on the same server only. The mapping is similar to the case for the ejb-ref element except that you specify a local EJB interface instead of a remote EJB interface, as shown below:
<ejb-local-ref> <ejb-ref-name>ejb/Suppliers</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local>com.packt.samples.Suppliers</local> <ejb-link>SuppliersBean</ejb-link> </ejb-local-ref>
This illustration shows the entries that are required in the Java EE deployment descriptors, and the next illustrations show the corresponding entries in the server-specific deployment plans:
<ejb-local-ref> <ref-name>ejb/Suppliers</ref-name> <ejb-link>SuppliersBean</ejb-link> </ejb-local-ref>
or
<ejb-local-ref> <ref-name>ejb/Suppliers</ref-name> <pattern> <name>SuppliersBean</name> </pattern> </ejb-local-ref>
service-ref
The service-ref element is used for mapping web service invocation proxies to the JNDI context of an application or component. The following is an example of a service-ref element:
<service-ref> <service-ref-name>service/SendMail</service-ref-name> <service-interface> javax.xml.ws.Service </service-interface> <wsdl-file>META-INF/wsdl/MailService.wsdl</wsdl-file> <service-qname xmlns:axis2="http://ejb.library.packt.com"> axis2:MailService </service-qname> <port-component-ref> <service-endpoint-interface> com.packtpub.library.ejb.MailBusinessRemote </service-endpoint-interface> </port-component-ref> </service-ref>
The illustration above shows the entries in the Java EE deployment descriptor for binding a web service client proxy in the JNDI context of an application or a Java EE component, while the next one shows the overrides that are possible in the server-specific deployment plan:
<service-ref> <service-ref-name>service/SendMail</service-ref-name> <port> <port-name>MailServiceSOAP11port</port-name> <protocol>http</protocol> <host>localhost</host> <port>8080</port> <uri>/Mail/MailService</uri> </port> </service-ref>
message-destination-ref
The message-destination-ref element is used for binding message destination references to the application or components JNDI context by using logical names. The next illustration shows how this can be done in the Java EE deployment descriptor. It provides all of the details required by Apache Geronimo in order to locate and bind a reference to the JMS queue to the JNDI location java:comp/env/jms/TestQueue, as follows:
<message-destination-ref> <description></description> <message-destination-ref-name>jms/TestQueue </message-destination-ref-name> <message-destination-type>javax.jms.Queue</message-destination-type> <message-destination-usage>Produces</message-destination-usage> message-destination-link>TestQueue</message-destination-link> </message-destination-ref>
If we do not specify the message-destination-link in this entry in the Java EE deployment descriptor, then we need to specify either of the next two entries in the application server-specific deployment plans:
<message-destination> <message-destination-name>jms/TestQueue </message-destination-name> <pattern> <name>TestQueue</name> </pattern> </message-destination>
or
<message-destination> <message-destination-name>jms/TestQueue </message-destination-name> <admin-object-module>TestRAR </admin-object-module> <admin-object-link>TestQueue </admin-object-link> </message-destination>
persistence-context-ref
The persistence-context-ref element is used to bind a JPA EntityManager to the JNDI naming context of an application or a component. This can be specified in the Java EE deployment descriptor in two ways, as shown below:
<persistence-context-ref> <persistence-context-ref-name>persistence/PContext </persistence-context-ref-name> </persistence-context-ref>
In this case, we only specify the name that the reference will have in the naming context of the application or component. This would need a corresponding mapping entry in the server-specific deployment plan in order to map the name to the actual resource, as shown below:
<persistence-context-ref> <persistence-context-ref-name>persistence/PContext </persistence-context-ref-name> <persistence-unit-name>PersistenceUnit1 </persistence-unit-name>
or
<pattern><name>PersistenceUnit1</name></pattern> <persistence-context-type>EXTENDED </persistence-context-type> <property><JPA provider specific properties></property> </persistence-context-ref>
Either the persistence-unit-name element or the pattern element must be present for the server to map the persistence context to the JNDI location. We can also specify the mapping in the Java EE deployment descriptor, in which case we do not need to have a corresponding entry in the server-specific deployment plan. This is shown in the following listing:
<persistence-context-ref> <persistence-context-ref-name>persistence/PContext </persistence-context-ref-name> <persistence-unit-name>PersistenceUnit1 </persistence-unit-name> <persistence-context-type>Extended </persistence-context-type> </persistence-context-ref>
persistence-unit-ref
The persistence-unit-ref element is used to make a JPA EntityManagerFactory object available in the JNDI namespace of an application or a component. The following listings show two different ways in which we can specify the persistence-unit-ref element in the Java EE deployment descriptor:
<persistence-unit-ref> <persistence-unit-ref-name>persistence/PU </persistence-unit-ref-name> </persistence-unit-ref>
or
<persistence-unit-ref> <persistence-unit-ref-name>persistence/PU </persistence-unit-ref-name> <persistence-unit-name>PersistenceUnit1 </persistence-unit-name> </persistence-unit-ref>
The second way does not require further information to be provided in the server-specific deployment plan, while the first way requires additional information, which can be provided as shown below:
<persistence-unit-ref> <persistence-unit-ref-name>persistence/PU </persistence-unit-ref-name> <persistence-unit-name>PersistenceUnit1 </persistence-unit-name> <persistence-unit-ref>
or
<persistence-unit-ref> <persistence-unit-ref-name>persistence/PU </persistence-unit-ref-name> <pattern><name>PersistenceUnit1</name> </pattern> <persistence-unit-ref>
gbean-ref
The gbean-ref element is used to map GBeans that are deployed in Apache Geronimo and that are accessible to the application or component, into the JNDI namespace of that application or component. As this is an Apache Geronimo— specific feature, an entry only needs to be made in the Apache Geronimo—specific deployment plans for that module. An example of such an entry is shown below:
<gbean-ref> <ref-name>gbean/TestGBean</ref-name> <ref-type>com.packt.Test<ref-type> <pattern><name>TestGBean</name></pattern> </gbean-ref>
This entry will make the GBean available in the JNDI context of the application at java:comp/env/gbean/TestGbean. The object obtained will be of type com.packt.Test, which is the interface that the GBean extends, and it exposes the methods that the application or component wants to invoke on the GBean.