JPPF And J2EE

From JPPF Documentation

Jump to: navigation, search

Contents

Main Page > JPPF And J2EE

Overview of the JPPF Resource Adapter

What is it?

The JPPF Resource Adapter is a JCA-compliant resource adapter module that encapsulates a JPPF client.
It provides J2EE application servers with an access to JPPF grid services.
It is intended for deployment as either a standalone module or embedded within an enterprise application, while preserving the ease of use of JPPF.

Features

  • Supports a pool of connections to a single JPPF driver
  • Supports disconnection from, and reconnection to, a JPPF driver
  • Compliant with the JCA 1.5 specifications
  • API similar to that of the standard JPPF client (submit(tasks, dataProvider))
  • No transaction support

Architecture

JPPF-J2EE.gif

Supported Platforms



Note: we have not tested all versions of all platforms, thus it is possible that the integration, with the version of the application server you are using, may not work out-of-the-box. We hope that the existing framework and instructions will allow you to adapt the build scripts and code to do so. If you have issues with a specific port, or if you wish to report one that is not specified in this documentation, we invite you to provide your feedback and comments on the JPPF Forums



Technology Tested Platforms
Operating System All Windows systems supporting JDK 1.5 or later
All Linux and Unix systems supporting JDK 1.5 or later
JDK Sun JDK 1.5 and later
IBM JVM 1.5 and later
BEA JRockit 1.5 and later
Application Server JBoss 4.0.x and 4.2.x
Oracle OC4J 10.1.3.x
Sun AS 9.0.x
IBM Websphere Application Server 6.1.x
BEA Weblogic 9.2.

Configuration and build

Requirement

For building, configuring and customizing the JPPF Resource Adapter, your will need the latest version of the JPPF source code distribution. It can be found on the JPPF download page. The name of the file should be jppf-full-src-x.y.z.bbbb-yyyymmdd.zip

Build structure

The JPPF resource adapter is contained in the "jca-client" folder of the JPPF source distribution. This folder has the following structure:

Folder Description
jca-client (root) The root folder, contains the build.xml Ant build script
appserver contains common and application server-specific configurations for the JPPF resource adapter and the demo application
build this folder contains all jars, .ear and .rar files resulting from the build
classes contains the compiled code of the JPPF resource adapter
config contains application server-specific resources for the deployment of the resource adapter
docroot contains resources for the build of the demo application on some application servers
src contains the source code for the resource adapter and demo application.


Building the JPPF resource adapter

To build the resource adapter:

  • Open a command prompt
  • Go to the folder "jca-client" of the JPPF source distribution
  • Enter "ant build"
  • The resulting .rar and .ear files are generated in the "build" subfolder.


Configuring the resource adapter and demo application

The configuration files and deployment descriptors are all contained in the appserver folder. The detailed content of this folder is as follows:

Folder Description
appserver root folder, contains:
  • the resource adapter's deployment descriptor ra.xml. It is in this file that you set the configuration parameters for the connection to the JPPF driver, by setting the values of the following configuration properties:
    • ServerHost: Host name or IP address of the JPPF driver
    • ClassServerPort: Port on which to connect for the JPPF driver class loader
    • AppServerPort: Port on which to connect to submit tasks to the JPPF driver
    • ConnectionPoolSize: Number of connections to the JPPF driver
  • the demo application's deployment desciptor application.xml
appserver/common contains files common to all application servers, for the demo enterprise application
appserver/<server_name> root of <server_name>-specific configuration and deployment files. Contains a commons-logging.properties file where you can configure which logging framework will be used (i.e. Log4j, JDK logger, etc...)
appserver/<server_name>/application contains <server_name>-specific deployment descriptor for the demo application, for example: weblogic-application.xml.
appserver/<server_name>/docroot contains a <server_name>-specific JSP for the demo application. The specificity is the JNDI name used to look up the JPPF connection factory. It relates to the corresponding resource-ref defined in the web.xml descriptor.
appserver/<server_name>/ra contains a <server_name>-specific deployment descriptor for the resource adapter. It generally contains the definition of the corresponding JCA connection factory. Not all application servers require one. Example: weblogic-ra.xml.
appserver/<server_name>/WEB-INF contains the <server_name>-specific deployment descriptors for the demo web application. The specificity is mostly in the resource-ref definition of the JNDI name ofr the JPPF connection factory. For example: web.xml and jboss-web.xml.

How to use the connector API

To use the JPPF Resource Adapter from your code, follow these steps:

Submitting the tasks

Example:

 //Perform a JNDI lookup of the JPPF connection factory
 InitialContext ctx = new InitialContext();
 Object objref = ctx.lookup("eis/JPPFConnectionFactory");
 ConnectionFactory factory = 
   (ConnectionFactory) PortableRemoteObject.narrow(objref, ConnectionFactory.class);
 //Obtain a JPPF Connection from the connection factory
 JPPFConnection connection = (JPPFConnection) factory.getConnection();
 //Use the connection to submit your JPPF tasks
 List<JPPFTask> tasks = new ArrayList<JPPFTask>();
 tasks.add(new DemoTask());
 //Use the connection to submit your JPPF tasks
 //And obtain a submission ID
 String submitID = connection.submitNonBlocking(tasks, null);
 //close the connection
 connection.close();


Checking the status and obtaining the results

Example:

 //Perform a JNDI lookup of the JPPF connection factory
 InitialContext ctx = new InitialContext();
 Object objref = ctx.lookup("eis/JPPFConnectionFactory");
 ConnectionFactory factory =
   (ConnectionFactory) PortableRemoteObject.narrow(objref, ConnectionFactory.class);
 //Obtain a JPPF Connection from the connection factory
 JPPFConnection connection = (JPPFConnection) factory.getConnection();
 //
 JPPFSubmissionResult.Status status = connection.getSubmissionStatus(submitID);
 //Use the connection to check the status from the submission ID
 if (status.equals(JPPFSubmissionResult.Status.COMPLETE))
 {
   //if successful process the results
   List<JPPFTask> results = connection.getSubmissionResults(submitID);
 }
 else if (status.equals(JPPFSubmissionResult.Status.FAILED))
 {
   //if failed process the errors
 }
 //close the connection
 connection.close();

Using submission status events

Example:

 JPPFConnection connection = getConnection();
 JPPFTask task = new DurationTask(duration);
 List list = new ArrayList();
 list.add(task);
 
 // A status listener can be added at submission time
 // using another form of the method JPPFConnection.submitNonBlocking()
 String id = connection.submitNonBlocking(list, null, new SubmissionStatusListener()
 {
   public void submissionStatusChanged(SubmissionStatusEvent event)
   {
     String id = event.getSubmissionId();
     SubmissionStatus status = event.getStatus();
     System.out.println("submission [" + id + "] changed to '" + status + "'");
   }
 });
 
 // or after the tasks have been submitted
 connection.addSubmissionStatusListener(id, new SubmissionStatusListener()
 {
   public void submissionStatusChanged(SubmissionStatusEvent event)
   {
     String id = event.getSubmissionId();
     SubmissionStatus status = event.getStatus();
     switch(status)
     {
       case COMPLETE:
         // process successfull completion
         break;
       case FAILED:
         // process failure
         break;
       default:
         System.out.println("submission [" + id + "] changed to '" + status + "'");
         break;
     }
   }
 });
 
 connection.close();

Submitting with an execution policy

The JPPFConnection API also enables providing an Execution Policy when submitting JPPF tasks, thanks to the following methods:

Example:

 connection = getConnection();
 List list = new ArrayList();
 list.add(new MyTask());
 // parse an execution policy file found in the classpath
 ExecutionPolicy policy =
   PolicyParser.parsePolicy("com/my/package/ExecutionPolicy.xml");
 // submit with the execution policy
 String id = connection.submitNonBlocking(policy, list, null);

Deployment on a J2EE application server

Packaging your enterprise application new.gif

For a J2EE enterprise application to work with the JPPF JCA connector, it is necessary to include a JPPF utility library called jppf-j2ee-client.jar, which can be found in the jca-client/build/lib folder. To ensure that this library can be made visible to all modules in the application, we recommend the following way of packaging it:

  • add jppf-j2ee-client.jar in a lib folder under the root of the EAR file
  • for each EJB, Web or Resource Adapter module of your application that will use JPPF, add a Class-Path entry in the META-INF/manifest.mf of the module, which will point to the JPPF library, for instance:
 Class-Path: lib/jppf-j2ee-client.jar

In a typical J2EE application, it would look like this:

 MyApplication.ear/
 
     lib/
         jppf-j2ee-client.jar
     
     MyEJBModule.jar/
         ...
         META-INF/
             manifest.mf:
                 ...
                 Class-Path: lib/jppf-j2ee-client.jar
                 ...
         ...
 
     ... other modules ...
 
     MyWebApp.war/
         ...
         META-INF/
             manifest.mf:
                 ...
                 Class-Path: lib/jppf-j2ee-client.jar
                 ...
         ...

Note: If you only need to use JPPF from a web application or module, then you can simply add jppf-j2ee-client.jar to the WEB-INF/lib folder of the war file.

Creating an application server port

If the JPPF resource adapter does not include, out-of-the-box, a port for your application server, or your application server version, this section is for you.
Here is a sequence of steps to create your own port:

1. copy one of the existing application server-specific folder in jca-client/appserver and give it a name that will distinguish it from the others. This name will be used throughout this process, so please make sure it is both unique and meaningful. For the sake of this exercise, we will use a generic name: "MyServer-1.0"

2. After creating the jca-client/appserver/MyServer-1.0 folder, edit the relevant configuration files and deployment descriptors.

3. Open the build.xml build script, in the jca-client folder, with a text editor.

4. At the start of the file, you will see the following section:

 <!-- ========================================================================= -->
 <!-- definition of application server-specific properties                      -->
 <!-- the value is used to generate the names of the corresponding EAR and RAR  -->
 <!-- ========================================================================= -->
 <property name="was61"           value="WAS-6.1"/>
 <property name="jboss40"         value="JBoss-4.0"/>
 <property name="oracle10"        value="Oracle-10"/>
 <property name="sunas90"         value="SunAS-9.0"/>
 <property name="weblogic92"      value="Weblogic-9.2"/>

You can add your own property here, for instance:

 <property name="myserver10"      value="MyServer-1.0"/>

5. (optional) navigate to the Ant target "ear.all" and add your own invocation for generating the demo application EAR:

 <antcall target="ear">
   <param name="appserver" value="${myserver10}"/>
   <param name="include.client.classes" value="true"/>
 </antcall>

You may also remove or comment out those you do not need.

6. Navigate to the Ant target "ear.all" and add your own invocation for generating the resource adapter RAR:

 <antcall target="rar"><param name="appserver" value="${myserver10}"/></antcall>

You may also remove or comment out those you do not need.


Support This Project Powered by MediaWiki