| Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g Release 3 (10.1.3) B14428-02 |
|
 Previous |
 Next |
| Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g Release 3 (10.1.3) B14428-02 |
|
Previous |
Next |
This chapter describes:
For more information, see:
"Oracle JNDI" in the Oracle Containers for J2EE Services Guide
Before you can access essential resources from your EJB at runtime using JNDI, you must define environment references to them. Environment references are static and cannot be changed by the bean.
This section describes configuring:
In EJB 3.0, you can use annotations, resource injection, and default JNDI names (based on class and interface names) instead of defining environment references.
In EJB 2.1, you must define <ejb-ref> or <ejb-local-ref> elements in the appropriate deployment descriptor (see "Where Do You Configure an EJB Environment Reference?").
When you define an environment reference, you can use the actual JNDI name or use a logical name ("Should You Use Logical Names?") associated with it to increase deployment flexibility.
Before one EJB, acting in the role of a client can access another EJB, you must define an EJB reference to the target EJB.
For more information, see "Configuring an Environment Reference to an EJB".
You can define an environment reference to resource manager connection factories that provide connections to such services as a JDBC data source, JMS topic or queue, Java mail, or an HTTP URL. These references are logical names that OC4J binds at deployment time to the actual resource manager connection factories that it provides.
|
Note: In EJB 3.0, an environment reference to a resource manager connection factory is not needed. You can access a resource manager connection factory directly using annotations and resource injection (see "Looking Up an EJB 3.0 Resource Manager Connection Factory"). |
For each client in which you want to access a resource manager connection factory, you must either inject it in the client source code or define an environment reference to it in the client's deployment descriptor.
For more information, see:
You can define an enviornment variable with an enviornment reference to make the environment variable value accessible using JNDI.
For more information, see "Configuring an Environment Reference to an Environment Variable"
You can define a Web service with an enviornment reference to make the Web service accessible using JNDI
For more information, see "Configuring an Environment Reference to a Web Service".
The preferred way to access an entity manager is using annotations and dependency injection (see "Acquiring the OC4J Default Entity Manager in an EJB 3.0 Stateful Session Bean Client" and "Acquiring an Entity Manager in Other EJB 3.0 Bean Clients").
To acquire an entity manager in a class that does not support annotations and injection, namely helper classes and Web clients, you must first define a persistence context reference and then lookup the entity manager using JNDI.
For more information, see:
If you choose to use environment references, where you configure the EJB reference depends on the type of client as Table 19-1 shows.
Table 19-1 Deployment Descriptor by Client Type
| Client Type | Description | Deployment Descriptor | OC4J-Specific Deployment Descriptor |
|---|---|---|---|
|
EJB |
Another EJB invoking an EJB from within the container. |
|
|
|
Standalone client |
A pure-Java client invoking an EJB from outside of the container. |
|
|
|
Servlet or JSP |
A servlet or JSP invoking an EJB from outside of the container. |
|
|
When you define an environment reference, you can identify the resource by a logical name or by its JNDI name.
To maximize application assembly and deployment flexibility, you typically develop an EJB application by referring to resources by a logical name that you define in your application environment. This indirection enables the bean developer to refer to EJBs, other resources (such as a JDBC DataSource), and environment variables without specifying the actual name, which may change depending on how an application is assembled and deployed.
The procedures in this chapter explain how to configure either logical or JNDI names.
Before one EJB, acting in the role of a client (call it the source EJB), can access another EJB (call it the target EJB), you must define an EJB reference to the target EJB in the deployment descriptor of the source EJB.
|
Note: In EJB 3.0, an environment reference to a target EJB is not needed. You can access a target EJB directly using annotations and resource injection (see "Accessing an EJB 3.0 EJB"). |
This section describes:
To define an EJB reference to the remote interface of a target EJB, you configure an <ejb-ref> element in the appropriate deployment descriptor.
|
Note: In EJB 3.0, an environment reference to a target EJB is not needed. You can access a target EJB directly using annotations and resource injection (see "Accessing an EJB 3.0 EJB"). |
For information on looking up a target EJB, see "Accessing an EJB from a Client".
To define a reference to the remote interface of an EJB 2.1 EJB:
Define an <ejb-ref> element in the appropriate client deployment descriptor (see "Where Do You Configure an EJB Environment Reference?").
Within the <ejb-ref> element, define the <home> and <remote> sub-elements with the package and class name of the target EJB remote home and remote component interface, respectively.
Within the <ejb-ref> element, define the <ejb-ref-type> to the target bean's type: Session or Entity.
Within the <ejb-ref> element, define the <ejb-ref-name> and, optionally, the <ejb-link> sub-elements.
|
Note: If the bean interfaces are unique (for example, only one session bean uses the interfaceCart.class) then the <ejb-link> is not required. |
You can choose one of the following options:
Configure <ejb-ref-name> with a logical name and configure <ejb-link> with the actual name of the target bean as Example 19-1 shows.
This option provides indirection that offers assembly and deployment flexibility.
Configure <ejb-ref-name> with a logical name as Example 19-2 shows and, in the orion-ejb-jar.xml deployment descriptor, define an <ejb-ref-mapping> element that maps the logical name to the actual name of the target bean as Example 19-3 shows.
This option provides indirection that offers the most assembly and deployment flexibility.
Example 19-2 Configuring ejb-ref-name with a Logical Name Resolved by ejb-ref-mapping
<ejb-ref> <ejb-ref-name>ejb/nextVal</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>myBeans.BeanAHome</home> <remote>myBeans.BeanA</remote> </ejb-ref>
As Figure 19-1 shows, in the <ejb-ref-mapping> element, configure the name attribute to match the <ejb-ref-name> and configure the location attribute with the actual name of the target bean. In Example 19-3, the logical name ejb/nextVal is mapped to the actual name of the target bean myBeans/BeanA.
Example 19-3 Mapping Logical Name to Actual Name with ejb-ref-mapping
<ejb-ref-mapping name="ejb/nextVal" location="myBeans/BeanA"/>
OC4J maps the logical name to the actual JNDI name on the client-side. The server-side receives the JNDI name and resolves it within its JNDI tree.
Before you can look up a target EJB from your client, you must define an EJB reference to the target EJB. To define an EJB reference to the local interface of a target EJB, you configure an <ejb-local-ref> element in the ejb-jar.xml deployment descriptor.
|
Note: In EJB 3.0, an environment reference to a target EJB is not needed. You can access a target EJB directly using annotations and resource injection (see "Accessing an EJB 3.0 EJB"). |
For information on looking up a target EJB, see "Accessing an EJB from a Client".
To define a reference to the local interface of an EJB:
Define an <ejb-local-ref> element in the appropriate client deployment descriptor (see "Where Do You Configure an EJB Environment Reference?").
Within the <ejb-local-ref> element, define the <local-home> and <local> sub-elements with the package and class name of the target EJB remote home and remote component interface, respectively.
Within the <ejb-local-ref> element, define the <ejb-ref-type> to the target bean's type: Session or Entity.
Within the <ejb-local-ref> element, define the <ejb-ref-name> and, optionally, the <ejb-link> sub-elements.
|
Note: If the bean interfaces are unique (for example, only one session bean uses the interfaceCart.class) then the <ejb-link> is not required. |
You can choose one of the following options:
Configure <ejb-ref-name> with a logical name and configure <ejb-link> with the actual name of the target bean as Example 19-1 shows.
This option provides indirection that offers assembly and deployment flexibility.
Configure <ejb-ref-name> with a logical name as Example 19-2 shows and, in the orion-ejb-jar.xml deployment descriptor, define an <ejb-ref-mapping> element that maps the logical name to the actual name of the target bean as Example 19-3 shows.
This option provides indirection that offers the most assembly and deployment flexibility.
Example 19-5 Configuring ejb-ref-name with a Logical Name Resolved by ejb-ref-mapping
<ejb-local-ref> <ejb-ref-name>ejb/nextVal</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home>myBeans.BeanAHome</local-home> <local>myBeans.BeanA</local> </ejb-local-ref>
In the <ejb-ref-mapping> element, configure the name attribute to match the <ejb-ref-name> and configure the location attribute with the actual name of the target bean. In Example 19-3, the logical name ejb/nextVal is mapped to the actual name of the target bean myBeans/BeanA.
Example 19-6 Mapping Logical Name to Actual Name with ejb-ref-mapping
<ejb-ref-mapping name="ejb/nextVal" location="myBeans/BeanA"/>
OC4J maps the logical name to the actual JNDI name on the client-side. The server-side receives the JNDI name and resolves it within its JNDI tree.
You can access a database through JDBC by creating an environment element for a JDBC DataSource.
|
Note: In EJB 3.0, an environment reference to a resource manager connection factory is not needed. You can access a resource manager connection factory directly using annotations and resource injection (see "Looking Up an EJB 3.0 Resource Manager Connection Factory"). |
For information on looking up a resource manager connection factory, see:
To define a reference to a JDBC DataSource:
Define a <resource-ref> element in the appropriate client deployment descriptor (see "Where Do You Configure an EJB Environment Reference?") and configure its <res-ref-name> element with a logical name for the JDBC data source resource manager connection factory.
It is a best practice to prefix the reference name with "jdbc" but it is not required. If you use the initial context to look up this reference in your bean source code (see Example 19-44), always prefix the logical name with "java:comp/env/".
Figure 19-0 shows a <resource-ref> element in the ejb-jar.xml deployment descriptor with a logical name of jdbc/OrderDB, of type javax.sql.DataSource, and the authenticator of Application.
In the data-sources.xml file, define the desired DataSource and specify its actual JNDI name (see "Configuring Data Sources").
In this example, assume a DataSource is specified in the data-sources.xml file with the JNDI name of /test/OrderDataSource.
In the orion-ejb-jar.xml deployment descriptor, define a <resource-ref-mapping> element to map the logical name (defined in ejb-jar.xml) to the JNDI name (defined in data-sources.xml).
Figure 19-2 shows a <resource-ref-mapping> element with the name attribute set to jdbc/OrderDB (the logical name defined in ejb-jar.xml) and the location attribute set to test/OrderDataSource (the JNDI name defined in data-sources.xml).
Within the bean's implementation, you can look up the JDBC data source resource manager connection factory for this data source using the logical name java:comp/env/jdbc/OrderDB (see Example 19-44).
Using JMS 1.1, you define an environment reference to a JMS connection resource manager connection factory the same as you do in JMS 1.0 (see "Configuring an Environment Reference to a JMS Destination or Connection Resource Manager Connection Factory (JMS 1.0)"). However, you can define an environment reference to a JMS destination using a <message-destination-ref> element in the client deployment descriptor and a <message-destination-ref-mapping> element in the corresponding OC4J-specific deployment descriptor (see "Where Do You Configure an EJB Environment Reference?").
You use the <message-destination-ref-mapping> to map the client <message-destination-ref-name> to another location that is available in the OC4J environment. This provides the means of linking message consumers and producers to one or more common logical destinations.
You can use <message-destination-ref> in all EJB types, therefore <message-destination-ref-mapping> is not restricted to message-driven-deployment.
For more information, see "Oracle Enterprise Messaging Service (OEMS)" in the Oracle Containers for J2EE Services Guide.
|
Note: In EJB 3.0, an environment reference to a resource manager connection factory is not needed. You can access a resource manager connection factory directly using annotations and resource injection (see "Looking Up an EJB 3.0 Resource Manager Connection Factory"). |
For information on looking up a resource manager connection factory, see:
You can access a JMS destination (queue or topic) and JMS connection resource manager connection factory by creating an environment reference to them.
|
Note: In EJB 3.0, an environment reference to a resource manager connection factory is not needed. You can access a resource manager connection factory directly using annotations and resource injection (see "Looking Up an EJB 3.0 Resource Manager Connection Factory"). |
For information on looking up a resource manager connection factory, see:
To define a reference to a JMS destination and JMS connection resource manager connection factory:
Configure your JMS service provider.
For more information, see:
Define the JNDI name for the JMS destination and connection factory.
For more information, see:
Define a logical name for the JMS destination and JMS connection factory.
How you define the logical names is the same regardless of what type of JMS provider you use.
Define a <resource-env-ref> element in the appropriate client deployment descriptor (see "Where Do You Configure an EJB Environment Reference?") and configure the following sub-elements:
<resource-env-ref-name>: a logical name for the JMS destination resource manager connection factory.
<resource-env-ref-type>: The destination class type; either javax.jms.Queue or javax.jms.Topic.
Example 19-7 shows a <resource-env-ref> element for a JMS topic resource manager connection factory.
Define a <resource-ref> element in the same client deployment descriptor and configure the following sub-elements:
<res-ref-name>: a logical name for the JMS connection resource manager connection factory.
<res-type>: the connection factory class type; either javax.jms.QueueConnectionFactory or javax.jms.TopicConnectionFactory.
<res-auth>: the authentication responsibility; either Container or Bean.
<res-sharing-scope>: the sharing scope; either Shareable or Unshareable.
Example 19-8 shows a <resource-ref> element for a JMS topic connection resource manager connection factory.
Map the logical names to the actual JNDI names.
Define a <resource-env-ref-mapping> element in the corresponding OC4J-specific deployment descriptor (see "Where Do You Configure an EJB Environment Reference?") and configure its name attribute to the JMS destination logical name (defined in the <resource-env-ref>) and its location attribute to the JNDI name defined when you configured your JMS provider (see step 2).
Example 19-9 shows a <resource-env-ref-mapping> element for OracleAS JMS.
Define a <resource-ref-mapping> element in the same OC4J-specific deployment descriptor (see "Where Do You Configure an EJB Environment Reference?") and configure its name attribute to the JMS connection factory logical name (defined in the <resource-ref>) and its location attribute to the JNDI name defined when you configured your JMS provider (see step 2).
Example 19-10 shows a <resource-ref-mapping> element for OracleAS JMS.
You can access a Java mail session by creating a resource manager connection factory reference to it.
|
Note: In EJB 3.0, an environment reference to a resource manager connection factory is not needed. You can access a resource manager connection factory directly using annotations and resource injection (see "Looking Up an EJB 3.0 Resource Manager Connection Factory"). |
For information on looking up a resource manager connection factory, see:
To define a reference to a Java mail resource manager connection factory:
Bind the javax.mail.Session reference within the JNDI name space in the application.xml file using the <mail-session> element, as follows:
<mail-session location="mail/MailSession" smtp-host="mysmtp.oraclecorp.com"> <property name="mail.transport.protocol" value="smtp"/> <property name="mail.smtp.from" value="emailaddress@oracle.com"/> </mail-session>
The location attribute contains the JNDI name specified in the location attribute of the <resource-ref-mapping> element in the OC4J-specific deployment descriptor.
Create a logical name within the <res-ref-name> element in the EJB deployment descriptor.
It is a best practice to start the reference name with "mail" but it is not required. In the bean code, the lookup of this reference is always prefaced by "java:comp/env" (for example, "java:comp/env/mail/myMail")
Map the logical name within the EJB deployment descriptor to the JNDI name, created in step 1, within the OC4J-specific deployment descriptor.
Lookup the object reference within the bean with the "java:comp/env/mail" preface and the logical name defined in the EJB deployment descriptor.
As shown in Figure 19-3, the Session object was bound to the JNDI name "/test/myMailSession". The logical name that the bean knows this resource as is "mail/testMailSession". These names are mapped together within the OC4J-specific deployment descriptor. Thus, within the bean's implementation, the bean can retrieve the connection to the bound Session object by using the "java:comp/env/mail/testMailSession" environment element.
This environment element is defined with the following information:
Example 19-11 Defining an environment element for Java mail Session
The environment element is defined within the EJB deployment descriptor by providing the logical name, "mail/testMailSession", its type of javax.mail.Session, and the authenticator of "Application".
The environment element of "mail/testMailSession" is mapped to the JNDI bound name for the connection, "test/myMailSession" within the OC4J-specific deployment descriptor.
Once deployed, the bean can retrieve the Session object reference:
InitialContext ic = new InitialContext();
Session session = (Session) ic.lookup("java:comp/env/mail/testMailSession");
//The following uses the mail session object
//Create a message object
MimeMessage msg = new MimeMessage(session);
//Construct an address array
String mailTo = "whosit@oracle.com";
InternetAddress addr = new InternetAddress(mailto);
InternetAddress addrs[] = new InternetAddress[1];
addrs[0] = addr;
//set the message parameters
msg.setRecipients(Message.RecipientType.TO, addrs);
msg.setSubject("testSend()" + new Date());
msg.setContent(msgText, "text/plain");
//send the mail message
Transport.send(msg);
You can access a URL connection by creating a resource manager connection factory reference to it.
|
Note: In EJB 3.0, an environment reference to a resource manager connection factory is not needed. You can access a resource manager connection factory directly using annotations and resource injection (see "Looking Up an EJB 3.0 Resource Manager Connection Factory"). |
For information on looking up a resource manager connection factory, see:
To define a reference to a URL resource manager connection factory:
Create a logical name within the <res-ref-name> element in the EJB deployment descriptor.
It is a best practice to start the reference name with "url" but it is not required. In the bean code, the lookup of this reference is always prefaced by "java:comp/env" (for example, "java:comp/env/url/myURL")
Map the logical name within the EJB deployment descriptor to the URL within the OC4J-specific deployment descriptor.
Lookup the object reference within the bean with the "java:comp/env/url" preface and the logical name defined in the EJB deployment descriptor.
As shown in Figure 19-4, the URL object was bound to the URL "http://www.myURL.com". The logical name that the bean knows this resource as is "url/testURL". These names are mapped together within the OC4J-specific deployment descriptor. Thus, within the bean's implementation, the bean can retrieve a reference to the URL object by using the "java:comp/env/url/testURL" environment element.
This environment element is defined with the following information:
Example 19-12 Defining an Environment Element for a URL
The environment element is defined within the EJB deployment descriptor by providing the logical name, "url/testURL", its type of java.net.URL, and the authenticator of "Application".
The environment element of "url/testURL" is mapped to the URL "http://www.myURL.com" within the OC4J-specific deployment descriptor.
Once deployed, the bean can retrieve the URL object reference as follows:
InitialContext ic = new InitialContext();
URL url = (URL) ic.lookup("java:comp/env/url/testURL");
//The following uses the URL object
URLConection conn = url.openConnection();
You can create environment variables that your bean accesses through a JNDI lookup on the InitialContext. These variables are defined within an ejb-jar.xml file <env-entry> element and can be of the following types: String, Integer, Boolean, Double, Byte, Short, Long, and Float. The environment variable name is defined in the <env-entry-name> sub-element, the type is defined in the <env-entry-type> sub-element, and the value is defined in the <env-entry-value> sub-element. The <env-entry-name> is relative to the "java:comp/env" context.
Example 19-13 shows how to define environment variables for java:comp/env/minBalance and java:comp/env/maxCreditBalance in the ejb-jar.xml file.
Example 19-13 ejb-jar.xml For Environment Variables
<env-entry>
<env-entry-name>minBalance</env-entry-name>
<env-entry-type>java.lang.Integer</env-entry-type>
<env-entry-value>500</env-entry-value>
</env-entry>
<env-entry>
<env-entry-name>maxCreditBalance</env-entry-name>
<env-entry-type>java.lang.Integer</env-entry-type>
<env-entry-value>10000</env-entry-value>
</env-entry>
You can override an environment variable value defined in the ejb-jar.xml file by defining an env-entry-mapping element in your orion-ejb-jar.xml file whose name attribute matches the env-entry-name defined in the ejb-jar.xml file. The type specified in the ejb-jar.xml file stays the same.
Figure 19-5 shows how the minBalance environment variable value is overridden by the orion-ejb-jar.xml file and set to 500.
Figure 19-5 Overriding Environment Variables in ejb-jar.xml with orion-ejb-jar.xml
For more information on looking up environment variables, see:
You can access a Web service from a stateless session bean by creating a resource manager connection factory reference to the Web service.
|
Note: In EJB 3.0, an environment reference to a Web service is not needed. You can access a Web service directly using annotations and resource injection. |
For each client in which you want to access a resource manager connection factory, you must either inject it in the client source code or define an environment reference to it in the client's deployment descriptor.
To create an environment reference to a Web service:
Define a logical name for the Web service.
Define a <service-ref> element in the appropriate client deployment descriptor (see "Where Do You Configure an EJB Environment Reference?") and configure the following sub-elements:
<service-ref-name>: a logical name for the Web service.
<service-interface>: the Web service interface.
Example 19-14 shows a <service-ref> element for a Web service.
It is a best practice to start the reference name with "service" but it is not required. In the bean code, the lookup of this reference (see Example 30-5) is always prefaced by "java:comp/env" (for example, "java:comp/env/service/myService")
Map the logical name to the actual JNDI name.
Define a <service-ref-mapping> element in the corresponding OC4J-specific deployment descriptor (see "Where Do You Configure an EJB Environment Reference?") and configure its name attribute to the Web service logical name (defined in the <service-ref>) and the <service-qname> sub-element.
Example 19-9 shows a <service-ref-mapping> element for a Web service.
For information on looking up and using a Web service , see "Using EJBs and Web Services".
To acquire an entity manager in a class that does not support annotations and injection, namely helper classes and Web clients, you must first define a persistence-context-ref in the appropriate deployment descriptor file.
To create an environment reference to a persistence context:
Define a logical name for the persistence context.
Define a <persistence-context-ref> element in the appropriate client deployment descriptor (see "Where Do You Configure an EJB Environment Reference?") and configure the following sub-elements:
<persistence-context-ref-name>: a logical name for the persistence context.
<persistence-unit-name>: the name of the persistence unit associated with this persistence context.
You must define a persistence unit of this name in a persistence.xml file.
For more information, see:
Example 19-14 shows a <persistence-context-ref> element for a persistence context in a web.xml file.
It is a best practice to start the reference name with "persistence" but it is not required. In the bean code, the lookup of this reference (see Example 29-6) is always prefaced by "java:comp/env" (for example, "java:comp/env/persistence/InventoryAppMgr").
Example 19-16 web.xml For a Persistence Context
...
<servlet>
<servlet-name>webTierEntryPoint</servlet-name>
<servlet-class>com.sun.j2ee.blueprints.waf.controller.web.MainServlet</servlet-class>
<init-param>
<param-name>default_locale</param-name>
<param-value>en_US</param-value>
</init-param>
<persistence-context-ref>
<description>
Persistence context for the inventory management application.
</description>
<persistence-context-ref-name>
persistence/InventoryAppMgr
</persistence-context-ref-name>
<persistence-unit-name>
InventoryManagement <!-- Defined in persistenc.xml -->
</persistence-unit-name>
</persistence-context-ref>
</servlet>
...
For information on looking up and using an entity manager , see "Acquiring an Entity Manager in a Helper Class or Web Client".
You use an initial context factory to obtain an initial context: a reference to a JNDI namespace. Using the initial context, you can use the JNDI API to look up an EJB, resource manager connection factory, environment variable, or other JNDI-accessible object.
The type of initial context factory you use depends on the type of client you are using it in as Table 19-2 shows.
Table 19-2 Client Initial Context Requirements
| Client Type | Relationship to Target EJB | Initial Context Factory |
|---|---|---|
|
Any Client |
Client and target EJB are collocated |
Default (see "Configuring the Default Initial Context Factory") |
|
Any Client |
Client and target EJB are deployed in the same application |
Default (see "Configuring the Default Initial Context Factory") |
|
Any Client |
Target EJB deployed in an application that is designated as the client's parentFoot 1 |
Default (see "Configuring the Default Initial Context Factory") |
|
|
Client and target EJB are not collocated, not deployed in the same application, and target EJB application is not client's parentFootref 1. |
|
|
|
Client and target EJB are not collocated, not deployed in the same application, and target EJB application is not client's parentFootref 1. |
|
Footnote 1 See the Oracle Containers for J2EE Developer's Guide for more information on how to set the parent of an application.
|
Note: In this release, note the new package names for the RMI and application client initial context factories. |
For more information, see:
Oracle Containers for J2EE Security Guide
Oracle Containers for J2EE Services Guide.
A client that is collocated with the target bean (see Table 19-2) automatically accesses the JNDI properties for the node. Thus, accessing the EJB is simple: no JNDI properties are required.
If your client requires an Oracle initial context factory (see Table 19-2), you must set the following JNDI properties:
For more information about setting JNDI properties, see "Setting JNDI Properties in an EJB".
Define the java.naming.factory.initial property with the Oracle initial context factory appropriate for your client (see Table 19-2).
Define the java.naming.provider.url property with the naming provider URL appropriate for your OC4J installation:
Create a HashTable and populate it with the required properties using javax.naming.Context fields as keys and String objects as values as Example 19-18 shows.
When you instantiate the initial context, pass the HashTable into the initial context constructor as Example 19-19 shows.
Use the initial context to look up a JNDI-accessible resource:
In an Oracle Application Server install, OPMN manages one or more OC4J instances. In this case the value for java.naming.provider.url should be of the format:
opmn:ormi://<hostname>:<opmn-request-port>:<oc4j-instance-name>/<application-name>
The fields in this provider URL are defined as follows:
<hostname>: The name of the host on which the Oracle Application Server is running.
<opmn-request-port>: In this configuration, you have to use the OPMN request port instead of using the ORMI port. You can find the OPMN request port in the opmn.xml file, as follows:
<notification-server>
<port local="6003" remote="6200" request="6004"/>
...
</notification-server>
The default OPMN request port is 6003.
<oc4j-instance-name>: In this configuration, you may have more than one OC4J process that OPMN uses for load balancing/failover. You use the name of the instance to which you deployed your application.
The default instance name is home.
For example, if the hostname is dpanda-us, request port is 6004, and instances name is home1, then the provider URL would be:
opmn:ormi://dpanda-us:6003:home1/ejbsamples
In a standalone OC4J install, the value for java.naming.provider.url should be of the format:
ormi://<hostname>:<ormi-port>/<application-name>
The fields in this provider URL are defined as follows:
<hostname>: The name of the host on which OC4J is running
<ormi-port>: The ORMI port as configured in the rmi.xml file, as follows:
<rmi-server
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/rmi-server-10_0.xsd"
port="23791"
schema-major-version="10"
schema-minor-version="0"
>
...
</rmi-server>
The default port is 23791.
<application-name>: The application name as configured in the server.xml file.
For example, if the hostname is dpanda-us, ORMI port is 23793, and the application name is ejb30slsb, then the provider URL would be:
ormi://dpanda-us:23793/ejb30slsb
If the client is collocated with the target, the client exists within the same application as the target, or the target exists within its parent, then you do not need to initialize JNDI properties. Otherwise, you must initialize JNDI properties in one of the following ways:
This section describes:
For more information, see:
Oracle Containers for J2EE Services Guide
You can set JNDI properties in a file named jndi.properties that conforms to the requirements specified in the java.util.Properties method load.
If setting the JNDI properties within the jndi.properties file, make sure that this file is accessible from the client CLASSPATH.
Set JNDI properties as follows:
<PropertyName>=<PropertyValue>
For example:
java.naming.factory.initial= oracle.j2ee.server.ApplicationClientInitialContextFactory
For property names, see the field definitions in javax.naming.Context.
For an example, see "Specifying Credentials in JNDI Properties".
You can set JNDI properties as system properties specified either on the command line as a -D argument or as an environment reference (see "Configuring an Environment Reference to an Environment Variable").
You can set JNDI properties by creating a HashTable and populating it with the required properties using javax.naming.Context fields as keys and String objects as values. When you instantiate the initial context, pass the HashTable into the the initial context constructor.
For an example, see "Specifying Credentials in the Initial Context".
Using EJB 3.0, you can look up an EJB using resource injection (see "Using Annotations") or the InitialContext (see "Using Initial Context").
Example 19-20 shows how to use annotations and dependency injection to access an EJB 3.0 EJB from an EJB client.
Example 19-20 Injecting an EJB 3.0 EJB in an EJB 3.0 EJB Client
@EJB AdminService bean;
public void privilegedTask()
{
bean.adminTask();
}
Example 19-21 shows how to use annotations and dependency injection to access an EJB 2.1 EJB from an EJB 3.0 EJB client.
This section describes:
Looking Up the Remote Interface of an EJB 3.0 EJB Using ejb-ref
Looking Up the Remote Interface of an EJB 3.0 EJB Using location
Looking up the Local Interface of an EJB 3.0 EJB Using local-ref
Looking up the Local Interface of an EJB 3.0 EJB Using local-location
For more information, see "Configuring the Initial Context Factory".
To look up the remote interface of an EJB using an ejb-ref:
Define an ejb-ref for the EJB in the ejb-jar.xml file.
Example 19-22 ejb-jar.xml For an ejb-ref
<ejb-ref>
<ejb-ref-name>ejb/Test</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<local>Test</local>
</ejb-ref>
For more information, see "Configuring an Environment Reference to a Remote EJB").
Determine whether or not a prefix is required (see "Selecting an EJB Reference").
Look up the EJB using the ejb-ref-name and the appropriate prefix (if required).
Example 19-23 Looking Up Using ejb-ref in an EJB 3.0 EJB Client Using Initial Context
InitialContext ic = new InitialContext();
Cart cart = (Cart)ic.lookup("java:comp/env/ejb/Test");
For more information, see "Configuring the Initial Context Factory".
To look up the remote interface of an EJB using its location:
Define the entity-deployment attribute location in the orion-ejb-jar.xml file.
Example 19-24 orion-ejb-jar.xml For location
<entity-deployment
name="Test"
location="app/Test"
...
>
...
</entity-deployment>
The default value for location is the value of entity-deployment attribute name.
Determine whether or not a prefix is required (see "Selecting an EJB Reference").
Look up the EJB using the location.
Example 19-25 Looking Up Using location in an EJB 3.0 EJB Client Using Initial Context
InitialContext ic = new InitialContext();
Cart cart = (Cart)ic.lookup("java:comp/env/app/Test");
For more information, see "Configuring the Initial Context Factory".
To look up the remote interface of an EJB using an ejb-local-ref:
Define an ejb-local-ref for the EJB in the ejb-jar.xml file.
Example 19-26 ejb-jar.xml For an ejb-local-ref
<ejb-local-ref>
<ejb-ref-name>ejb/Test</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<local>Test</local>
</ejb-local-ref>
For more information, see "Configuring an Environment Reference to a Local EJB").
Determine whether or not a prefix is required (see "Selecting an EJB Reference").
Look up the EJB using the ejb-ref-name and the appropriate prefix (if required).
Example 19-27 Looking Up Using local-ref in an EJB 3.0 EJB Client Using Initial Context
InitialContext ic = new InitialContext();
Cart cart = (Cart)ctx.lookup("java:comp/env/ejb/Test");
For more information, see "Configuring the Initial Context Factory".
To look up the local interface of an EJB using its local-location:
Define the entity-deployment attribute local-location in the orion-ejb-jar.xml file.
Example 19-28 orion-ejb-jar.xml For local-location
<entity-deployment
name="Test"
local-location="app/Test"
...
>
...
</entity-deployment>
The default value for location is the value of entity-deployment attribute name.
Determine whether or not a prefix is required (see "Selecting an EJB Reference").
Look up the EJB using the local-location.
Example 19-29 Looking Up Using local-location in an EJB 3.0 EJB Client Using Initial Context
InitialContext ic = new InitialContext();
Cart cart = (Cart)ctx.lookup("java:comp/env/app/Test");
For more information, see "Configuring the Initial Context Factory".
Using EJB 3.0, you can look up a resource manage connection using resource injection (see "Using Annotations") or the InitialContext (see "Using Initial Context").
Example 19-30 shows how to use annotations and dependency injection to access an EJB 3.0 resource manager connection factory.
Example 19-31 shows how to use the initial context to look up an EJB 3.0 resource manager connection factory.
Example 19-31 Looking Up an EJB 3.0 Resource Manager Connection Factory
@Stateless public class EmployeeServiceBean implements EmployeeService
{
...
public void sendEmail(String emailAddress)
{
InitialContext ic = new InitialContext();
Session session = (Session) ic.lookup("java:comp/env/mail/testMailSession");
...
}
}
For more information, see "Configuring the Initial Context Factory".
Using EJB 3.0, you can look up an environment variable using resource injection (see "Using Resource Injection") or the InitialContext (see "Using Initial Context").
Using resource injection, you can rely on the container to initialize a field or a setter method (property) using either the:
default JNDI name (of the form java:comp/env/<FieldOrPropertyName>)
explicit JNDI name that you specify (do not prefix the name with "java:comp/env")
You cannot inject both field and setter using the same JNDI name.
The following examples show how to initialize the maxExemptions field with the value specified for the environment variable with the default JNDI name java:comp/env/maxExemptions.
You can use resource injection at the field level (see Example 19-32) or the set-method (property) level as Example 19-33 shows.
Example 19-32 Resource Injection at Field Level with Default Environment Variable Name
@Stateless public class EmployeeServiceBean implements EmployeeService
{
...
// The maximum number of tax exemptions, configured by Deployer
// Assumes JNDI name java:comp/env/maxExemptions.
@Resource int maxExemptions;
...
public void setMaxExemptions(int maxEx)
{
maxExemptions = maxEx;
}
...
}
Example 19-33 Resource Injection at the Property Level with a Default Environment Variable Name
@Stateless public class EmployeeServiceBean implements EmployeeService
{
...
int maxExemptions;
...
// Assumes JNDI name java:comp/env/maxExemptions.
@Resource
public void setMaxExemptions(int maxEx)
{
maxExemptions = maxEx;
}
...
}
You can specify an explicit JNDI name as Example 19-34 shows.
Example 19-35 shows how you look up these environment variables within the bean's code using the InitialContext.
Example 19-35 Looking Up Environment Variables
InitialContext ic = new InitialContext();
Integer min = (Integer) ic.lookup("java:comp/env/minBalance");
Integer max = (Integer) ic.lookup("java:comp/env/maxCreditBalance"));
Notice that to retrieve the values of the environment variables, you prefix each environment element with "java:comp/env/", which is the location that the container stored the environment variable.
For more information, see "Configuring the Initial Context Factory".
Using EJB 2.1, you can look up an EJB using the InitialContext (see "Using Initial Context").
To look up an EJB 3.0 EJB using the InitalContext, use the same approach.
This section describes:
Looking Up the Remote Interface of an EJB 2.1 EJB Using ejb-ref
Looking Up the Remote Interface of an EJB 2.1 EJB Using location
Looking up the Local Interface of an EJB 2.1 EJB Using local-ref
Looking up the Local Interface of an EJB 2.1 EJB Using local-location
For more information, see "Configuring the Initial Context Factory".
To look up the remote interface of an EJB using an ejb-ref:
Define an ejb-ref for the EJB in the ejb-jar.xml file.
Example 19-36 ejb-jar.xml For an ejb-ref
<ejb-ref>
<ejb-ref-name>ejb/Test</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<local>Test</local>
</ejb-ref>
For more information, see "Configuring an Environment Reference to a Remote EJB").
Determine whether or not a prefix is required (see "Selecting an EJB Reference").
Look up the EJB using the ejb-ref-name and the appropriate prefix (if required).
Example 19-37 Looking Up Using ejb-ref
InitialContext ic = new InitialContext();
Object homeObject = context.lookup("java:comp/env/ejb/Test");
CartHome home = (CartHome)PortableRemoteObject.narrow(homeObject,CartHome.class);
For more information, see "Configuring the Initial Context Factory".
To look up the remote interface of an EJB using its location:
Define the entity-deployment attribute location in the orion-ejb-jar.xml file.
Example 19-38 orion-ejb-jar.xml For location
<entity-deployment
name=EmployeeBean"
location="app/EmployeeBean"
...
>
...
</entity-deployment>
The default value for location is the value of entity-deployment attribute name.
Determine whether or not a prefix is required (see "Selecting an EJB Reference").
Look up the EJB using the location.
Example 19-39 Looking Up Using location
InitialContext ic = new InitialContext();
Object homeObject = context.lookup("java:comp/env/app/EmployeeBean");
CartHome home = (CartHome)PortableRemoteObject.narrow(homeObject,CartHome.class);
For more information, see "Configuring the Initial Context Factory".
To look up the remote interface of an EJB using an ejb-local-ref:
Define an ejb-local-ref for the EJB in the ejb-jar.xml file.
Example 19-40 ejb-jar.xml For an ejb-local-ref
<ejb-local-ref>
<ejb-ref-name>ejb/Test</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<local>Test</local>
</ejb-local-ref>
For more information, see "Configuring an Environment Reference to a Local EJB").
Determine whether or not a prefix is required (see "Selecting an EJB Reference").
Look up the EJB using the ejb-ref-name and the appropriate prefix (if required).
Example 19-41 Looking Up
InitialContext ic = new InitialContext();
Object homeObject = context.lookup("java:comp/env/ejb/Test");
CartHome home = (CartHome)PortableRemoteObject.narrow(homeObject,CartHome.class);
For more information, see "Configuring the Initial Context Factory".
To look up the local interface of an EJB using its local-location:
Define the entity-deployment attribute local-location in the orion-ejb-jar.xml file.
Example 19-42 orion-ejb-jar.xml For local-location
<entity-deployment
name=EmployeeBean"
local-location="app/EmployeeBean"
...
>
...
</entity-deployment>
The default value for location is the value of entity-deployment attribute name.
Determine whether or not a prefix is required (see "Selecting an EJB Reference").
Look up the EJB using the local-location.
Example 19-43 Looking Up Using local-location
InitialContext ic = new InitialContext();
Object homeObject = context.lookup("java:comp/env/app/EmployeeBean");
CartHome home = (CartHome)PortableRemoteObject.narrow(homeObject,CartHome.class);
For more information, see "Configuring the Initial Context Factory".
Using EJB 2.1, you can look up a resource manager connection factory using the InitialContext (see "Using Initial Context").
For more information on configuring resources, see "Resource Manager Connection Factory Environment References".
Example 19-44 shows how to look up a JDBC data source resource manager connection factory within the bean's code using the InitialContext with the logical name defined in the EJB deployment descriptor (see "Configuring an Environment Reference to a JDBC Data Source Resource Manager Connection Factory") prefixed with java:comp/env/jdbc prefix.
Example 19-44 Looking Up a JDBC Data Source Resource Manager Connection Factory
javax.sql.DataSource db;
java.sql.Connection conn;
...
InitialContext ic = new InitialContext();
db = (javax.sql.DataSource) initCtx.lookup("java:comp/env/jdbc/OrderDB");
conn = db.getConnection();
For more information, see "Configuring the Initial Context Factory".
Using EJB 2.1, you can look up an environment variable using the InitialContext (see "Using Initial Context").
For more information on configuring enviornment variables, see "Configuring an Environment Reference to an Environment Variable".
Example 19-35 shows how you look up these environment variables within the bean's code using the InitialContext.
Example 19-45 Looking Up Environment Variables
InitialContext ic = new InitialContext();
Integer min = (Integer) ic.lookup("java:comp/env/minBalance");
Integer max = (Integer) ic.lookup("java:comp/env/maxCreditBalance"));
Notice that to retrieve the values of the environment variables, you prefix each environment element with "java:comp/env/", which is the location that the container stored the environment variable.
For more information, see "Configuring the Initial Context Factory".
