Skip Headers
Oracle® Application Server Integration InterConnect Adapter for JCA Installation and User's Guide
10g Release 2 (10.1.2)
B19182-01
  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 Design-Time and Run-Time

This chapter describes the design-time and run-time concepts for the JCA adapter. It contains the following topics:

Design-Time Concepts

The design time for JCA adapter consists of following three steps:

These design-time steps are explained by using a scenario in the following sections.

Scenario Overview

This section describes how to design and execute the following integration scenario

  1. The publishing JCA adapter polls two database tables Departments and Employees for new record inserts. The DeptID column of the Employees table references the DeptID column of the Departments table.

  2. When you insert a new record in any of these tables, the publishing JCA adapter publishes the message to the InterConnect Hub. This message contains the data that was inserted in the table.

  3. The subscribing JCA adapter polls the InterConnect hub queue for messages and receives the new message.

  4. The subscribing JCA adapter inserts the data contained in the message into the NewEmployees or NewDepartments tables.

Pre-Requisites

This example assumes that you are familiar with basic BPEL constructs, such as activities and partner links, and JDeveloper environment for creating a BPEL process.

You need following tables for this scenario:

  • DEPARTMENTS

    Use the following code to create the table: 

    CREATE TABLE DEPARTMENTS
(
  DEPTNO NUMBER(2) CONSTRAINT PK_DEPT PRIMARY KEY,
  DNAME VARCHAR2(14),
  LOC VARCHAR2(13)
);

  • NewDEPARTMENTS

    Use the following code to create the table: 

    CREATE TABLE NewDEPARTMENTS
(
   DEPTNO NUMBER(2) CONSTRAINT PK_NewDEPT PRIMARY KEY,
   DNAME VARCHAR2(14),
   LOC VARCHAR2(13)
) ;

  • EMPLOYEES

    Use the following code to create the table: 

    CREATE TABLE EMPLOYEES
(
   EMPNO NUMBER(4) CONSTRAINT PK_EMP PRIMARY KEY,
   ENAME VARCHAR2(10),
   JOB VARCHAR2(9),
   MGR NUMBER(4),
   HIREDATE DATE,
   SAL NUMBER(7,2),
   COMM NUMBER(7,2),
   DEPTNO NUMBER(2) CONSTRAINT FK_DEPTNO REFERENCES DEPARTMENTS
);

  • NewEMPLOYEES

    Use the following code to create the table: 

    CREATE TABLE NewEMPLOYEES
(
   EMPNO NUMBER(4) CONSTRAINT PK_NewEMP PRIMARY KEY,
   ENAME VARCHAR2(10),
   JOB VARCHAR2(9),
   MGR NUMBER(4),
   HIREDATE DATE,
   SAL NUMBER(7,2),
   COMM NUMBER(7,2),
   DEPTNO NUMBER(2) CONSTRAINT FK_NewDEPTNO REFERENCES NewDEPARTMENTS
);

Generating the WSDL Files

JCA adapter uses the WSDL file to perform the WSIF invocation. You can generate a WSDL file in many ways. This section explains how to generate WSDL files by using the Oracle JDeveloper.

Generating the JCAPublish.wsdl File

Follow these steps to generate the JCAPublish.wsdl file in JDeveloper:

  1. From the File menu, select New. The New Gallery dialog box is displayed.

  2. Select Workspaces from Categories and then Workspace from Items.

  3. Click OK. The Create Workspace dialog box is displayed.

  4. Enter MyWorkspace as Workspace Name.

  5. Deselect Add a Empty New Project and click OK.

  6. Right-click MyWorkspace and select New Project. The New Gallery dialog box is displayed.

  7. Select Project from Categories and select BPEL Process Project from Items.

  8. Click OK. The BPEL Process Project dialog box is displayed.

  9. Enter Publisher as the BPEL Process Name.

  10. Select Empty BPEL Process from Templates.

    Figure 3-1 BPEL Process Project dialog box

    Description of Figure 3-1 follows
    Description of "Figure 3-1 BPEL Process Project dialog box"

  11. Click OK.

  12. Drag a Partner Link activity from the components palette. The Create Partner Link dialog box is displayed.

  13. Enter PublishProcess in the Name field.

  14. Click the Define Adapter Service icon. The Adapter Configuration Wizard Welcome window is displayed.

    Description of acf1.gif follows
    Description of the illustration acf1.gif

  15. Click Next. The Adapter Type window is displayed

  16. Select Database adapter.

    Figure 3-2 Selecting as Adapter Type

    Description of Figure 3-2 follows
    Description of "Figure 3-2 Selecting as Adapter Type"

  17. Click Next. The Service Name window is displayed.

  18. Enter a JCAPublish in the Service Name field.

    Figure 3-3 Specifying the Service Name

    Description of Figure 3-3 follows
    Description of "Figure 3-3 Specifying the Service Name"

  19. Select a database connection from Connection. If no connection exists, you can also create a new connection. To create a new connection, click New and use the Create Database Connection wizard to create a new connection.

    Figure 3-4 Specifying the Service Connection

    Description of Figure 3-4 follows
    Description of "Figure 3-4 Specifying the Service Connection"

  20. Click Next. The Operation Type window is displayed.

  21. Select Poll for New or Changed Records in a Table.

    Figure 3-5 Selecting the Operation Type

    Description of Figure 3-5 follows
    Description of "Figure 3-5 Selecting the Operation Type"

  22. Click Next. The Select Table window is displayed.

  23. Click Import Tables. The Import tables window is displayed.

  24. Select Employees and Departments table from Available and click the right arrow.

  25. Click OK.

  26. Select Departments table as the root database table.

    Figure 3-6 Selecting a Root Table

    Description of Figure 3-6 follows
    Description of "Figure 3-6 Selecting a Root Table"

  27. Click Next. The Relationships window is displayed.

  28. Click Next. The Object Model window is displayed.

  29. Click Finish.

  30. Click OK in the Create Partner Link dialog box.

  31. Copy the following files from the project directory to the publishing adapter directory:

    • toplink_mappings.xml

    • JCAPublish.wsdl

    • Departments_table.xsd

Generated JCAPublish.wsdl file

After performing these steps, following JCAPublish.wsdl file is generated: 

<?xml version="1.0" encoding="UTF-8"?>
 <definitions 
   name="JCAPublish"
   targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/db/JCAPublish/"
   xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/db/JCAPublish/"
   xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
   xmlns:jca="http://xmlns.oracle.com/pcbpel/wsdl/jca/"
   xmlns:pc="http://xmlns.oracle.com/pcbpel/"
   xmlns:top="http://xmlns.oracle.com/pcbpel/adapter/db/top/Publisher"
   xmlns="http://schemas.xmlsoap.org/wsdl/">
  <types>
      <schema xmlns="http://www.w3.org/2001/XMLSchema">
       <import namespace="http://xmlns.oracle.com/pcbpel/adapter/db/top/Publisher"
        schemaLocation="Departments_table.xsd"/>
      </schema>
  </types>
  <message name="DepartmentsCollection_msg">
        <part name="DepartmentsCollection" element="top:DepartmentsCollection"/>
  </message>
  <portType name="JCAPublish_ptt">
      <operation name="receive">
          <input message="tns:DepartmentsCollection_msg"/>
      </operation>
  </portType>
  <binding name="JCAPublish_binding" type="tns:JCAPublish_ptt">
        <pc:inbound_binding/>
        <operation name="receive">
            <jca:operation
                ActivationSpec="oracle.tip.adapter.db.DBActivationSpec"
                DescriptorName="Publisher.Departments"
                QueryName="JCAPublish"
                PollingStrategyName="DeletePollingStrategy"
                MaxRaiseSize="1"
                MaxTransactionSize="unlimited"
                PollingInterval="5"
                MappingsMetaDataURL="toplink_mappings.xml"
        <input/>
        </operation>
  </binding>
  <!-- Your runtime connection is declared in
        J2EE_HOME/application-deployments/default/DbAdapter/oc4j-ra.xml
        These 'mcf' properties here are from your design time connection and 
        save you from having to edit that file and restart the application server
        if eis/DB/DBConnection is missing.
        These 'mcf' properties are safe to remove.
  -->
    <service name="JCAPublish">
    <port name="JCAPublish_pt" binding="tns:JCAPublish_binding">
    <jca:address location="eis/DB/DBConnection"
      UIConnectionName="DBConnection"
      ManagedConnectionFactory="oracle.tip.adapter.db.DBManagedConnectionFactory"
      mcf.DriverClassName="oracle.jdbc.driver.OracleDriver"
      mcf.PlatformClassName="oracle.toplink.internal.databaseaccess.
       DatabasePlatform
      mcf.ConnectionString="jdbc:oracle:thin:@localhost:1521:ORCL"
                mcf.ConnectionString="jdbc:oracle:thin:@localhost:1521:ORCL"
                mcf.UserName="scott"
                mcf.Password="3E20F8982C53F4ABA825E30206EC8ADE"
/>
    </port>
    </service>
    <plt:partnerLinkType name="JCAPublish_plt" >
        <plt:role name="JCAPublish_role" >
            <plt:portType name="tns:JCAPublish_ptt" />
        </plt:role>
    </plt:partnerLinkType>
 </definitions>

Generating the JCASubscribe.wsdl File

Follow these steps to generate another WSDL with name JCASubscribe:

  1. Click Applications and then right-click MyWorkspace.

  2. Select New Project.

  3. Select Project from Categories and select BPEL Process Project from Items.

  4. Select Empty BPEL Process from Templetes.

  5. Click OK. The BPEL Process Project dialog box is displayed.

  6. Enter Subscriber as the BPEL Process Name.

  7. Click OK.

  8. Drag a Partner Link activity from the components palette. The Create Partner Link dialog box is displayed.

  9. Enter SubscribeProcess in the Name field.

  10. Click the Define Adapter Service icon. The Adapter Configuration Wizard Welcome window is displayed.

  11. Click Next. The Adapter Type dialog box is displayed.

  12. Select Databse adapter and click Next. The Service Name dialog box is displayed.

  13. Enter a JCASubscribe in the Service Name field and click Next. The Connection dialog box is displayed.

  14. Select a database connection from Connection. If no connection exists, you can also create a new connection. To create a new connection, click New and use the Create Database Connection wizard to create a new connection.

  15. Click Next. The Operation Type dialog box is displayed.

  16. Select Perform an Operation on a Table.

  17. Select Insert or Update.

  18. Deselect Delete and Select.

  19. Click Next. The Select Table dialog box is displayed

  20. Click Import Tables. The Import tables dialog box is displayed.

  21. Select NewEmployees and NewDepartments table from Available and click the right arrow.

  22. Click OK.

  23. Select NewDepartments table as the root database table and click Next. The Relationships dialog box is displayed.

  24. Click Next.

  25. Click Finish.

  26. Click OK in the Create Partner Link dialog box.

  27. Copy the following files from the project directory to the subscribing adapter directory:

    • toplink_mappings.xml

    • JCASubscribe.wsdl

    • Newdepartments_table.xsd


      Note:

      the generated files should be copied to the home directory of the adapter only.

Generated JCASubscribe.wsdl File

After performing these steps, following JCASubscribe.wsdl file is generated: 

<?xml version="1.0" encoding="UTF-8"?>
<definitions 
   name="JCASubscribe"
   targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/db/JCASubscribe/"
   xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/db/JCASubscribe/"
   xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
   xmlns:jca="http://xmlns.oracle.com/pcbpel/wsdl/jca/"
   xmlns:pc="http://xmlns.oracle.com/pcbpel/"
   xmlns:top="http://xmlns.oracle.com/pcbpel/adapter/db/top/Subscriber"
   xmlns="http://schemas.xmlsoap.org/wsdl/">
   <types>
     <schema xmlns="http://www.w3.org/2001/XMLSchema">
      <import namespace="http://xmlns.oracle.com/pcbpel/adapter/db/top/Subscriber"
                schemaLocation="Newdepartments_table.xsd"/>
     </schema>
   </types>

   <message name="NewdepartmentsCollection_msg">
    <part name="NewdepartmentsCollection" element="top:NewdepartmentsCollection"/>
   </message>

  <message name="Newdepartments_msg">
     <part name="Newdepartments" element="top:Newdepartments"/>
  </message>

  <portType name="JCASubscribe_ptt">
     <operation name="merge">
           <input message="tns:NewdepartmentsCollection_msg"/>
     </operation>
     <operation name="insert">
           <input message="tns:NewdepartmentsCollection_msg"/>
     </operation>
     <operation name="update">
           <input message="tns:NewdepartmentsCollection_msg"/>
     </operation>
     <operation name="write">
            <input message="tns:NewdepartmentsCollection_msg"/>
     </operation>
     <operation name="queryByExample">
            <input message="tns:Newdepartments_msg"/>
            <output message="tns:NewdepartmentsCollection_msg"/>
     </operation>
  </portType>
  <binding name="JCASubscribe_binding" type="tns:JCASubscribe_ptt">
     <jca:binding />
     <operation name="merge">
       <jca:operation
         InteractionSpec="oracle.tip.adapter.db.DBWriteInteractionSpec"
         DescriptorName="Subscriber.Newdepartments"
         DmlType="merge"
         MappingsMetaDataURL="toplink_mappings.xml" />
       <input/>
     </operation>
        <operation name="insert">
            <jca:operation
                InteractionSpec="oracle.tip.adapter.db.DBWriteInteractionSpec"
                DescriptorName="Subscriber.Newdepartments"
                DmlType="insert"
                MappingsMetaDataURL="toplink_mappings.xml" />
            <input/>
        </operation>
        <operation name="update">
            <jca:operation
                InteractionSpec="oracle.tip.adapter.db.DBWriteInteractionSpec"
                DescriptorName="Subscriber.Newdepartments"
                DmlType="update"
                MappingsMetaDataURL="toplink_mappings.xml" />
            <input/>
        </operation>
        <operation name="write">
            <jca:operation
                InteractionSpec="oracle.tip.adapter.db.DBWriteInteractionSpec"
                DescriptorName="Subscriber.Newdepartments"
                DmlType="write"
                MappingsMetaDataURL="toplink_mappings.xml" />
            <input/>
        </operation>
        <operation name="queryByExample">
            <jca:operation
                InteractionSpec="oracle.tip.adapter.db.DBReadInteractionSpec"
                DescriptorName="Subscriber.Newdepartments"
                IsQueryByExample="true"
               
MappingsMetaDataURL="toplink_mappings.xml" />
            <input/>
        </operation>
    </binding>
    <!-- Your runtime connection is declared in
        J2EE_HOME/application-deployments/default/DbAdapter/oc4j-ra.xml
        These 'mcf' properties here are from your design time connection and 
        save you from having to edit that file and restart the application server
        if eis/DB/DBConnection is missing.
        These 'mcf' properties are safe to remove.
    -->
    <service name="JCASubscribe">
        <port name="JCASubscribe_pt" binding="tns:JCASubscribe_binding">
            <jca:address location="eis/DB/DBConnection"
                UIConnectionName="DBConnection"
               
 ManagedConnectionFactory="oracle.tip.adapter.db.DBManagedConnectionFactory"
                mcf.DriverClassName="oracle.jdbc.driver.OracleDriver"
               
 mcf.PlatformClassName="oracle.toplink.internal.databaseaccess.DatabasePlatform"
                mcf.ConnectionString="jdbc:oracle:thin:@localhost:1521:ORCL"
                mcf.UserName="scott"
                mcf.Password="3E20F8982C53F4ABA825E30206EC8ADE"
            />
        </port>
    </service>
    <plt:partnerLinkType name="JCASubscribe_plt" >
        <plt:role name="JCASubscribe_role" >
            <plt:portType name="tns:JCASubscribe_ptt" />
        </plt:role>
    </plt:partnerLinkType>
</definitions>

Modifying the Generated WSDL Files

In the generated WSDL files, you need to specify the abosolute parh of the toplink_mappings.xml file in the MappingsMetaDataURL parameter such as: 

MappingsMetaDataURL="file:///C:/Oracle/midtier/integration/interconnect/adapters/myJCAAdapter/toplink_mappings.xml"/>

iStudio Design-Time Steps

This section describes design-time steps to be performed in iStudio for implementing the scenario. it contains the following steps:

Creating a Common View

To create a common view:

  1. From the File menu, select New Project. The New Project dialog box is displayed.

  2. Enter the JCAProject in the Project Name field.

  3. Click OK. The Hub Information dialog box is displayed.

  4. Enter information in the following fields:

    • Hub database username: The name of the hub database user.

    • Hub database password: The password associated with the hub database user.

    • Hub database url: The URL of the database in the following format: 

      machine name:port number:database sid

  5. In iStudio, click JCAProject, Common View, and then click Business Object.

  6. Right-click Business Object and select New. The Create Business Object dialog box is displayed.

  7. Enter the JCABusObj in the Business Object Name field.

  8. Click OK.

  9. In the iStudio list, click JCABusObj and then click Event.

  10. Right-click Event and select New. The Create Event dialog box is displayed.

  11. Enter the CVPublishEvent in Event Name field.

  12. Click Import, and then JCA.

  13. Click Browse.

  14. Navigate to the JCAPublish.wsdl file and click Open. The Choose Operation from WSDL dialog box is displayed.

  15. Select Receive Operation.

  16. Click OK.

  17. Click Save in the Create Event dialog box.

  18. Repeat Step 9 to Step 16 to create an event CVSubscribeEvent by using the JCASubscribe.wsdl file.

Publishing the JCA Event

To publish the JCA event:

  1. In iStudio, click JCAProject, and then right-click Applications.

  2. Select New. The Create Application dialog box is displayed.

  3. Enter the JCAPublisher in the Application Name field and click OK.

  4. In iStudio, click Applications, JCAPublisher, and then Published Events.

  5. Right-click Published Events and select New. The Publish Wizard- Select an event dialog box is displayed.

  6. Perform the following steps:

    1. Select JCA from the Message Type list.

    2. Click Business Objects, JCABusObj, and then CVPublishEvent from the Select an Event list.

    3. Click Next. The Publish Wizard- Define Application View dialog box is displayed.

  7. Click Import and then WSDL. The Choose Operations From WSDL dialog box is displayed.

  8. Click Browse and select JCAPublish.wsdl.

  9. Click Open. The Choose Operation from WSDL dialog box is displayed.

  10. Select Receive operation.

  11. Click Next. The Publish Wizard- Define Mapping dialog box is displayed.

  12. Click Define Mapping. The Mapping Parameters dialog box is displayed.

  13. Perform the following mappings:

    1. In JCAPublisher view, select Departments[ ].

    2. In Transformations, select ObjectCopy.

    3. In Common View, select Departments[ ].

    4. Click Add.

    5. Click OK.

  14. Click Finish.

Subscribing the JCA Event

To subscribe to the JCA event:

  1. In iStudio, click JCAProject, and then right-click Applications.

  2. Select New. The Create Application dialog box is displayed.

  3. Enter the JCASubscriber in the Application Name field and click OK.

  4. In iStudio, click Applications, JCASubscriber, and then Subscribed Events.

  5. Right-click Subscribed Events and select New. The Subscribe Wizard- Select an event dialog box is displayed.

  6. Perform the following steps:

    1. Select JCA from the Message Type list.

    2. Click Business Objects, JCABusObj, and then CVSubscribeEvent from the Select an Event list.

    3. Click Next. The Subscribe Wizard- Define Application View dialog box is displayed.

  7. Click Import and then WSDL. The Choose Operations From WSDL dialog box is displayed.

  8. Click Browse and select JCASubscribe.wsdl.

  9. Click OK. The Choose Operation from WSDL dialog box is displayed.

  10. Select Insert operation.

  11. Click Next. The Publish Wizard- Define Mapping dialog box is displayed.

  12. Click Define Mapping. The Mapping Parameters dialog box is displayed.

  13. Perform the following mappings:

    1. In Common View, select Newdepartments[ ].

    2. In Transformations, select ObjectCopy.

    3. In JCASubscriber view, select Newdepartments[ ].

    4. Click Add.

    5. Click OK.

  14. Click Next.

  15. Click Finish.

Run-Time Concepts

This section describes how JCA adapter works at run time. It contains the following sections:

JCA Adapter as the Publishing Adapter

When JCA adapter acts as a publishing adapter, it communicates with the JCA compliant resource adapter through adapter framework. When the adapter is started, the bridge performs endpoint activation to register a callback with the adapter framework. Once this callback is registered, the bridge is ready to start processing the messages it receives from the adapter framework through the registered callback. The resource adpater, in turn, is getting the messages from the Enterprise Information System (EIS).

JCA Adapter as the Subscribing Adapter

When the JCA adapter acts as a subscribing adapter, the communication between the bridge and the resource adapter happens through Web Services Activation Framework (WSIF). The bridge uses the WSDL file to perform the WSIF invocation. The bridge obtains the information about the WSDL file to be used from the metadata that was defined in iStudio during design time. This metadata also contains information about which port type and operation is to be used from the WSDL file. When the bridge receives the message from agent, it uses this information for WSIF invocation.

Starting the JCA Adapter

The process for starting the adapter varies based on the operating system.

Log File of the JCA Adapter

You can verify the start up status of the JCA adapter by viewing the log.xml files. The files are located in the time-stamped subdirectory of the log directory of the JCA adapter. Subdirectory names have the following form: 

timestamp_in_milliseconds

Stopping the JCA Adapter

The process for stopping the adapter varies based on the operating system.

  Previous
Previous 		Next
Next
  Go To Documentation Library
Home		 Go To Product List
Solution Area		 Go To Table Of Contents
Contents		 Go To Index
Index