Configuring an Environment Reference to a Remote EJB: Unclustered Separate Web Tier and EJB Tier

A common Java EE application architecture is one in which you deploy the Web tier to one OC4J instance, and the EJB tier–to another OC4J instance on a separate host in a nonclustered environment.

In this architecture, to access a remote enterprise bean, you must populate the required JNDI properties in your Web-tier code when you create the context (for example, see "Setting JNDI Properties in the Initial Context"). These hard-coded properties can cause portability problems, when, for example, migrating from a test environment to a production environment.

Using OC4J-proprietary deployment XML (see "Using Deployment XML"), you can associate a reference to a remote enterprise bean with a JNDI properties file that contains the required JNDI context variables. This simplifies assembly and deployment.

Figure 19-2 shows this architecture for a JSP/Servlet client, and Figure 19-3 shows this architecture for an EJB client.

Figure 19-2 Web-tier and EJB-tier Remote EJB Access: JSP/Servlet Client

Description of "Figure 19-2 Web-tier and EJB-tier Remote EJB Access: JSP/Servlet Client"

Figure 19-3 Web-tier and EJB-tier Remote EJB Access: EJB Client

Description of "Figure 19-3 Web-tier and EJB-tier Remote EJB Access: EJB Client"

For more information about the JNDI properties file, see "Setting JNDI Properties With the JNDI Properties File").

Using Deployment XML

To associate a reference to a remote enterprise bean with a JNDI properties file that contains the required JNDI context variables using OC4J-proprietary element <ejb-ref-mapping>, perform the following configuration on the Web-tier OC4J instance:

1. Define an <ejb-ref> element in the appropriate client deployment descriptor (see "Where do you Configure an EJB Environment Reference?") and configure the following subelements, as Example 19-5 shows:

   • <ejb-ref-name>: the logical name of the target enterprise bean.

   • <ejb-ref-type>: the type of the target enterprise bean, one of Session or Entity.

   • <home>: the package and class name of the target enterprise bean's remote home interface.

   • <remote>: package and class name of the target enterprise bean's remote component interface.

   Example 19-5 Configuring ejb-ref-name With a Logical Name Resolved by ejb-ref-mapping

   <ejb-ref>
    <ejb-ref-name>ejb/emp</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <home>myBeans.EmployeeBeanHome</home>
    <remote>myBeans.EmployeeBean</remote>
   </ejb-ref>
   

   In this architecture, the client deployment descriptor is on the Web-tier OC4J instance. The client of the remote enterprise bean is one of the following:

   • a JSP or servlet deployed on the Web tier: use the web.xml file.

   • an enterprise bean deployed on the Web tier: use the ejb-jar.xml file.

2. Within the orion-web.xml or orion-ejb-jar.xml deployment descriptor (depending on your type of client), define an <ejb-ref-mapping> element that does the following, as Example 19-6 shows:

   • maps the logical name (ejb/emp) to the actual name (myBeans/EmployeeBean) of the target bean;

   • specifies that target EJB instances are located on a remote host (remote-server-ref="true");

   • associates the reference with a JNDI properties file (jndi-properties-file="empjndi.properties") that contains the JNDI context variables that a client needs to access the remote host, on which target EJB instances are deployed.

   Example 19-6 Mapping Logical Name to Actual Name With ejb-ref-mapping for a Remote Target EJB

   <ejb-ref-mapping
       name="ejb/emp"
       location="myBeans/EmployeeBean"
       remote-server-ref="true"
       jndi-properties-file="empjndi.properties"
   />
   

   As Figure 19-1 shows, in the <ejb-ref-mapping> element, you 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-4, the logical name ejb/emp is mapped to the actual name of the target bean myBeans/EmployeeBean.

   Figure 19-4 Associating ejb-ref-name and ejb-ref-mapping for a Remote Target EJB

   
   Description of "Figure 19-4 Associating ejb-ref-name and ejb-ref-mapping for a Remote Target EJB"
   
   

   When the Web-tier client (JSP/Servlet or enterprise bean deployed to the Web tier) accesses the remote target enterprise bean (using injection or JNDI lookup), the Web-tier OC4J instance maps the logical name (specified in the Web-tier OC4J instance's web.xml or ejb-jar.xml file) to the actual name (specified in the Web-tier OC4J instance's orion-web.xml or orion-ejb-jar.xml file). The Web-tier OC4J instance uses the JNDI properties file specified in the <ejb-ref-mapping> element to access the EJB-tier OC4J instance and resolve the actual name to the target enterprise bean on the EJB-tier OC4J instance.