Oracle® Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide
10g Release 2 (10.1.2) Part No. B15505-01 |
|
![]() Previous |
![]() Next |
To access an EJB from a client, you must do the following:
If you are remote, download the oc4j.jar
file.
Set up JNDI properties for the connection, if necessary.
Determine which InitialContextFactory
you will use for the connection.
Retrieve an EJB using either the JNDI name or an EJB reference, which is configured in the deployment descriptor.
These subjects are discussed in the following sections:
In order to access EJBs, the client-side must download oc4j_client.zip
file from http://www.oracle.com/technology/software/products/ias/devuse.html
. Unzip the JAR into a directory that is in your CLASSPATH. This JAR contains the classes necessary for client interaction. If you download this JAR into a browser, you must grant certain permissions. See "Granting Permissions in Browser" for a list of these permissions.
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 a JNDI properties file. Else, you must initialize your JNDI properties either within a jndi.properties
file, in the system properties, or within your implementation, before the JNDI call. The following sections discuss these three options:
To specify credentials within the JNDI properties, see "Specifying Credentials in EJB Clients".
Note: A full description of how to use JNDI, see the JNDI chapter in the Oracle Application Server Containers for J2EE Services Guide. |
A servlet that is collocated with the target bean automatically accesses the JNDI properties for the node. Thus, accessing the EJB is simple: no JNDI properties are required.
//Get the Initial Context for the JNDI lookup for a local EJB InitialContext ic = new InitialContext(); //Retrieve the Home interface using JNDI lookup Objecthello
Object = ic.lookup("java:comp/env/ejb/HelloBean
");
This is also true if the target bean is in the same application or an application that has been deployed as this application's parent. See the Oracle Application Server Containers for J2EE User's Guide for more information on how to set the parent of the application.
If setting the JNDI properties within the jndi.properties
file, set the properties as follows. Make sure that this file is accessible from the CLASSPATH
.
Factory
See "When Do You Use the Different Initial Context Factory Classes?" for discussion on the initial context factory to use.
java.naming.factory.initial= com.evermind.server.ApplicationClientInitialContextFactory
Location
All ports, including the RMI port, are dynamically set by OPMN when each OC4J instance starts. When you specify the following URL in the client JNDI properties, the client-side OC4J retrieves the dynamic ports for the instance, and chooses one from the list for communication.
java.naming.provider.url= opmn:ormi://<opmn_host>:<opmn_port>:<oc4j_instance>/<application-name>
The OPMN host name and port number is retrieved from the opmn.xml
file. In most cases, OPMN is located on the same machine as the OC4J instance. However, you must specify the host name in case it is located on another machine. The OPMN port number is optional; if excluded, the default is port 6003. The OPMN port is specified in opmn.xml
.
The OC4J instance name is defined in the Enterprise Manager. The ORMI default port number is 23791, which can be modified in . Thus, set the URL in the , in one of the two ways:
Security
When you access EJBs in a remote container, you must pass valid credentials to this container. Stand-alone clients define their credentials in the jndi.properties
file deployed with the client's code.
java.naming.security.principal=<username> java.naming.security.credentials=<password>
Set the properties with the same values, only with a different syntax. For example, JavaBeans running within the container pass their credentials within the InitialContext
, which is created to look up the remote EJBs.
In the java.naming.provider.url
, the "opmn:ormi
" location string is provided. Both OPMN and OC4J are located on the same host. The OPMN default port is used, so the port number is not specified.
In the java.naming.factory.initial
, the ApplicationClientInitialContextFactory
object is used.
To pass JNDI properties within the Hashtable
environment, set these as shown below:
Hashtable env = new Hashtable(); env.put("java.naming.provider.url", "opmn:ormi://opmnhost:oc4j_inst1/ejbsamples"); env.put("java.naming.factory.initial", "com.evermind.server.ApplicationClientInitialContextFactory"); env.put(Context.SECURITY_PRINCIPAL, "guest"); env.put(Context.SECURITY_CREDENTIALS, "welcome"); Context ic = new InitialContext (env); Object homeObject = ic.lookup("java:comp/env/ejb/HelloBean
"); // Narrow the reference to aHello
Home.Hello
Home empHome = (Hello
Home) PortableRemoteObject.narrow(homeObject,Hello
Home.class);
The rules for which initial context factory are the same for OC4J standalone applications. However, since OC4J standalone does not use OPMN, the location URL cannot use the opmn:ormi://
prefix. Instead, the ormi://
prefix is used.
The ORMI default port number is 23791, which can be modified in config/rmi.xml. Thus, set the URL in the jndi.properties, in one of the two ways:
java.naming.provider.url=ormi://<hostname>/<application-name>
or
java.naming.provider.url=ormi://<hostname>:23791/<application-name>\
When you access EJBs in a remote container, you must pass valid credentials to this container. Stand-alone clients define their credentials in the jndi.properties file deployed with the client's code.
java.naming.security.principal=<username> java.naming.security.credentials=<password>
If you set the properties within the bean implementation, then set them with the same values, just with different syntax. For example, JavaBeans running within the container pass their credentials within the InitialContext, which is created to look up the remote EJBs.
To pass JNDI properties within the Hashtable environment, set these as shown below:
Hashtable env = new Hashtable();
env.put("java.naming.provider.url", "ormi://myhost/ejbsamples
");
env.put("java.naming.factory.initial",
"com.evermind.server.ApplicationClientInitialContextFactory");
env.put(Context.SECURITY_PRINCIPAL, "guest");
env.put(Context.SECURITY_CREDENTIALS, "welcome");
Context ic = new InitialContext (env);
Object homeObject = ic.lookup("java:comp/env/ejb/HelloBean");
// Narrow the reference to a HelloHome.
HelloHome helloHome =
(HelloHome) PortableRemoteObject.narrow(homeObject,
HelloHome.class);
The type of initial context factory that you use depends on who the client is. The initial context factory creates the initial context class for the client.
If the client is a pure Java client outside of the OC4J container, use the ApplicationClientInitialContextFactory
class.
If the client is an EJB or servlet client within the OC4J container, use the ApplicationInitialContextFactory
class. The ApplicationInitialContextFactory
class is the default class; thus, each time you create a new InitialContext
without specifying any initial context factory class, your client uses the ApplicationInitialContextFactory
class.
If the client is an administrative class that is going to manipulate or traverse the JNDI tree, use the com.evermind.server.RMIInitialContextFactory
class.
If the client is going to use DNS load balancing, use the RMIInitialContextFactory
class.
For example, if you have a pure Java client, then you set the initial context factory class ("java.naming.factory.initial
") to ApplicationClientInitialContextFactory
. The following example sets the initial context factory in the environment, but you could also put this in the JNDI properties file.
env.put("java.naming.factory.initial", "com.evermind.server.ApplicationClientInitialContextFactory");
If the client is an EJB or a servlet calling an EJB in the same application, you can use the default by not setting the JNDI properties with a initial context factory and uses the ApplicationInitialContextFactory
object by executing the following:
InitialContext ic = new InitialContext();
If you decide to use the RMIInitialContextFactory
class, you must use the JNDI name in the lookup and not a logical name defined in the <ejb-ref>
in your XML configuration file.
To use DNS for load balancing, you must do the following:
Within DNS, map a single host name to several IP addresses. Each of the port numbers must be the same for each IP address. Set up the DNS server to return the addresses either in a round-robin or random fashion.
Turn off DNS caching on the client. For UNIX machines, you must turn off DNS caching as follows:
Kill the NSCD daemon process on the client.
Start the OC4J client with the -Dsun.net.inetaddr.ttl=0
option.
Within each client, use any initial context factory to create an initial context. You can use either the opmn:ormi://
or the ormi://
prefix in the provider URL. Use opmn:ormi://
syntax for Oracle9iAS applications and the ormi://
for standalone OC4J applications.
Set the dedicated.rmicontext
property to true.
Each time the lookup occurs on the DNS server, the DNS server hands back a one of the many IP addresses that are mapped to it.
Before you start implementing your call to the EJB in your client, you should consider the following for the JNDI retrieval of the EJB reference of the bean:
Within your client code, you retrieve an EJB reference to the target bean in order to execute methods on that bean. Do you want to set up a logical name for the target bean or use the JNDI name?
Use the logical name: Modify the client XML configuration file to set up the <ejb-ref>
element with the target bean information. The logical name specified in the <ejb-ref-name>
element is used in the JNDI lookup. See "Configuring the EJB Reference Information" for more information on the <ejb-ref>
and <ejb-ref-name>
elements.
Use the actual name: The actual name of the bean is used in the JNDI lookup. This name has been specified in the target bean's ejb-jar.xml
XML deployment descriptors in the <ejb-name>
element.
The method for accessing EJBs depends on where your client is located relative to the bean it wants to invoke.
Is the client is collocated with the target bean? Deployed in the same application? Or is the target bean part of an application that is this client's parent? You do not need to set up any JNDI properties.
Otherwise, you must set up JNDI properties. There are two methods for setting up JNDI properties. See "Setting JNDI Properties" for more information
Specify the EJB reference information for the remote EJB in the <ejb-ref>
or <ejb-local-ref>
elements in the client's XML file:
application-client.xml
: The client is a pure-Java client, invoking the bean outside of the container.
ejb-jar.xml
: The client is another EJB.
web.xml
: The client is a servlet or JSP.
For example, if a client wants to access the remote interface of the Hello
example, then the client's XML would define the following:
<ejb-ref> <ejb-ref-name>ejb/HelloBean</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>hello.HelloHome</home> <remote>hello.Hello</remote> </ejb-ref>
If the client wants to access the local interface of the Hello
example, then the client's XML would define the following:
<ejb-ref> <ejb-ref-name>ejb/HelloBean</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home>hello.HelloLocalHome</local-home> <local>hello.HelloLocal</local> </ejb-ref>
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.