|
| Sun ONE Connector Builder 2.0 Developer's Guide |
Deploying the Resource AdapterThis module describes the following topics:
Deployment Scenarios
There are several options to deploy the Connector Builder generated resource adapters. This section covers those deployment scenarios and the important aspects of each of them.
Deployment in Managed Environment
In this deployment scenario, the resource adapters are deployed onto a J2EE 1.3 compliant Application Server. This secenario has the following features:
- The Application Server provides connection pooling, transaction and security features as part of the SPI implementation which the Connector Builder generated resource adapters utilize at run time.
- Multiple connection factory instances can be configured for a single resource adapter. In this case, the application must use appropriate JNDI lookup names for the configured connection factories.
- Multiple resource adapters built using Connector Builder can be deployed on the same Server.
- The resource Adapters run in the same JVM of the Application Server.
With SOAP over HTTP/S
In addition to the deployment aspects of the adapter in the Managed Environment, SOAP over HTTP/S deployment has the following features:
- The generated SOAP services can be deployed on the Application Server so that the adapter is accessible through SOAP over HTTP/S protocol.
- Provides a loosely-coupled deployment in the managed environment.
- Apache SOAP must be deployed on the Application Server prior to deploying the adapter's SOAP services.
Deployment in Non-Managed Environment
- In this deployment scenario, the resource adapters are deployed onto iPlanet Web Server 6.0 or Planet Application Server 6.5.
- The resource adapters provide built-in connection pooling.
- Application managed local transactions are supported by the adatpers, however, container managed transactions and security features are not available in this mode.
- Multiple connection factory instances can be configured for a single resource adapter. In this case, the application must use appropriate JNDI lookup names for the configured connection factories.
- Multiple resource adapters built using Connector Builder can be deployed on the same Server.
- The resource Adapters run in the same JVM of the Server.
With SOAP over HTTP/S
In addition to the deployment aspects of the adapter in the Non-managed Environment, SOAP over HTTP/S deployment has the following features -
- The generated SOAP services can be deployed on the Server so that the adapter is accessible through SOAP over HTTP/S protocol.
- Provides a loosely-coupled deployment in the non-managed environment.
- Apache SOAP must be deployed on the Server prior to deploying the adapter's SOAP services.
Deploying the Resource Adapters
The resource adapters built using the Sun ONE Connector Builder can be deployed in either managed or non-managed environments as described in J2EE Connector Architecture Version 1.0 specifications. For a managed environment, the application server which is J2EE 1.3 compliant, provides the necessary tools to deploy, administer and monitor the resource adapters. You must use the tools specific to a particular application server to deploy the resource adapters built using Connector Builder into that application server's managed environment. Refer to the application server specific documentation for more details.
For non-managed environments, Connector Builder provides a deployment tool to deploy and configure resource adapters into the iPlanet Application Server 6.5 and the iPlanet Web Server 6.0. The Connector Builder specific deployment tool is installed along with Connector Builder installation.The Deployment Tool is located under the bin directory of Sun ONE Connector Builder installation directory. You must use the Sun ONE Connector Builder specific Deployment Tool when deploying resource adapters into a non-managed environment. The rest of this module describes the details of that process.
Deploying the Resource Adapters in Non-managed Environments
The resource adapters built using Sun ONE Connector Builder can be deployed in non-managed mode on the following platforms:
- iPlanet Application Server 6.5
- iPlanet Web Server 6.0
The tools required to deploy and monitor the resource adapters in this mode are provided by the Sun ONE Connector Builder. These tools are installed as a part of Connector Builder installation. Using Connector Builder deployment tool you can perform the following tasks:
- Deploy a resource adapter (rar file).
- Undeploy a resource adapter.
- List all the deployed resource adapters.
- Deploy SOAP services.
- Configure connection factories for deployed resource adapters.
- List connection factories configured.
- Query the connection factory config parameters.
The following table lists the Deployment Tool Commands. They are located under the bin directory of Connector Builder installation directory. The left column lists the command. The right column lists a description and when the command is used.
The above commands can be executed either from <connector_builder_install_root>\bin directory or from any other directory provided the <connector_builder_install_root>\bin directory is in the PATH environment variable.
Deployment Process for Non-managed Environments
Deploying a resource adapter in non-managed environment consists of the following steps:
- Step 1 - Register Deployment Platform Instance (icsvrreg)
- Step 2 - Deploy Resource Adapter (icradeploy)
- Step 3 - Configure Connection Factory (icconfig)
- Step 4- Deploy SOAP Services (icwsdeploy) - optional
- Step 5- Check the Version of Sun ONE Connector Builder (icversion) - optional
Step 1 - Register Deployment Platform Instance (icsvrreg)
Use the icsvrreg command to register the deployment platform instance with Connector Builder. The registered server is used later with other commands to deploy and configure the resource adapters. Using this command you can perform the following tasks:
- Register a deployment platform instance.
- Unregister a deployment platform instance.
- List registered deployment platform instances.
The syntax of the command is as follows:
icsvrreg <subcommand> [<options>]
icsvrreg add -n <name> -t <type> -d <serverdir>
For complete details about the icsvrreg command, refer to "Command Line Interface Reference".
Examples
The following are examples for usage of icsvrreg:
icsvrreg add -t ias65 -n myias1 -d /test/sun/ias6
icsvrreg add --type iws -n myiws1 --dir d:\sun\server
icsvrreg update -n myiws1 -u http://localhost:8000/soap/servlet/rpcrouter
icsvrreg delete -n myiws1
icsvrreg list
Step 2 - Deploy Resource Adapter (icradeploy)
Use icradeploy command to deploy, undeploy and list deployed resource adapters in non-managed environment.
The syntax of the command is as follows:
icradeploy <subcommand> [<options>]
icradeploy deploy -s <server_name> -a <adapter_name> -r <rar_file>
For complete details about the icradeploy command, refer to "Command Line Interface Reference".
Examples
The following are examples for usage of icradeploy:
icradeploy deploy -s myias1 -a myadapter -r /export/home/myadapter.rar
icradeploy list -s myias1
icradeploy undeploy -s myias1 -a myadapter
icradeploy -h
icradeploy -v
Step 3 - Configure Connection Factory (icconfig)
Use the icconfig command to configure connection factories for deployed resource adapters. You can configure more than one connection factory for a resource adapter. The connection factory or factories must be configured before you start or restart the non-managed environment itself - iAS 6.5 or iWS 6.0.
Using this command you can perform the following tasks:
- Add a connection factory.
- List configured connection factories in a specific deployment instance.
- Update an existing connection factory config parameters.
- Remove an existing connection factory.
- Query the connection factory config parameters.
The syntax of the command is as follows:
icconfig <subcommand> [<options>]
icconfig add -s <server_name> -n <jndi_name> -a <adapter_name>
For complete details about the icconfig command, refer to "Command Line Interface Reference".
Examples
The following are examples for usage of icconfig:
icconfig add -s myias1 -n myadapter -a myadapter
icconfig update -s myias1 -n myadapter -p portnumber=8081
icconfig update -s myias1 -n myadapter -i /export/prop/test.properties
icconfig delete -s myias1 -n myadapter
icconfig list -s myias1
icconfig -h
icconfig -v
Adding a Connection Factory
Use the following command to register/add a connection factory to an already deployed resource adapter.
icconfig add -s <reg_server_name> -n <lookupname> -a <adaptername> -p <propname=propvalue>+
Example:
icconfig add -s myias65 -n COTS -a COTS
The above command adds a connection factory with lookup name COTS for an already deployed resource adapter with name COTS with default configuration and pool parameters as specified in ra.xml and sun-ra.xml files.
Optionally, you can specify different values other than default values specified in deployment descriptor while adding a connection factory using -p option. Here is an example to specify different parameter values while adding a connection factory:
icconfig add -s myias65 -n COTS -a cots -p PortNumber=8888
There is no limit on number of connection factories that can be defined for a deployed resource adapter.
The lookup name must be unique across all deployed resource adapters and is case sensitive.
You must use the configured connection factory lookup name in your client application code to access a deployed resource adapter.
Updating an Existing Connection Factory's Parameters
The query subcommand of icconfig command can be used to view the existing configuration of a connection factory for a deployed resource adapter. Here is an example:
icconfig query -s <reg_server_name> -n COTS
The above command displays the current values of the connection factory's parameters. You should use the `update' subcommand of icconfig to modify an existing parameter value. You cannot add or delete a parameter. All config parameters must be defined while generating the resource adapter. Here is an example for how to update an existing connection factory parameters:
icconfig update -s <reg_server_name> -n COTS -p PortNumber=8888
More than one parameter can be specified in a single command. Use the -p <name>=<value> format for each parameter.
Step 4- Deploy SOAP Services (icwsdeploy) - optional
If a SOAP accessibility framework is generated for the resource adapter, upon successful compilation and packaging, the jar files corresponding to the deployment descriptor and the HTTP clients are created under the adapter ship directory. All other necessary infrastructure, such as serializers/deserializers, are packaged along with the resource adapter .rar file, that can deployed as described in Step 2 - Deploy Resource Adapter (icradeploy).
The following tasks must be performed before proceeding with SOAP service deployment:
- Make sure that the deployment descriptor and HTTP client jar files are created successfully.
If the adapter logical name is ALN, 2 jar files name ALN-soapdd.jar and ALN-soapclient.jar are created in resource adapter ship directory. ALN-soapdd.jar contains the deployment descriptors of all SOAP services generated for the resource adapter. The ALN-soapclient.jar contains the HTTP Client classes generated for each service.
- Make sure that the target deployment server is up and running. It is essential for SOAP service deployment to have the server running. Follow the steps mentioned in ""Installing Apache SOAP 2.2" for verification.
- Register the target server using icsvrreg if it is not already registered.
Use the icwsdeploy command to deploy/undeploy the SOAP services generated by Connector Builder in both managed and non-managed environments.
The syntax of the command is as follows:
icwsdeploy <subcommand> [<options>]
icwsdeploy deployall -s <server_name> -j <jar file with dds>
For complete details about the icwsdeploy command, refer to "Command Line Interface Reference".
Examples
The following are examples for usage of icwsdeploy:
icwsdeploy deploy -s myias1 -d /export/home/mydescriptor.xml
icwsdeploy deployall -s myias1 -j /export/home/COTS-soapdd.jar
icwsdeploy undeploy -s myias1 -n urn:COTS:COTSAPIGetCustomer
icwsdeploy list -s myias1
icwsdeploy -h
icwsdeploy -v
Step 5- Check the Version of Sun ONE Connector Builder (icversion) - optional
Use the icversion command to check the version of the Connector Builder.
The syntax of the of command is as follows:
icversion[-h] [-v] [-r <rarFile>]
The following table lists the icversion options. The left column lists the subcommand long name. The middle column lists the subcommand short name and the right column lists the meaning.
For complete details about the icversion command, refer to "Command Line Interface Reference".
Examples
The following are examples for usage of icversion:
icversion
icversion -v
icversion --version
icversion - h
icversion --help
icversion -r COTS.rar
icversion -rarfile COTS.rar
Using the Resource Adapters
After you deploy the resource adapters they can be used in the following ways:
Using CCI
In this scenario, the J2EE application clients use the J2EE CA prescribed CCI programming model to use the resource adapter. The client needs to get the connection, create the interaction on the connection, create the InteractionSpec, Input record corresponding to the method it wants to invoke, and then call execute on the Interaction to receive the output record. Refer to the J2EE Connector Architecture for more details on using the CCI programming model.
Using JIO
Connector Builder provides an easier and more convenient way to access the resource adapter without the need to know the intricate details of the CCI programming model. In this scenario, the application client prepares the input record for the InteractionSpec it wants to invoke, instantiates the JIO object and calls its execute method passing the input record. The JIO returns the output record to the client.
Using SOAP
Connector Builder generated SOAP clients can be used as stand alone applications or modified as desired to suit various needs. In this scenario, the generated SOAP clients use SOAP messages over HTTP/S to call the resource adapter. The programming model is similar to using the JIOs. The client prepares the SOAP Call object with details of the URN of the method to invoke, fills in the details of the method's input parameters and makes the SOAP request.
When you package the reseouce adapter with SOAP services, Connector Builder creates an <adaptername>-soapclient.jar which contains all the generated SOAP client classes. Be certain that the jar file, the adapter rar file and Apache SOAP runtime are in the CLASSPATH while running the SOAP clients as stand alone applications.