5 Using TopLink with JBoss 7 Application Server

This chapter describes how to use Oracle TopLink as the persistence provider for applications deployed to JBoss Application Server 7.1.

This chapter contains the following sections:

Use Case

TopLink can be used with a number of popular Java EE application servers, including JBoss Application Server.

Solution

Configure JBoss to use EclipseLink runtime, and deploy applications developed using EclipseLink APIs.

Components

5.1 Introduction to the Solution

JBoss Application Server implements the Java Platform, Enterprise Edition (Java EE). JBoss 7 fully supports Java EE 6, while JBoss 6 officially supports only the Java EE 6 Web Profile.

By configuring JBoss to support EclipseLink, you can take advantage of EclipseLink's full support for Java Persistence API (JPA), Java Architecture for XML Binding (JAXB), including EclipseLink's extensions to those technologies, as well as EclipseLink Database Web Services (DBWS) to access to relational database artifacts via a Web service.

5.2 Implementing the Solution

To develop, deploy and run EclipseLink applications in JBoss Application Server 7, you must create EclipseLink as a module of JBoss. You must also create other modules, such as a JDBC driver, etc., in order to run applications.

This section contains the following tasks for using EclipseLink with JBoss 7.1:

5.2.1 Task 1: Prerequisites

Ensure that you have installed the following components:

5.2.2 Task 2: Configure EclipseLink as a Module in JBoss

To configure EclipseLink as a module in JBoss:

  1. Create a directory as follows:

    JBOSS_ HOME\modules\org\eclipse\persistence\main

  2. Copy eclipselink.jar to the directory created in step 1. (The eclipselink.jar file is located in the oracle_common\modules\oracle.toplink_ver_no directory created by the TopLink quick installer.)

  3. Create a module.xml file in the directory created in step 1, with the following content:

    <module xmlns="urn:jboss:module:1.1" name="org.eclipse.persistence">
       <resources>
           <resource-root path="eclipselink.jar"/>
           <!-- Insert resources here -->
       </resources>
       <dependencies>
          <module name="javax.api"/>
          <module name="javax.persistence.api"/>
          <module name="javax.transaction.api"/>
          <module name="javax.validation.api"/>
          <module name="javax.xml.bind.api"/>
          <module name="org.antlr"/>
          <module name="org.apache.commons.collections"/>
          <module name="org.dom4j"/>
          <module name="org.javassist"/>
          <module name="org.jboss.logging"/>
          <module name="com.oracle.ojdbc6"/>
       </dependencies>
    </module>
    

5.2.3 Task 3: Add ojdbc6.jar as a Module in JBoss

Add the Oracle thin driver ojdbc6.jar as a module within JBoss, as follows:

  1. Create the module directory:

    JBOSS_ HOME\modules\com\oracle\ojdbc6\main

  2. Copy ojdbc6.jar to the module directory created in step 1.

  3. Create a module.xml file in the module directory created in step 1, with the following contents:

    <module xmlns="urn:jboss:module:1.1" name="com.oracle.ojdbc6">
        <resources>
            <resource-root path="ojdbc6.jar"/>
            <!-- Insert resources here -->
        </resources>
        <dependencies>
            <module name="javax.api"/>
        </dependencies>
    </module>
    

5.2.4 Task 4: Create the Driver Definition and the Datasource

Create the driver definition and create the data source.

The following instructions tell how to configure JBoss for running in standalone mode, using the standalone.xml configuration file. For instructions on how to use domain.xml to configure JBoss for running in domain mode, see the JBoss documentation.

  1. In the standalone configuration file JBOSS_ HOME\standalone\configuration\standalone.xml, find the following:

    <subsystem xmlns="urn:jboss:domain:datasources:1.0">

  2. In that section, configure the data source. The following example shows a configuration for the Oracle Database, using the Oracle JDBC Thin driver. For instructions on configuring other data sources, see the JBoss documentation.

<subsystem xmlns="urn:jboss:domain:datasources:1.0">
   <datasources>
      <datasource jndi-name="java:/EclipseLinkDS" 
            pool-name="EclipseLinkDS" 
            enabled="true" 
            jta="true" 
            use-java-context="true" 
            use-ccm="true">
         <connection-url>jdbc:oracle:thin:node_name.example.com:1521:TOPLINK</connection-url>
         <driver>oracle</driver>
         <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
         <pool>
            <prefill>true</prefill>
            <use-strict-min>false</use-strict-min>
            <flush-strategy>FailingConnectionOnly</flush-strategy>
         </pool>
         <security>
            <user-name>Smith</user-name>
            <password>password</password>
         </security>
       </datasource>
       <driver name="oracle" module="com.oracle.ojdbc6">
         <xa-datasource-class>oracle.jdbc.OracleDriver</xa-datasource-class>
       </driver>
    </datasources>
</subsystem>

5.2.5 Task 5: Create Users

Starting with JBoss Application Server 7.1, you must create an Application User to get started, because remote access to the JNDI tree is secured by default, and you must provide login credentials. Therefore, at a minimum, you just create an Application User to be able to deploy an application to the server. If you want to use the JBoss administration console for administration tasks, for example to view the JNDI tree, you must also create an Administration User.

To create user credentials, use the JBoss add-user.bat utility, located in JBOSS_HOME\bin\.

For more information about security in JBoss Application Server, refer to the JBoss documentation.

5.2.6 Task 6: Modify JBoss Properties

Modify JBoss properties, as follows:

## JBoss-7.x
server.factory=org.jboss.naming.remote.client.InitialContextFactory
java.naming.factory.url.pkgs=org.jboss.ejb.client.naming
server.depend=jboss-client.jar
jboss.server=${jboss.home}/standalone
server.lib=${jboss.home}/bin/client
server.url=remote://localhost:4447
server.user=usera
server.pwd=passworda
jboss.naming.client.ejb.context=true

5.2.7 Task 7: Other Requirements

  1. Add junit.jar in the ear under the \lib directory.

  2. Because of a classloading issue in JBoss, you must list all your entity classes in persistence.xml. You can use either <class> elements or a global <exclude-unlisted-classes>false</exclude-unlisted-classes> element.

  3. Add both jndi.properties and jboss-ejb-client.properties in the client classpath.

5.2.8 Task 8: Start JBoss

Start JBoss by running standalone.bat (for a single-server configuration) or domain.bat file (in a clustered environment) in JBOSS_ HOME\bin\.

For information on different ways to configure and start JBoss, see the JBoss documentation.

5.3 Additional Resources

See the following resources for more information about the technologies and tools used to implement the solutions in this chapter: