| Sun ONE Application Server 7 J2EE CA Service Provider Implementation Administrator's Guide |
Chapter 2
Assembling and Deploying the ConnectorThis chapter describes the contents of the Sun ONE Application Server connector module and how this module is assembled separately or together in an application.
The Sun ONE Application Server connector module includes J2EE standard elements and Sun ONE Application Server specific elements. Only Sun ONE Application Server specific elements are described in detail in this chapter.
This chapter describes the following topics:
Overview of Assembly and DeploymentApplication assembly (also known as packaging) is the process of combining discrete components of an application into a single unit that can be deployed to a J2EE-compliant application server. A package can be classified either as a module or as a full-fledged application. This section covers the following topics:
Modules
A J2EE module is a collection of one or more J2EE components of the same container type with two deployment descriptors of that type. One descriptor is J2EE standard, the other is Sun ONE Application Server specific. The Connector Module can be described as follows:
Package definitions must be used in the source code of all modules so the classloader can properly locate the classes after the modules have been deployed.
Because the information in a deployment descriptor is declarative, it can be changed without requiring modifications to source code. At run time, the J2EE server reads this information and acts accordingly.
The connector module has a Sun ONE Application Server deployment descriptor and a J2EE deployment descriptor. The Sun ONE Application Server Administration interface uses the deployment descriptors to deploy the application components and to register the resources with the Sun ONE Application Server.
An application consists of one or more modules, a Sun ONE Application Server deployment descriptor, and a J2EE application deployment descriptor. All modules are assembled, using the Java ARchive (.jar) file format, into one file with an extension of .ear.
J2EE Standard Descriptors
The J2EE platform provides assembly and deployment facilities. These facilities use JAR files as the standard package for components and applications, and XML-based deployment descriptors for customizing parameters.
The J2EE standard deployment descriptors are described in the J2EE specification, v1.3. For more information on J2EE standard deployment descriptors, see the following specifications:
You can find specifications at the following URL:
Sun ONE Application Server Descriptors
Sun ONE Application Server uses additional deployment descriptors for configuring features specific to the Sun ONE Application Server.
Note
The Sun ONE Application Server deployment descriptors must have 600 level access privileges on Unix systems.
The DTD schema files for all the Sun ONE Application Server deployment descriptors are located in the install_dir/lib/dtds directory.
Naming Standards
Names of deployed connector RAR modules must be unique in the Sun ONE Application Server. Using a Java package-like naming scheme is recommended for module filenames. The use of this package-like naming scheme ensures that name collisions do not occur. The benefits of this naming practice apply not only to the Sun ONE Application Server, but to other J2EE application servers as well.
Runtime Environments
Whether you deploy a component as a stand-alone module or as an application, deployment affects both the file system and the server configuration. See the "Sun ONE Application Server J2EE CA SPI Developer’s Guide" for more information.
Classloaders
In a Java Virtual Machine (JVM), the classloaders dynamically load a specific java class file needed for resolving a dependency. For example, when an instance of java.util.Enumeration needs to be created, one of the classloaders loads the relevant class into the environment. See the "Sun ONE Application Server J2EE CA SPI Developer’s Guide" for more information.
Sample Applications
Sample applications that you can examine and deploy are included in Sun ONE Application Server, in the install_dir/samples/j2ee directory. Each sample has its own documentation.
Selects component files that match specified parameters. When fileset is included as a subelement, the name and contextroot attributes of the containing element must use their default values for each file in the fileset. For more information, see:
http://jakarta.apache.org/ant/manual/CoreTypes/fileset.html
Assembling a J2EE CA Resource Adapter
This section provides some brief pointers for assembling J2EE CA resource adapters.
The following two XML connector files are required for deploying a connector to the application server.
The ra.xml file is based on the J2EE CA specification and is packaged with the connector. The sun-ra.xml file contains Sun ONE Application Server specific information.
To assemble a connector RAR module
Deploying Modules and ApplicationsThis section describes the way to deploy J2EE connector module to the Sun ONE Application Server.
Deployment IDs and Errors
A unique ID is generated in the server.xml file when you deploy an application or module. Do not change this ID. During deployment, the server detects any ID collisions and does not load an application or module having a non-unique ID. Messages are logged in the server log when this happens.
If an error occurs during deployment, the application or module is not deployed. If a module within an application contains an error, the entire application is not deployed.
For details about server.xml, see the Sun ONE Application Server Administrator’s Configuration File Reference.
The Deployment Life Cycle
After an application is initially deployed, it may be modified and reloaded, redeployed, disabled, re-enabled, and finally undeployed (removed from the server). This section covers the following topics related to the deployment life cycle:
Dynamic Deployment
You can deploy, redeploy, and undeploy an application or module without restarting the server. This is called dynamic deployment.
When an application or module is redeployed, some file system content and some Application Server settings are not overwritten or removed. This can lead to older settings remaining in effect after a redeployment. To perform a clean redeployment, undeploy the application or module before redeploying it. In addition, whenever a redeployment is done, the sessions at that transit time become invalid. The client must restart the session.
Disabling a Resource Adapter
You can disable a deployed resource adapter without removing it from the server. Each application and module has an enabled attribute in the server.xml file and a corresponding option in the Administration interface, which you can change. For details about server.xml, see the Sun ONE Application Server Administrator’s Configuration File Reference.
Dynamic Reloading
If dynamic reloading is enabled, you do not have to redeploy an application or module when you change its code. All you have to do is copy the changed class files into the deployment directory for the application or module. The server checks for changes periodically and redeploys the application, automatically and dynamically, with the changes.
This is useful in a development environment, because it allows code changes to be tested quickly. Dynamic reloading is not recommended for a production environment, however, because it may degrade performance. In addition, whenever a reload is done, the sessions at that transit time become invalid. The client must restart the session.
The deployment descriptor files in the application are not reloaded automatically. If you change them, you must redeploy the application.
To enable dynamic reloading, you can do one of the following:
- Use the Administration Tool interface:
- Open the Applications component under your server instance
- Go to the Applications page
- Check the Reload Enabled box to enable dynamic reloading.
- Enter a number of seconds in the Reload Poll Interval field to set the interval at which applications and modules are checked for code changes and dynamically reloaded.
- Click on the Save button.
- Edit the following attributes of the server.xml file’s applications element:
In addition, to load new servlet files, reload EJB related changes, or reload deployment descriptor changes, you must do the following:
For JSPs, changes are reloaded automatically at a frequency set in the reload-interval property of the jsp-config element in the sun-web.xml file. To disable dynamic reloading of JSPs, set reload-interval="-1".
Deploying a J2EE CA Resource Adapter
You can deploy a connector module using the following tools:
asadmin deploy
The asadmin deploy command deploys a RAR file. To deploy a stand-alone connector module, specify --type connector.The following command deploys a RAR stand-alone module:
asadmin deploy -- connector--instance inst1 -name connector_name rar filename
To undeploy a connector module, use this command:
asadmin undeploy -- connector--instance inst1 -name connector_name
The Administration Interface
You can also use the Administration interface to deploy a connector module.
To Deploy a Connector Module
Access to Shared Frameworks
When J2EE applications and modules use shared framework classes (such as components and libraries) the classes can be put in the path for the System Classloader or the Common Classloader rather than in an application or module. If you assemble a large, shared library into every module that uses it, the result is a huge file that takes too long to register with the server. In addition, several versions of the same class could exist in different classloaders, which is a waste of resources.
For more information about the system classloader, see "Classloaders".
Security ManagementConnectors are integrated in the overall J2EE security scheme. However, because the EIS usually has its own security system, a mechanism is required to map J2EE security principal to EIS principals. The J2EE SPI supports the following two mechanisms:
Principal Mapping
Principal mapping sets up the mapping between J2EE principals EIS principals. The sun-ra.xml contains this mapping. For a description and sample see "Elements in the sun-ra.xml File"
Configured Identity
The configured identity mechanism allows you to set up and use a single user id to login to the backend for all J2EE principals.
J2EE CA currently supports password authentication.
The Connector Deployment Descriptor FilesSun ONE Application Server connectors include two deployment descriptor files:
This section covers the following topics:
The sun-connector_1_0-0.dtd
The sun-connector_1_0-0.dtd file defines the various elements that the sun-ra.xml file can contain and the subelements and attributes these elements can have. The sun-connector_1_0-0.dtd file is located in the install_dir/lib/dtds directory.
Note
Do not edit the sun-connector_1_0-0.dtd file. Its contents change only with new versions of Sun ONE Application Server.
For general information about DTD files and XML, see the XML specification at:
Each element in a DTD file (and the XML file for which it specifies the schema) can contain the following:
Subelements
Elements can contain subelements. For example, the following code defines the sun-connector element.
<!ELEMENT sun-connector (resource-adapter, role-map?)>
The ELEMENT line specifies that a sun-connector element can contain (resource-adapter, role-map?) subelements.
The following table shows how the ending characters of the subelements determine the requirement rules for the subelements. The left column lists the subelement ending character, and the right column lists the corresponding requirement rule.
If an element cannot contain other elements, you see EMPTY or (#PCDATA) instead of a list of element names in parentheses.
Data
Some elements contain data instead of subelements. These elements have definitions of the following format:
<!ELEMENT element-name (#PCDATA)>
For example:
<!ELEMENT description (#PCDATA)>
In the sun-ra.xml file, white space is treated as part of the data in a data element. Therefore, there should be no extra white space before or after the data delimited by a data element. For example:
<principal user-name="keren"></principal>
The following conventions apply to all J2EE deployment descriptor elements unless indicated otherwise.
In elements that contain PCDATA, leading and trailing white space in the data may be ignored.
In elements whose value is an "enumerated type", the value is case sensitive.
In elements that specify a pathname to a file within the same JAR file, relative filenames (i.e., those not starting with "/") are considered relative to the root of the JAR file's namespace. Absolute filenames (i.e., those starting with "/") also specify names in the root of the JAR file's namespace. In general, relative names are preferred. The exception is .war files where absolute names are preferred for consistency with the servlet API.
Attributes
Elements that have ATTLIST lines contain attributes.
Elements in the sun-ra.xml File
This section describes the following XML elements in the sun-connector_1_0-0.dtd sun-ra.xml files:
sun-connector
Defines Sun ONE Application Server specific sun-connector element and is the root element of the deployment descriptor for the resource adapter; there can only be one sun-connector element in a sun-ra.xml file.
Subelements
The following table describes subelements for the sun-connector element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-2 sun-connector subelements
Element
Required
Description
resource-adapter
consists of the jndi-name and pooling configuration attributes
role-map
contains security mapping information
resource-adapter
Defines the pool sizing and JNDI - lookup name.
Attributes
The following table describes attributes for the resource-adapter element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes the attribute.
Subelements
The following table describes subelements for the resource-adapter element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-4 resource-adpater subelements
Element
Required
Description
description
Describes the resource adapter
property
Defines the syntax for supplying properties as name value pairs.
description
Describes the resource adapter.
Subelements
None
property
Defines the syntax for supplying properties as name value pairs.
Subelements
None
Attributes
The following table describes attributes for the property element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes the attribute.
Table 2-5 property attributes
Attribute
Default
Description
name
Name of the property
value
Contains the value of the property.
role-map
Defines the mapping from the principal received during Servlet/EJB authentication, to credentials accepted by the EIS. This mapping is optional. The map consists of several 2-tuples.
Subelements
The following table describes subelements for the role-map element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
role map subelements
Element
Default
Description
description
Describes the backend that you are mapping to.
map-element
Describes the mapping from the principal to the backend principal.
Attributes
The following table describes attributes for the role-map element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes the attribute.
Table 2-6 role-map attributes
Attribute
Default
Description
map-id
Describes the ID for the mapping.
map-element
Defines the map-element. It is possible to map multiple (server) principal to the same backend principal.
Subelements
The following table describes subelements for the map-elementelement. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 2-7 map-element subelements
Element
Default
Description
principal
Principal of the Servlet and EJB client
backend-principal
Backend principal of the EIS.
principal
Defines the principal of the Servlet and EJB client.
Subelements
The following table describes subelements for the prinicpal element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Attribute
The following table describes attributes for the principal element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes the attribute.
backend-principal
Defines the backend EIS principal.
Subelements
None
Attributes
The following table describes attributes for the backend-principal element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes the attribute.
backend-prinicpal attributes
Attribute
Default
Description
user-name
Contains the backend user name.
password
Contains the backend password.
credential
Contains the type of credential.
description
Defines the resource adapter.
Subelements
None
Sample Application XML FIles
The sun-ra.xml file needs to be customized to deploy it. Code Example provides an example of the code and a description of each parameter and item that needs to be customized.
This section includes the following:
Sample sun-ra.xml File
The following is a code example of the sun-ra.xml file
<?xml version="1.0" encoding="UTF-8"?>
<!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>
Sample ra.xml File
The following is an example of a sample 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>sun</vendor-name>
<spec-version>1.0</spec-version>
<eis-type>Comet</eis-type>
<version>1.0</version>
<resourceadapter>
<managedconnectionfactory-class>samples.connectors.simple.CometMana gedConnectionFactory</managedconnectionfactory-class>
<connectionfactory-interface>javax.resource.cci.ConnectionFactory</ connectionfactory-interface>
<connectionfactory-impl-class>samples.connectors.simple.CometConnec tionFactory</connectionfactory-impl-class>
<connection-interface>javax.resource.cci.Connection</connection-int erface>
<connection-impl-class>samples.connectors.simple.CometConnection</c onnection-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-mechan ism-type>
<credential-interface>javax.resource.security.PasswordCredential</c redential-interface>
</authentication-mechanism>
<reauthentication-support>false</reauthentication-support>
</resourceadapter>
</connector>
Preparing the .rar File for DeploymentThe .rar file must contain the following:
- A deployment descriptor file that contains standard deployment information that is defined in the connector_1-0.dtd file.
The deployment descriptor must be stored with the name META-INF/ra.xml in the .rar file.
- The Sun ONE Application Server connector sun-ra.xml file that specifies additional Application Server specific deployment information.
The sun-ra.xml must be stored with the name META-INF/sun-ra.xml in the .rar file.
- The Java interfaces, implementation and utility classes, required by the resource adapter should be packaged as one or more .jar files as part of the resource adapter module.
- The platform-dependent libraries required by the resource adapter should also be packaged with the resource adapter module.
Directory Structure for the .rar File
The following illustrates a listing of files in a sample resource adapter module:
In the above example, ra.xml is the deployment descriptor, sun-ra.xml is the Sun specific deployment descriptor. The ra.jar and client.jar contain Java interfaces and implementation classes for the resource adapter. The win.dll and solaris. so are examples of native libraries.
