Sun ONE logo     
Java TM Connector Architecture Sample Application



Simple Connector Sample Application


This document describes how to utilize the Java TM Connector Architecture sample application in conjunction with Sun ONE Application Server version 7.

This sample application document contains the following sections:



Overview

The Comet Sample Connector can be used to illustrate how a J2EE CA compliant connector can be deployed and then operate with a J2EE CA compliant application server. The sample contains the following components:

The Sample J2EE Connector

The comet.rar file contains the sample connector files that are archived into a .rar file according to the connector architecture specification. The file is located in [appserver installation directory]/samples/connectors/simple/comet.rar.

The following describes the files in the Comet Connector Sample:

comet.jar

The comet.jar file contains the Java interfaces, implemetation and utility classes, required by the resource adapter and the error messages file. The filename is samples.connectors.simple.Messages.properties. The messages file may be modified to comply with the internationalization standards (I18N).

META-INF/ra.xml

The Comet Sample ra.xml file contains the Host and Port configuration properties.
Their values are set to:
Host: localhost
Port: 8020
These values may be modified before deployment.

Code Example 4-1 displays the sample ra.xml file.


Code Example 4-1    ra.xml file
<?xml version="1.0" encoding="UTF-8"?>

<!--
   Copyright 2002 Sun Microsystems, Inc. All rights reserved.
 -->

<!DOCTYPE connector PUBLIC '-//Sun Microsystems, Inc.//DTD Connector 1.0//EN'
'http://java.sun.com/dtd/connector_1_0.dtd'>

<connector>
    <display-name>CometResourceAdapter</display-name>
    <vendor-name>iPlanet</vendor-name>
    <spec-version>1.0</spec-version>
    <eis-type>Comet</eis-type>
    <version>1.0</version>
    <resourceadapter>
        <managedconnectionfactory-class>samples.connectors.simple.CometManagedConnectionFactory</managedconnectionfactory-class>
        <connectionfactory-interface>javax.resource.cci.ConnectionFactory</connectionfactory-interface>
        <connectionfactory-impl-class> samples.connectors.simple.CometConnectionFactory</connectionfactory-impl-class>
        <connection-interface>javax.resource.cci.Connection</connection-interface>
        <connection-impl-class>samples .connectors.simple.CometConnection</connection-impl-class>
        <transaction-support>NoTransaction</transaction-support>
        <config-property>
            <config-property-name>Host</config-property-name>
            <config-property-type>java.lang.String</config-property-type>
            <config-property-value>localhost</config-property-value>
        </config-property>
        <config-property>
            <config-property-name>Port</config-property-name>
            <config-property-type>java.lang.String</config-property-type>
            <config-property-value>8020</config-property-value>
        </config-property>

        <authentication-mechanism>
            <authentication-mechanism-type>BasicPassword</authentication-mechanism-type>
            <credential-interface>javax.resource.security.PasswordCredential</credential-interface>
        </authentication-mechanism>
        <reauthentication-support>false</reauthentication-support>
    </resourceadapter>
</connector>
 

META-INF/sun-ra.xml

The sun-ra.xml contains additional deployment information as follows:

Pooling Configuration

Pool sizing consists of the following pool configuration attributes:

max-pool-size: maximum size of connections to EIS.

steady-pool-size: initial and minimum number of connections to be maintained.

max-wait-in-millis: if a connection is not readily found, the caller will have to wait this long, before a connection is created. A value of 0 implies, immediately request another connection without waiting. If the pool is completely utilized and the timer expires, an exception will be delivered to the application.

idle-timeout-in-seconds: The maximum time that a connection is in the pool until it is destroyed. There is a timer thread that periodically removed unused connections.

Security Role Map

The security role map attributes are used to perform mapping from the principal received during Servlet/EJB authentication, to credentials accepted by the EIS.

It is possible to map multiple principals to the same backend principal.

The role-map element consists of the map-id and the map-element. The map-id attribute is the name of the mapping. The map-element element consists of the principal and the backend-principal. The principal element consists of the user-name attribute. The backend-principal element consists of user-name, password and credential attributes.

JNDI Name

In addition to the pooling configuration attributes, the jndi-name attribute is included in the resource adapter element . The jndi-name is the name by which, this resource adapter will appear in JNDI namespace.



Code Example 4-2 displays the sample sun-ra.xml file.


Code Example 4-2    Sample sun_ra.xml file
<?xml version="1.0" encoding="UTF-8"?>

<!--
   Copyright 2002 Sun Microsystems, Inc. All rights reserved.
 -->

<!DOCTYPE sun-connector PUBLIC "-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7.0 Connector 1.0//EN" "http://www.sun.com/software/sunone/appserver/dtds/sun-connector_1_0-0.dtd">
<sun-connector>
    <resource-adapter jndi-name="Comet" max-pool-size="20" steady-pool-size="10"
 max-wait-time-in-millis="300000" idle-timeout-in-seconds="5000">
    </resource-adapter>
    <role-map map-id="mainframe">
         <map-element>
           <principal user-name="keren"></principal>
             <backend-principal user-name="pazit" password="tulip" credential="credential">
             </backend-principal>
         </map-element>
        </role-map>
  </sun-connector>



The Sample Application

The Comet Sample application operates the Comet connector that sends and recieves messages from a backend system. You need to deploy the sample applicaton and connector before you can use/operate it.

Directory Structure of the Sample Application

src - contains all the source code for sample application
the source code of sample application to be used with connector is under [appserver-install-dir]/samples/connectors /simple/src/comet, it contains deployment descriptor files and java source code with package name samples/comet/ejb
 
assemble - samples/connectors/ simple/assemble