Sun ONE Application Server 7 J2EE CA Service Provider Implementation Administartor's Guide |
Assembling and Deploying the ConnectorThis module 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 module.
This chapter describes the following topics:
- Overview of Assembly and Deployment
- Deploying Modules and Applications
- The Connector Deployment Descriptor Files
- Security Management
- Preparing the .rar File for Deployment
Overview of Assembly and Deployment
Application 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
- J2EE Standard Descriptors
- Sun ONE Application Server Descriptors
- Naming Standards
- Runtime Environments
- Classloaders
- Sample Applications
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:
- Resource RAR File: The RAR files apply only to J2EE CA connectors. Each Sun ONE Application Server connector has a sun-ra.xml file and a J2EE application deployment descriptor ra.xml file.
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:
- Java 2 Enterprise Edition, J2EE Connector Architecture Specification v1.0, 10 "Packaging and Deployment".
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.
- sun-ra.xml
- ra.xml
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
- Create a working directory, and copy the contents of your module into it.
- Create two deployment descriptor files with these names: sun-ra.xml and ra.xml in the META_INF directory.
- Execute this command to create the RAR file:
jar -cvf module_name.rar *
Deploying Modules and Applications
This 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
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:
dynamic-reload-enabled="true" enables dynamic reloading.
dynamic-reload-poll-interval-in-seconds sets the interval at which applications and modules are checked for code changes and dynamically reloaded.
For details about server.xml, see the Sun ONE Application Server Administrator's Configuration File Reference.
In addition, to load new servlet files, reload EJB related changes, or reload deployment descriptor changes, you must do the following:
- Create an empty file named .reload at the root of the deployed application:
instance_dir/applications/j2ee-apps/app_name/.reload
or individually deployed module:
instance_dir/applications/j2ee-modules/module_name/.reload
- Explicitly update the .reload file's timestamp (touch .reload in Unix) each time you make the above changes.
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
- Open the Applications component under your server domain.
- Go to the Connector Modules page.
- Click on the Deploy button.
- Enter the following information
File path - The file path for the connector module .rar file.
- Click OK.
- Enter the connector name. Click OK
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 Management
Connectors 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
- configured identity
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 Files
Sun ONE Application Server connectors include two deployment descriptor files:
- A J2EE standard file (ra.xml), described in the Java 2 Enterprise Edition, J2EE Connector Architecture Specification v1.0, Chapter 10 "Packaging and Deployment".
- A Sun ONE Application Server specific file (sun-ra.xml), described in this section.
This section covers the following topics:
- sun-connector_1_0-0.dtd
- Elements in the sun-ra.xml File
- Sample Application XML FIles
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
- resource-adapter
- role-map
- map-element
- principal
- backend-principal
- description
- property
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.
   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.
   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.
   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.
   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.
   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.
   principal subelements
Element
Default
Description
description
Describes the principal
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.
   prinicpal attributes
Attribute
Default
Description
user-name
Contains the user name.
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 Deployment
The .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:
- /META-INF/ra.xml
- /META-INF/sun-ra.xml
- /readme.html
- /ra.jar
- /client.jar
- /win.dll
- /solaris.so
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.