Consuming Java Enterprise Resources

One of the goals of deployment descriptors in the Java EE platform is to provide a standard way of describing external facilities that need to be available for successful execution of the enterprise application. The declaration in the deployment descriptor references the expected interface and the name used to locate this instance. This binding and declaration mechanism allows the late binding of resources. (In Java EE role terms, the deployer can change the actual resource used without changing the source code or the mandatory deployment descriptors.)

A resource is an external entity required by an enterprise application that is referenced using the standard deployment descriptor. A large number of resources can be used, but some of the most common are JDBC (via the javax.sql.DataSource interface), JMS (via the javax.jms.* interfaces), and enterprise beans (using the interfaces exposed by the bean developer).

Several steps are required to incorporate a resource into an application:

• Declaration of the resource in the standard deployment descriptor

• Resource setup in the server-specific deployment descriptor, which may also include setup on the server instance itself

• Acquisition of the resource using JNDI

• Using the resource in the programming environment

NetBeans IDE provides commands to automate the use of resources. Typically, you realize that a resource should be used while you are writing Java code. The IDE makes it easy to add a resource as you are coding by providing an Enterprise Resources submenu on the contextual menu in the Source Editor for Java classes contained in enterprise projects (web applications and EJB Modules). See Figure 13-19.

Figure 13-19. Source Editor with the contextual menu open and the Enterprise Resources submenu selected

The Enterprise Resources menu provides a set of commands that automate the use of JMS, JDBC, enterprise beans, and email. Subsequent sections in this chapter describe what happens when the wizards are invoked and how to use the wizards.

All the actions are able to incorporate the Java BluePrints Service Locator pattern, which encapsulates and caches the JNDI initial context lookup. This pattern aggregates all boilerplate lookup code and provides the potential for performance enhancements.

NetBeans IDE provides two different service locator strategies: caching and non-caching. The caching strategy uses the singleton pattern and caches both the initial context and the results from the JNDI lookup. The non-caching locator does not cache the lookup results, but instead reuses the initial context. The Service Locator templates are available under the Enterprise node in the New File wizard, as shown in Figure 13-20.

Figure 13-20. New File wizard with the Caching Service Locator template selected

The Service Locator template generates a Java source file that can be further customized. The service locator last used for the project is stored with the project settings, allowing the last locator to be reused easily. The service locator naming conventions provided in the templates are incorporated into the enterprise resource commands; therefore, changing the name of the public lookup methods after generation may require manual intervention following the use of the enterprise resource commands.

The caching service locator strategy is most useful from a web module where resource definitions are shared across the entire module. The singleton pattern can be used effectively in this scenario to reuse lookup instances. In an EJB module, resource declarations are scoped to a single enterprise bean; thus, the singleton pattern is not applicable. An EJB module will commonly use a non-caching service locator.

Using Enterprise Beans

If you want to use an enterprise bean, perform the following steps:

1.	Declare an ejb-ref entry or an ejb-local-ref entry (depending on whether the enterprise bean exposes local or remote interfaces) in the deployment descriptor. The deployment descriptor entry will specify the home and component interface, a name used in the JNDI lookup to specify the instance, the type of enterprise bean (either session or entity), and a reference to the actual enterprise bean.
2.	Perform a JNDI lookup to obtain an instance of the home interface.
3.	Use a create or finder method on the home interface to obtain an instance of the component interface.

The Call Enterprise Bean command (which you can access by right-clicking the Source Editor and choosing Enterprise Resources | Call Enterprise Bean) automates this process. The dialog box shown in Figure 13-21 provides a way to select the enterprise bean to invoke. This dialog further enables you to specify the enterprise bean, the desired lookup strategy, and whether checked exceptions should be converted to runtime exceptions.

Figure 13-21. Dialog box for the Call Enterprise Bean command

Using the Call Enterprise Bean command in an EJB Module project or a Web project will result in the following:

• Generation of an ejb-ref or ejb-local-ref in the deployment descriptor. If this is done from an EJB module, this feature can be invoked directly only from the bean class. This feature requires that the referenced enterprise bean is in the same deployment unit (either the same module or the same enterprise application) as required by the semantics of the ejb-link (the reference is based on ModuleName#EjbName syntax and requires the reference to be collocated).

• Generation of the lookup code. If a service locator is being used, the generated code delegates the lookup to the locator; otherwise, lookup code is generated. The generated code uses the JDK logging framework to log the exception. The lookup code returns the home interface unless a stateless session bean is referenced, in which case an instance of the component interface is returned.

• Establishment of a project dependency between the current project and the referenced project, as the interfaces from the enterprise beans need to be used during compilation. The interfaces will not be included in the archive of the referencing project, but will instead assume that the server supports delegation to the application class loader (for references outside a module). If this is not true, the Java Extension mechanism can be used to add a classpath reference to the EJB module.

Using a Database

The Use Database command automates the process of incorporating a relational database into an application. If you intend to use a database, you must go through the following steps:

1.	Declare a resource-ref entry in the deployment descriptor. The deployment descriptor entry must specify the resource-type javax.sql.DataSource, the ability to share the resource, and the authorization mechanism (typically, the authorization is done by the container).
2.	Add code to perform a JNDI lookup to obtain an instance of DataSource.
3.	Use server specific mechanisms to configure the application server to use the JDBC resource. This typically involves adding the JDBC driver to the server classpath, as well as setting up a connection pool for the JDBC connection describing how to connect (including authentication) to the database.

The Enterprise Resources | Use Database command (available by right-clicking a file in the Source Editor) automates this process. When you choose this command, the Choose Database dialog box (shown in Figure 13-22) appears and prompts you to select the database to use in either a web module or an EJB module. In the dialog box, specify a JNDI name (used as the resource reference name), the connection to use, and whether a service locator should be used or inline code should be generated (lookup code is generated in the current class). The list of connections is the same as what is provided in the Runtime window.

Figure 13-22. Choose Database dialog box

After you fill in the Choose Database dialog box, the following occurs:

• A resource reference is added to the deployment descriptor using the form jdbc/JNDIName. Existing resource references are reused if possible (matching is done using the description, which initially is populated via the connection string).

• Code is generated to automate the JNDI lookup, using the specified lookup strategy to obtain the data source.

• If the Add Driver and Add Connection buttons are used, a connection node (and also possibly a driver node) is added to the Runtime window.

• Assuming that you are using the Sun Java System Application Server, the necessary steps to enable successful deployment and execution are performed. (Technically, it's the IDE's Sun Java System Application Server integration plug-in module that provides this support. By the time you read this, there might be IDE plug-in modules to provide equivalent features for different servers.) This might involve creating a connection pool and adding the JDBC driver to the classpath of the application server. The connection pool setup can be configured later in the Server Resources node or via the administrative capability of the server. The Server Resources node enables you to provide version control for and deploy server resources that are required to successfully execute an application. The resources provide all the necessary information to configure the setup. This may include usernames and passwords, so editing these files may be necessary when sharing the application with other team members.

Sending a JMS Message

The Send JMS Message command automates the process of sending a message to a queue or topic. The J2EE 1.4 specification defines the concept of a message destination, which provides a way to specify logical destinations for messages. A message destination allows the decoupling of the message consumer and message producer. The most common scenario is to have a message-driven bean (MDB) linked to the message destination. However, the message destination mechanism allows only the logical message destination to be used by the module sending the message. Although this concept defines a generic linking mechanism, additional information, such as the type of destination (the J2EE 1.4 specification allows other messaging systems to be used), and the message format must be exchanged.

If you want to use JMS, you need to do the following:

• Add a resource reference to declare a ConnectionFactory. The connection factory is used to create JMS queue or topic connections.

• Add a message destination reference that declares the message destination type (which must match the type declared for the message destination), the use (the sender will produce messages), and the destination (in the form of a link). The link will be in the format moduleName#destinationName and must be included in the same application.

• Add code to send the message. The code to send a message must do a JNDI lookup to obtain the connection factory, use the connection factory to create a session, use the session to create a message producer, use the session to create a message, send the message, and close the session and connection.

The Send JMS Message command automates this process. To use this command, right-click in the Source Editor and choose Enterprise Resources | Send JMS Message. The Select Message Destination dialog box (shown in Figure 13-23) appears and provides a way to select a message destination and to specify whether a service locator should be used or inline code should be generated (lookup code is generated in the current class). Only projects that can supply a destination are shown in the list of projects (web and EJB Modules).

Figure 13-23. Select Message Destination dialog box

After you complete the Select Message Destination dialog box, the following occurs:

1.	A resource reference is added to the deployment descriptor, specifying the intention to use a ConnectionFactory. The IDE's Sun Java System Application Server integration plug-in module shares the connection factory with the message consumer. This can be changed by creating a new ConnectionFactory, if desired.
2.	A message destination reference is created and linked to the selected destination. The message type is discovered by determining the message type of the consumer linked to the destination.
3.	A private method providing the code necessary to send a single JMS message (named sendJMSDestinationName) is created. This method handles connection, session, and producer creation and destruction. This method accepts a context parameter that allows data to be passed via parameters instead of instance variables, although instance variables can be used as well.
4.	A second private method (createJMSMessageForDestinationName) is added to create the message (this is the template pattern) from the supplied session and potentially the context parameter.