Configuring Environment References

You can create three types of environment elements that are accessible to your bean during runtime: environment variables, EJB references, and resource managers. These environment elements are static and can not be changed by the bean.

ISVs typically develop EJBs that are independent from the EJB container. In order to distance the bean implementation from the container specifics, you can create environment elements that map to one of the following: defined variables, entity beans, or resource managers. This indirection enables the bean developer to refer to existing variables, EJBs, and a JDBC DataSource without specifying the actual name. These names are defined in the deployment descriptor and are linked to the actual names within the OC4J-specific deployment descriptor.

Environment Variables

You can create environment variables that your bean accesses through a lookup on the InitialContext. These variables are defined within an <env-entry> element and can be of the following types: String, Integer, Boolean, Double, Byte, Short, Long, and Float. The name of the environment variable is defined within <env-entry-name>, the type is defined in <env-entry-type>, and its initialized value is defined in <env-entry-value>. The <env-entry-name> is relative to the "java:comp/env" context.

For example, the following two environment variables are declared within the XML deployment descriptor for java:comp/env/minBalance and java:comp/env/maxCreditBalance.

<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>

Within the bean's code, you would access these environment variables through the InitialContext, as follows:

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.

If you wanted the value of the environment variable to be defined in the OC4J-specific deployment descriptor, you can map the <env-entry-name> to the <env-entry-mapping> element in the OC4J-specific deployment descriptor. This means that the value specified in the orion-ejb-jar.xml file overrides any value that may be specified in the ejb-jar.xml file. The type specified in the EJB deployment descriptor stays the same.

Figure 10-3 shows how the minBalance environment variable is defined as 500 within the OC4J-specific deployment descriptor.

Figure 10-3 Environment Variable Mapping

Description of the illustration packaging3.gif

Environment References To Other Enterprise JavaBeans

You can define an environment reference to an EJB through either its local or remote interface within the deployment descriptor. If your bean calls out to another bean, you can enable your bean to invoke the second bean using a reference defined within the deployment descriptors. You create a logical name within the EJB deployment descriptor, which is mapped to the concrete name of the bean within the OC4J-specific deployment descriptor.

Declaring the target bean as an environment reference provides a level of indirection: the originating bean can refer to the target bean with a logical name.

A reference to the local interface of a bean is defined in an <ejb-local-ref> element; a reference to the remote interface of a bean is defined in an <ejb-ref> element.

To define a reference to another EJB within the JAR or in a bean declared as a parent, you provide the following:

Name—provide a name for the target bean. This name is what the bean uses within the JNDI location for accessing the target bean. The name should begin with "ejb/", such as "ejb/myEmployee", and will be available within the "java:comp/env/ejb" context.
- This name can be the actual name of the bean; that is, the name defined within the <ejb-name> element in the <session> or <entity> elements.
- This name can be a logical name that you want to use in your implementation. But it is not the actual name of the bean. If you use a logical name, the actual name must either be specified in the <ejb-link> element or <ejb-ref-mapping> element in the OC4J-specific deployment descriptor.
Type—define whether the bean is a session or an entity bean. Value should be either "Session" or "Entity".
Home—provide the fully qualified home interface name.
Remote—provide the fully qualified remote interface name.
Link—provide the EJB name of the target bean. This is optional and only used if you used a logical name in the name attribute.

Examples of References to a Local Interface

If you have two beans in the JAR: BeanA and BeanB. If BeanB creates a reference to the local interface of BeanA, you can define this reference in one of three methods:

Provide the actual name of the bean. BeanB would define the following <ejb-local-ref> within its definition:
```
<ejb-local-ref>
 <ejb-ref-name>myBeans/BeanA</ejb-ref-name>
 <ejb-ref-type>Session</ejb-ref-type>
 <local-home>myBeans.BeanALocalHome</local-home>
 <local>myBeans.BeanALocal</local>
</ejb-local-ref>
```
Since the EJB name of the target is specified in the <ejb-ref-name> element, no <ejb-link> is necessary for this method. However, the BeanB implementation must refer to BeanA in the JNDI retrieval, which would use java:comp/env/myBeans/BeanA for retrieval within an EJB or Java client and use "myBeans/BeanA" within a servlet.

Note:
Servlets do not require the prefix of "java:comp/env" in the JNDI lookup. Thus, they will always either reference just the actual JNDI name or the logical name of the EJB.
Provide the EJB name of the bean in the <ejb-link> element. You can use any logical name in your bean implementation for the JNDI retrieval by defining a logical name in the <ejb-ref-name> element and then map it to the target bean by specifying the target EJB name in the <ejb-link> element. The following defines a logical name of ejb/nextVal that this bean can use in its code in the JNDI retrieval. The container maps it to the target bean, myBeans/BeanA, which is specified in the <ejb-link> element.
```
<ejb-local-ref>
 <ejb-ref-name>ejb/nextVal</ejb-ref-name>
 <ejb-ref-type>Session</ejb-ref-type>
 <local-home>myBeans.BeanALocalHome</local-home>
 <local>myBeans.BeanALocal</local>
 <ejb-link>myBeans/BeanA</ejb-link>
</ejb-local-ref>
```
BeanB would use java:comp/env/ejb/nextVal in the JNDI retrieval of BeanA.
Provide the logical name of the bean in the <ejb-ref-name> and the actual name of the bean in the <ejb-ref-mapping> element in the OC4J-specific deployment descriptor.

The reference in the EJB deployment descriptor would be as follows:
```
<ejb-local-ref>
 <ejb-ref-name>ejb/nextVal</ejb-ref-name>
 <ejb-ref-type>Session</ejb-ref-type>
 <local-home>myBeans.BeanALocalHome</local-home>
 <local>myBeans.BeanALocal</local>
</ejb-local-ref>
```
The "ejb/nextVal" logical name is mapped to an actual name in the OC4J-deployment descriptor as follows:
```
<ejb-ref-mapping name="ejb/nextVal" location="myBeans/BeanA"/>
```
BeanB would use java:comp/env/ejb/nextVal in the JNDI retrieval of BeanA.

As shown in Figure 10-4, the logical name for the bean is mapped to the JNDI name by providing the same name, "ejb/nextVal", in both the <ejb-ref-name> in the EJB deployment descriptor and the name attribute within the <ejb-ref-mapping> element in the OC4J-specific deployment descriptor.

Figure 10-4 EJB Reference Mapping

Description of the illustration packaging4.gif

Accessing EJBs Using Environment References

To access a bean from within your implementation using a reference, use the <ejb-ref-name> defined in the EJB deployment descriptor in the JNDI lookup.

If you are using the default context when you retrieve the InitialContext, then you can do one of the following:

Prefix the logical name defined within the <ejb-ref-name> element with "java:comp/env/ejb/", which is where the container places the EJB references defined in the deployment descriptor.
Do not prefix the logical name with any string and supply only the logical name defined in the <ejb-ref-name>.

The following is a lookup from an EJB client, using the java:comp/env prefix, assuming that the logical name is "ejb/HelloWorld."

InitialContext ic = new InitialContext();
HelloHome hh = (HelloHome)ic.lookup("java:comp/env/ejb/HelloWorld");

The following is a lookup using only the logical name of "ejb/HelloWorld."

InitialContext ic = new InitialContext();
HelloHome hh = (HelloHome)ic.lookup("ejb/HelloWorld");

However, if you are not using the default context, but are specifically using another context, such as the RMIInitialContext object, you can only use the logical name, as follows:

InitialContext ic = new InitialContext();
HelloHome hh = (HelloHome)ic.lookup("ejb/HelloWorld");

Example 10-2 Defining a Local EJB Reference Within the Environment

The following example defines a reference to the local interface of the Hello bean, as follows:

The logical name used for the target bean within the originating bean is "java:comp/env/ejb/HelloWorld".
The target bean is a session bean.
Its local home interface is hello.HelloLocalHome; its local interface is hello.HelloLocal.
The <ejb-ref-name> attribute is the logical name used within the originating bean. This is optional. In this example, this bean is defined in the EJB deployment descriptor under the "ejb/HelloWorld" name.
```
<ejb-local-ref>
   <description>Hello World Bean</description>
   <ejb-ref-name>ejb/HelloWorld</description>
   <ejb-ref-type>Session</ejb-ref-type>
   <local-home>hello.HelloLocalHome</local-home>
   <local>hello.Hello.Local</local>
</ejb-local-ref>
```
The <ejb-ref-name> element in the EJB deployment descriptor is mapped to the name attribute within the <ejb-ref-mapping> element in the OC4J-specific deployment descriptor by providing the same logical name in both elements. The Oracle-specific deployment descriptor would have the following definition to map the logical bean name of "java:comp/env/ejb/HelloWorld" to the JNDI location "/test/myHello":
```
<ejb-ref-mapping
   name="ejb/HelloWorld"
   location-"/test/myHello"/>
```
To invoke this bean from within your implementation, you use the <ejb-ref-name> defined in the EJB deployment descriptor. In EJB or pure Java clients, you prefix this name with "java:comp/env/ejb/", which is where the container places the EJB references defined in the deployment descriptor. Servlets only require the logical name defined in the <ejb-ref-name>.

The following is a lookup from an EJB, acting as a client:
```
InitialContext ic = new InitialContext();
HelloHome hh = (HelloHome)ic.lookup("java:comp/env/ejb/HelloWorld");
```
Alternatively, you could lookup the name, as follows:
```
InitialContext ic = new InitialContext();
HelloHome hh = (HelloHome)ic.lookup("ejb/HelloWorld");
```

Examples of References to a Remote Interface

Defining a reference to a remote interface uses exactly the same rules as the local interface, as described in "Examples of References to a Local Interface". The only difference is as follows:

Use the <ejb-ref> instead of the <ejb-local-ref> element.
Use the <home> and <remote> elements instead of the <local-home> and <local> elements.

Everything else is the same.

The following uses an example with two beans in the JAR: BeanA and BeanB. If BeanB creates a reference to BeanA, you can define this reference in one of three methods:

Provide the actual name of the bean.

<ejb-ref>
 <ejb-ref-name>myBeans/BeanA</ejb-ref-name>
 <ejb-ref-type>Session</ejb-ref-type>
 <home>myBeans.BeanAHome</home>
 <remote>myBeans.BeanA</remote>
</ejb-ref>

Provide the EJB name of the bean in the <ejb-link> element.

<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-link>myBeans/BeanA</ejb-link>
</ejb-ref>

Provide the logical name of the bean in the <ejb-ref-name> and the actual name of the bean in the <ejb-ref-mapping> element in the OC4J-specific deployment descriptor.
```
<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>
```
The "ejb/nextVal" logical name is mapped to an actual name in the OC4J-deployment descriptor as follows:
```
<ejb-ref-mapping name="ejb/nextVal" location="myBeans/BeanA"/>
```

Refer to "Examples of References to a Local Interface" for more description and a code example.

Environment References To Resource Manager Connection Factory References

The resource manager connection factory references can include resource managers such as JMS, Java mail, URL, and JDBC DataSource objects. Similar to the EJB references, you can access these objects from JNDI by creating an environment element for each object reference. However, these references can only be used for retrieving the object within the bean that defines these references. Each is fully described in the following sections:

JDBC DataSource
Mail Session
URL

JDBC DataSource

You can access a database through JDBC either using the traditional method or by creating an environment element for a JDBC DataSource. In order to create an environment element for your JDBC DataSource, you must do the following:

Define the DataSource in the data-sources.xml file.
Create a logical name within the <res-ref-name> element in the EJB deployment descriptor. This name should always start with "jdbc". In the bean code, the lookup of this reference is always prefaced by "java:comp/env/jdbc".
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/jdbc" preface and the logical name defined in the EJB deployment descriptor.

As shown in Figure 10-5, the JDBC DataSource uses the JNDI name "test/OrderDataSource". The logical name that the bean knows this resource as is "jdbc/OrderDB". These names are mapped together within the OC4J-specific deployment descriptor. Thus, within the bean's implementation, the bean can retrieve the connection to OrderDataSource by using the "java:comp/env/jdbc/OrderDB" environment element.

Figure 10-5 JDBC Resource Manager Mapping

Description of the illustration packaging5.gif

Example 10-3 Defining an environment element for JDBC Connection

The environment element is defined within the EJB deployment descriptor by providing the logical name, "jdbc/OrderDB", its type of javax.sql.DataSource, and the authenticator of "Application":

<resource-ref>
   <res-ref-name>jdbc/OrderDB</res-ref-name>
   <res-type>javax.sql.DataSource</res-type>
   <res-auth>Application</res-auth>
</resource-ref>

The environment element of "jdbc/OrderDB" is mapped to the JNDI bound name for the connection, "test/OrderDataSource" within the Oracle-specific deployment descriptor.

resource-ref-mapping
   name="jdbc/OrderDB"
      location="test/OrderDataSource"/>

Once deployed, the bean can retrieve the JDBC DataSource as follows:

javax.sql.DataSource db;
java.sql.Connection conn;
.
.
.
db = (javax.sql.DataSource) initCtx.lookup("java:comp/env/jdbc/OrderDB");
conn = db.getConnection();

Note:

This example assumes that a DataSource is specified in the data-sources.xml file with the JNDI name of "/test/OrderDataSource".

Mail Session

You can create an environment element for a Java mail Session object through the following:

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. This name should always start with "mail". In the bean code, the lookup of this reference is always prefaced by "java:comp/env/mail".
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 10-6, 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.

Figure 10-6 Session Resource Manager Mapping

Description of the illustration packaging6.gif

This environment element is defined with the following information:

Element	Description
`<res-ref-name>`	The logical name of the `Session` object to be used within the originating bean. The name should be prefixed with "`mail`/". In our example, the logical name for our mail session is "`mail/testMailSession`".
`<res-type>`	The Java type of the resource. For the Java mail `Session` object, this is `javax.mail.Session`.
`<res-auth>`	Define who is responsible for signing on to the database. The value can be "`Application`" or "`Container`" based on who provides the authentication information.

Example 10-4 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":

<resource-ref>
   <res-ref-name>mail/TestMailSession</res-ref-name>
   <res-type>javax.mail.Session</res-type>
   <res-auth>Application</res-auth>
</resource-ref>

The environment element of "mail/testMailSession" is mapped to the JNDI bound name for the connection, "test/myMailSession" within the OC4J-specific deployment descriptor:

<resource-ref-mapping
   name="mail/TestMailSession"
   location="/test/myMailSession"/>

Once deployed, the bean can retrieve the Session object reference as follows:

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);

URL

You can create an environment element for a Java URL object through the following:

Create a logical name within the <res-ref-name> element in the EJB deployment descriptor. This name should always start with "url". In the bean code, the lookup of this reference is always prefaced by "java:comp/env/url".
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 10-7, 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.

Figure 10-7 URL Resource Manager Mapping

Description of the illustration packaging7.gif

This environment element is defined with the following information:

Element	Description
`<res-ref-name>`	The logical name of the `URL` object to be used within the originating bean. The name should be prefixed with "`url`/". In our example, the logical name for our URL is "`url/testURL`".
`<res-type>`	The Java type of the resource. For the Java URL object, this is `java.net.URL`.
`<res-auth>`	Define who is responsible for signing on to the database. At this time, the only value supported is "`Application`". The application provides the authentication information.

Example 10-5 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":

<resource-ref>
   <res-ref-name>url/testURL</res-ref-name>
   <res-type>java.net.URL</res-type>
   <res-auth>Application</res-auth>
</resource-ref>

The environment element of "url/testURL" is mapped to the URL "http://www.myURL.com" within the OC4J-specific deployment descriptor:

<resource-ref-mapping
   name="url/testURL"
   location="http://www.myURL.com"/>

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();