Skip Headers
Oracle® Application Server Adapter for PeopleSoft User's Guide
10g Release 2 (10.1.2)
B14060-02
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

3 OC4J Deployment and Integration

This chapter describes Oracle Containers for J2EE (OC4J) deployment and integration with OracleAS Adapter for PeopleSoft.

This chapter discusses the following topics:


See Also:


Adapter Integration with OC4J

OracleAS Adapter for PeopleSoft is deployed within an OC4J container during installation. All client applications run within the OC4J environment. In J2CA deployment, the Common Client Interface (CCI) integrates an OC4J client application with a resource adapter.


See Also:


Deployment of Adapter

Figure 3-1 shows deployment of the Connector to the Oracle Application Server. In a runtime service scenario, an EJB, servlet, or Java program client makes CCI calls to J2CA resource adapters. The adapters process the calls as requests and send them to the EIS. The EIS response is then sent back to the client.

Figure 3-1 Oracle Application Server Adapter J2CA Architecture

OracleAS Adapter JCA Architecture
Description of the illustration xipps002.gif

Updating Adapter Configuration

During the J2CA deployment of OracleAS Adapter for PeopleSoft, OC4J generates a deployment descriptor called oc4j-ra.xml, located in OC4J_home\integration\orabpel\system\appserver\oc4j\j2ee\home\application-deployments\default\iwafjca.


Note:

Your installation contains more than one file named oc4j-ra.xml. The OC4J deployment descriptor described in this section is located in the directory specified earlier.

Creating a Managed Connector Factory Object

The oc4j-ra.xml descriptor provides OC4J-specific deployment information for resource adapters. For example, the default jca_sample configuration in Application Explorer is represented in the oc4j-ra.xml file as follows:

<?xml version="1.0"?><!DOCTYPE oc4j-connector-factories PUBLIC "-//Oracle//DTD 
Oracle Connector 9.04//EN" "http://xmlns.oracle.com/ias/dtds/oc4j-connector-factories-9_04.dtd">
<oc4j-connector-factories>
	   <connector-factory location="eis/OracleJCAAdapter/DefaultConnection" connector-name="IWAFJCA10">
		   <config-property name="IWayHome" value="../../adapters/application"/>
		   <config-property name="IWayConfig" value="jca_sample"/>
   		<config-property name="IWayRepoURL" value=""/>
   		<config-property name="IWayRepoUser" value=""/>
   		<config-property name="IWayRepoPassword" value=""/>
   		<config-property name="logLevel" value="debug"/>
   	</connector-factory>
</oc4j-connector-factories>

The parameters defined in the oc4j-ra.xml file are described in the following table:

Parameter Name Description
IWayHome The base installation directory for the OracleAS packaged application adapter.
IWayConfig The adapter configuration name as defined in Application Explorer. For example, OracleAS Adapter for PeopleSoft has a preconfigured jca_sample configuration in Application Explorer.
IWayRepoURL The URL to use when opening a connection to the database. This is necessary only when using an Oracle database as the BSE repository. See "Configuring BSE System Settings" for more information.
IWayRepoUser User name to use when connecting to the database. This is necessary only when using an Oracle database as the BSE repository. See "Configuring BSE System Settings" for more information.
IWayRepoPassword Password. If provided, it overwrites configuration. This is necessary only when using an Oracle database as the BSE repository. See "Configuring BSE System Settings" for more information.
loglevel It overwrites the level set by the ManagedConnectionFactory property. .

Creating Multiple Managed Connector Factory Objects

To establish multiple managed connector factory objects, you must edit the oc4j-ra.xml file and add more <connector-factory> nodes. For example, the default jca_sample configuration in Application Explorer is represented in the oc4j-ra.xml file as follows:

<?xml version="1.0"?><!DOCTYPE oc4j-connector-factories PUBLIC "-//Oracle//DTD 
Oracle Connector 9.04//EN" "http://xmlns.oracle.com/ias/dtds/oc4j-connector-factories-9_04.dtd">
<oc4j-connector-factories>
	   <connector-factory location="eis/OracleJCAAdapter/DefaultConnection" connector-name="IWAFJCA10">
		   <config-property name="IWayHome" value="../../adapters/application"/>
		   <config-property name="IWayConfig" value="jca_sample"/>
   		<config-property name="IWayRepoURL" value=""/>
   		<config-property name="IWayRepoUser" value=""/>
   		<config-property name="IWayRepoPassword" value=""/>
   		<config-property name="logLevel" value="debug"/>
   	</connector-factory>
</oc4j-connector-factories>

To create multiple managed connector factory objects, you must add new <connector-factory> nodes in the file. For example:

<?xml version="1.0"?><!DOCTYPE oc4j-connector-factories PUBLIC "-//Oracle//DTD 
Oracle Connector 9.04//EN" "http://xmlns.oracle.com/ias/dtds/oc4j-connector-factories-9_04.dtd">
<oc4j-connector-factories>
   <connector-factory location="eis/OracleJCAAdapter/DefaultConnection1" connector-name="IWAFJCA10">
   <config-property name="IWayHome" value="../../adapters/application"/>
   <config-property name="IWayConfig" value="jca_sample"/>
   <config-property name="IWayRepoURL" value=""/>
   <config-property name="IWayRepoUser" value=""/>
   <config-property name="IWayRepoPassword" value=""/>
   <config-property name="logLevel" value="debug"/>
   </connector-factory>
<connector-factory location="eis/OracleJCAAdapter/DefaultConnection2" connector-name="IWAFJCA10">
		   <config-property name="IWayHome" value="../../adapters/application"/>
		   <config-property name="IWayConfig" value="jca_sample2"/>
		   <config-property name="IWayRepoURL" value=""/>
		   <config-property name="IWayRepoUser" value=""/>
   		<config-property name="IWayRepoPassword" value=""/>
		   <config-property name="logLevel" value="debug"/>
	   </connector-factory>
</oc4j-connector-factories>

How to Write a Java Application Client Using the CCI API

The following example shows the code structure for using CCI with packaged application adapters. The code sample is shown in four steps.

Step 1. Obtain the Connection Factory

The connection factory is obtained by JNDI lookup.

InitialContext context = new InitialContext();
ConnectionFactory cf = (ConnectionFactory)context.lookup(iwayJndi)

Step 2. Obtaining a Connection for the Adapter

IWAFConnectionSpec is an implementation of ConnectionSpec used for creating a design time or runtime service adapter connection. The ConnectionSpec has seven parameters. Connection Pooling is fully supported and established based on these parameters, except log level.

Parameter Name Description
adapterName Name of the packaged application adapter.
config - Adapter configuration name. NOT REQUIRED FOR IWAEAdapter.
language Default is en.
country Default is us.
userName User name. If provided, it overwrites configuration.
password Password. If provided, it overwrites configuration.
logLevel It overwrites the level set by the ManagedConnectionFactory property.

A connection pool is a set of client connections to a specific destination. The pool may automatically create new connections to the specified remote system or return an already existing connection. It also provides methods to return a connection back to the pool when it is no longer required.

A connection pool can check which connections are no longer in use and can be closed to save system resources. The time period after which the pool checks the connections and the time after which a connection will time out can be configured by the calling application.

A pool is always bound to one user ID and password, meaning that all connections taken from this pool will also use these credentials. A PeopleSoft connection is always bound to a PeopleSoft user ID and a PeopleSoft Client number.

If you log on with a pool size that is set to one, no connection pool is created (one user ID and one process thread). If you log on with a pool size that is greater than one, a pool is created with a size of n, where n is the number you specified.


Note:

Currently the OracleAS Adapter J2CA supports only basic security mapping. The DEBUG log level provides detailed information on the mapping behavior. It functions as follows:
  • If the userName and password are not set, and no security is provided by the application server, the OracleAS Adapter J2CA will still let it pass and rely on the adapter configuration security information.

  • If userName and password are set, these values will overwrite the adapter configuration. The OracleAS Adapter J2CA compares this information with the security information provided by the application server and log in case the values do not match. However, it still allows the information through.


The iWAFConnectionSpec can be set to initiate an interaction with PeopleSoft by specifying the adapter name and configuration parameters in the ConnectionSpec. For example,

iWAFConnectionSpec cs = new IWAFConnectionSpec();
	  cs.setAdapterName(ADAPTER); 
	  cs.setConfig(TARGET);
	  cs.setLogLevel(LOG_LEVEL);  // Adapter layer log level
	  Connection c = cf.getConnection(cs);// where cf is the connection factory

In this snippet, ADAPTER and TARGET refer to the adapter being deployed, in this case PeopleSoft, and the name of a target defined in Application Explorer. For more information, see "Complete Code Sample".

Step 3. Create Interaction with InteractionSpec for runtime

Interaction i = c.createInteraction();
	  IWAFInteractionSpec is = new IWAFInteractionSpec();
	  is.setFunctionName(IWAFInteractionSpec.PROCESS);

Two functions can be set: PROCESS and IWAE. PROCESS are used at runtime. IWAE is used when you are using the IAEAdapter at design time.

Step 4. Create Input Record and Execute Interaction

In this case, to complete the EIS invocation, a PeopleSoft message is referenced. The schema is provided by Application Explorer.

A standard J2CA indexed record is used in this example:

// Use JCA IndexRecord, named "input" for runtime processing.
		IndexedRecord rIn = cf.getRecordFactory().createIndexedRecord("input");
		rIn.add(msg_run);
	  IndexedRecord rOut = (IndexedRecord)i.execute(is, rIn);
		System.out.println((String)rOut.get(0));

A special record is supported in this example:

//IWAFRecord rIn = new IWAFRecord("input");
		//rIn.setRootXML(msg_run);						
		//IWAFRecord response = executeRunInteraction(c, rIn);
	  //IWAFRecord rOut = (IWAFRecord)i.execute(is, rIn);
		//System.out.println(rOut.getRootXML());

Where msg_run is an instance XML document generated from the schema created by Application Explorer. For example, the following is a sample PeopleSoft request XML document.

<?xml version="1.0" encoding="UTF-8" ?> 
<PS8>
  <component perform="browse">LOCATION</component> 
  <key name="Setid">SHARE</key> 
  <key name="Location">ALBERTA</key> 
</PS8>

Complete Code Sample

The following is a sample of the complete code:

import javax.resource.cci.*;
import com.ibi.afjca.cci.*;
import com.ibi.afjca.spi.*;
 
/**
 * The purpose of this sample is to illustrate how to use the IWAF Universal
 * JCA connector.
 */
public class IWAFJCASimple {
  
	private static String  HOME 	   = "c:/iway/xfoc/components/iwafcont/dist";
	private static String  CONFIG    = "base"; 
	private static String  LOG_LEVEL = "FATAL";
	
	private static String ADAPTER = "PeopleSoft";
	private static String TARGET  = "PeopleSoft_connection";
	
	// Input Message
	private static String msg_run = "<PeopleSoft/>";
	
  public static void main(String[] args) throws Exception {
		
		// 1. Getting the Connection factory through JNDI lookup
		// ---------------------------------------------------------
	  InitialContext context = new InitialContext();
	  ConnectionFactory cf = (ConnectionFactory)context.lookup(iwayJndi)
	  // 2. Getting a connection for a particular adapter target, in this case PeopleSoft
		// ---------------------------------------------------------
	  IWAFConnectionSpec cs = new IWAFConnectionSpec();
	  cs.setAdapterName(ADAPTER); 
	  cs.setConfig(TARGET);
	  cs.setLogLevel(LOG_LEVEL);  // Adapter layer log level
	  Connection c = cf.getConnection(cs);// where cf is the connection factory
 
	  // 3. Create interaction with interactionSpec for RUNTIME 
		// ---------------------------------------------------------
	  Interaction i = c.createInteraction();
	  IWAFInteractionSpec is = new IWAFInteractionSpec();
	  is.setFunctionName("PROCESS"); 
 
	  // 4. Create input Record and execute interaction
		// ---------------------------------------------------------
 
	  // 4.1 Using JCA standard Indexed Record
		// Use JCA IndexRecord, named "input" for runtime processing.
		IndexedRecord rIn = cf.getRecordFactory().createIndexedRecord("input");
		rIn.add(msg_run);
	  IndexedRecord rOut = (IndexedRecord)i.execute(is, rIn);
		System.out.println((String)rOut.get(0));
	  
	  // 4.2 Our own Record is supported here
		//IWAFRecord rIn = new IWAFRecord("input");
		//rIn.setRootXML(msg_run);		
		//IWAFRecord response = executeRunInteraction(c, rIn);
	  //IWAFRecord rOut = (IWAFRecord)i.execute(is, rIn);
		//System.out.println(rOut.getRootXML());
		
  } // main()
	  
}