|
Oracle® Application Server ProcessConnect User’s Guide
10g (9.0.4) Part No. B12121-02 |
|
|
|
|
Oracle® Application Server ProcessConnect User’s Guide
10g (9.0.4) Part No. B12121-02 |
|
|
|
|
This chapter provides details about the technology adapters included with Oracle Application Server ProcessConnect.
This chapter contains these topics:
|
See Also:
|
The details provided for each technology adapter in this chapter are divided into the sections shown in Table 8-1. Brief descriptions of the details covered in each section are also provided.
Table 8-1 Adapter Details Overview
| Section | Description |
|---|---|
| Benefits of using the adapter | This section describes the benefits of using an adapter. |
| Supported versions | This section describes the supported versions of components that interact with an adapter (such as an Oracle database or Java Messaging Service providers). |
| Application delivery channel description | An application is a party that you assign to an agreement. This enables the party to participate in an integration with another party. Each application uses an adapter that enables communication between parties (with their different interfaces) and Oracle Application Server ProcessConnect.
You also create an application delivery channel for an adapter. Delivery channels describe delivery, security, and endpoint details for messages delivered between parties. This section briefly describes delivery channel parameters and provides references to the delivery channel parameters you must define for an adapter. |
| Adapter exchange protocols | Interactions define the communication between the Oracle Application Server ProcessConnect runtime system and various adapters to send and receive data. When you add an interaction, you must typically provide responses to a series of questions. The questions that display are based on the type of adapter exchange protocol you select. Adapter exchange protocols are an adapter’s logical grouping of interactions and represent the unique actions that can be performed with a specific adapter.
This section describes the adapter exchange protocols supported by an adapter and provides references to the interaction questions you must answer for an adapter. See Also: "Adding an Adapter Interaction" |
| Design-time tasks | This section provides an overview of design-time tasks and Oracle record element conventions for an adapter. The Oracle record represents the input or output to an adapter interaction. |
| Interaction and record naming restrictions | This section describes interaction and record naming restrictions for an adapter. |
| Errors | This section describes adapter errors. |
| Validation prerequisites | This section describes any adapter requirements to satisfy before an adapter can be included in a successfully validated and deployed configuration. |
| Additional setup tasks | This section describes adapter setup tasks to perform in addition to the delivery channel parameter and interaction question tasks that you perform with the Oracle Application Server ProcessConnect user interface tool. |
| Application integration and runtime behavior | This section describes additional application integration tasks for most adapters, such as any schema objects you must create to use an adapter. |
| Limitations | This section describes any adapter limitations. |
| Diagnostics and troubleshooting | This section describes logging diagnostics and procedures for troubleshooting adapter problems. |
| Use case | This section provides an example of using an adapter. |
|
See Also: The Interaction and Record Naming Restrictions sections in this chapter for details about any event map requirements for your adapter |
This chapter references adapter-related tasks that you perform with the Oracle Application Server ProcessConnect user interface tool. These tasks are described in other sections of this User Guide. This section provides a graphical, high-level overview of these tasks using the File/FTP adapter as an example. Similar tasks must be performed to use other technology adapters with Oracle Application Server ProcessConnect.
A delivery channel describes the communication capabilities (such as message exchange and security details) of a specific adapter. Each adapter has its own unique delivery channel parameters that you must define. Figure 8-1 shows the parameters to define for the File/FTP adapter.
|
See Also: "Creating an Application Delivery Channel" for instructions on adding delivery channels for all adapters |
You select an adapter exchange protocol for which to add an interaction on the Add Interaction: Select Interaction page, as shown in Figure 8-2. For this example, the ReadFile(FileRecord) adapter exchange protocol of the File/FTP adapter is selected.
|
Note: The File portion of the (FileRecord) adapter exchange protocol name in Figure 8-2 is replaced with a content type you select when adding an interaction. For example, if you specify xml as the content type, the interaction name includes (xmlRecord) as part of the interaction name (as shown in Figure 8-7). This convention is followed by several technology adapters. |
You then provide answers to adapter interaction questions when prompted, as shown in Figure 8-3.
More than one page of questions can appear depending on the adapter exchange protocol selected.
|
See Also: "Adding an Adapter Interaction" for instructions on adding adapter interactions for each adapter |
After you create your adapter interaction (and its Oracle records), you create a native event and its body elements, select a translator, and create an application event and its body elements through a wizard-based tool. You can perform these tasks during the same session in which you add your adapter interaction or during a separate session. After completing these tasks, you can view the results from the details pages of the native event type. The Event Body Elements section enables you to view the Oracle records created from your application’s wire message contents, as shown in Figure 8-4.
The details page of a record element type is available from the Record Type Element column, as shown in Figure 8-5.
You can view the following details from this page:
A record type element has a particular native format (either XSD, data definition description language (D3L), or token substituted text). In this example, the native format is XSD.
A record element has a value type (either XML, CLOB, or BLOB) with the following restrictions:
D3L is only used for value type BLOB.
The value type XML is only used with the XSD native format.
In this example, the value type is BLOB.
You can also view the application event details, including the application datatypes created from your application’s wire message contents, as shown in Figure 8-6.
The interaction you added in "Add an Interaction" can be viewed from the Interaction page. As part of the interaction name, any IN (inbound) and OUT (outbound) records associated with the interaction appear. In Figure 8-7, the File/FTP adapter has a single IN record in the inbound direction (xmlRecord).
Clicking this interaction displays the details page shown in Figure 8-8. Any IN and OUT records of the interaction appear (for this example, IN record xmlRecord).
Clicking the xmlRecord IN record type of the interaction displays the details page, as shown in Figure 8-9. The native datatypes and native event type of this record appear.
The record type element in Figure 8-9 can display its native datatypes in the Datatype section. Some adapters, such as the Oracle Database, Advanced Queuing, and Web Service adapters, automatically detect the native datatypes when an interaction is added. This means that when you are creating a native event that uses this interaction, you are not prompted to specify a native datatype format file. Other adapters, such as the File/FTP adapter, do not detect the native datatypes. Instead, you are prompted to specify a native datatype format file during native event creation.
The page provides a definition of the native datatypes, including the file name.
After completing these tasks, you have defined the delivery channel and adapter interaction parameters to include in your integration.
Oracle Application Server ProcessConnect provides support for the native formats shown in Table 8-2. The value types supported by each native format are also listed. The native formats and content types supported by each adapter are described throughout this chapter.
This section provides details about using the Advanced Queuing adapter. This section contains these topics:
Advanced Queuing Adapter Application Delivery Channel Description
Advanced Queuing Adapter Interaction and Record Naming Restrictions
Advanced Queuing Adapter Application Integration and Runtime Behavior
Advanced Queuing Adapter Use Case
|
See Also: "Layout of Adapter Details in this Chapter" for an overview of topics covered for each adapter in this chapter |
The Advanced Queuing adapter enables applications to communicate asynchronously with Oracle Application Server ProcessConnect over a reliable, scalable, and secure communication channel. Oracle advanced queuing provides an extremely flexible mechanism for bidirectional, asynchronous communication between participating applications. Application location is transparent, using any number of Oracle's connectivity options, including OCI, JDBC, or PL/SQL. Both XML and non-XML message payloads are supported.
Since advanced queues are an Oracle database feature, they are extremely scalable and reliable. Backup and recovery (including any-point-in-time recovery), logging, transactional services, and system management are all inherent features of the database and, therefore, advanced queues. Multiple queues can also service a single application, partitioning messages in a variety of ways and providing another level of scalability through load balancing.
Application integration is possible, regardless of the application location. Since advanced queuing is a database feature, the services (API) are accessible through many languages and platforms, including Oracle Call Interface (OCI), JMS through JDBC, and PL/SQL. Complete bidirectional messaging propagation is supported.
Oracle advanced queues and the Advanced Queuing adapter support both XML and non-XML payload types. Message payloads can be defined in XML and a set of XML utilities and services are now available as features of the database. Non-XML payloads can be defined using Oracle Abstract Data Types (ADTs), or as SQL data structures. In all cases, the payload definitions can be defined, stored, and accessed in the Oracle Catalog and shared across the enterprise.
|
Note: This description does not suggest that the Advanced Queuing adapter supports the XMLType queue payload type; only that the supported RAW or Object (ADT) type queues can contain either XML or non-XML payloads due to the inherent support for these different formats in the Oracle Application Server ProcessConnect translator layer. |
Oracle provides an array of security models and options for authentication, authorization, and encryption. Since Advanced Queues are part of the database, the security model is sharable across the enterprise with different applications and user groups. The Advanced Queuing adapter fully supports all these security options.
The Advanced Queuing adapter supports Oracle database server versions 8.1.7, 9.0.1.4, and 9.2 as the application (spoke) database. The application database is (but does not need to be) a separate database from the Oracle Application Server Metadata Repository. This repository contains the Oracle Application Server ProcessConnect schema and modeling metadata and profile data that you create with the Oracle Application Server ProcessConnect user interface tool.
You must create a delivery channel to interact with the application database server by specifying a series of parameters that describe Advanced Queuing adapter connection information, including database server hostname and JDBC driver details, a connection username and password, the time between connection retries, and a schema name for the queues being accessed in the database server. These parameter details comprise the delivery channel.
|
See Also: "Creating an Advanced Queuing Adapter Delivery Channel" for the list of parameters you specify to create a delivery channel |
Table 8-3 identifies and describes when to use the Advanced Queuing adapter exchange protocols. Each adapter exchange protocol operates in the inbound and outbound directions.
Table 8-3 Advanced Queuing Adapter Exchange Protocols - Inbound and Outbound Directions
| Inbound and Outbound Direction | Description |
|---|---|
| RAW Queue | This protocol interacts with RAW advanced queuing queues. |
| Oracle Object Queue | This protocol interacts with Oracle object queues, where the Oracle object type, also known as an ADT, is the payload. |
| Oracle Object Queue with payload fields | This protocol interacts with object queues, where one or more large object (LOB)-type fields of the ADT carry a payload. |
|
See Also:
|
Table 8-4 provides examples of the naming conventions for Advanced Queuing adapter exchange protocols in the Oracle Application Server ProcessConnect user interface tool. The information appearing under the User Interface Naming Convention column is the interaction groups and interaction descriptions (names).
Table 8-4 Advanced Queuing Adapter Naming Conventions
| Adapter Exchange Protocol | User Interface Naming Convention |
|---|---|
| Inbound | Queue names adhere to the following convention when displaying in the user interface tool: |
|
Queues that begin with R.
|
|
Queues that begin with E.
|
|
Queues that begin with N.
|
| Outbound | Queue names adhere to the following convention when displaying in the user interface tool: |
|
Queues that begin with R.
|
|
Queues that begin with E.
|
|
Queues that begin with N.
|
Table 8-5 describes RAW Queue record element naming conventions.
Table 8-5 RAW Queue Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
AQ-Headers
|
Includes the advanced queuing headers | XML | Adapter | AQ-Headers | XSD only |
Payload
|
The advanced queuing payload to enqueue or dequeue | BLOB | User | None | None |
Table 8-6 describes Oracle Object Queue record element naming conventions.
Table 8-6 Oracle Object Queue Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
AQ-Headers
|
Includes the advanced queuing headers | XML | Adapter | AQ-Headers | XSD only |
Object_Type_Name_Payload
|
The advanced queuing payload to enqueue or dequeue | XML | Adapter | Object_Type_Name_Payload
|
XSD only |
Table 8-7 describes Oracle Object Queue with Payload Fields record element naming conventions.
Table 8-7 Oracle Object Queue with Payload Fields Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
AQ-Headers
|
Includes the advanced queuing headers | XML | Adapter | AQ-Headers | XSD only |
Object_Type_Name_Headers
|
Includes the nonpayload fields of the object type | XML | Adapter | Object_Type_Name_Headers
|
XSD only |
Payload_Field_Name
|
For each payload field of the object type, there is a record element | BLOB if the payload field has a binary datatype
CLOB if the payload field has a string datatype |
User | None | If the value type is CLOB, then D3L cannot be used. |
...Foot 1
|
|
|
|
|
|
|
Note: When using the Oracle object queue with payload fields, all binary members (BLOBs and RAWs) of the object type that are not marked as payload fields should be encoded with the default character set of the platform. |
You cannot have two queues with the same name in different schemas if the queues have different structures. This causes the record names to be the same.
Table 8-8 lists when Advanced Queuing adapter errors occur and how they are handled by the adapter.
Table 8-8 Advanced Queuing Adapter Errors
| An Error Occurs While... | Adapter Error Handling Behavior |
|---|---|
| Establishing a connection | Displays the following error: CouldNotConnect
At design time, it displays the error immediately without any retrying. At runtime, for the outbound case, the error appears in the log file. The Advanced Queuing adapter does not try to reestablish the connection; the adapter framework performs this task. For the inbound case, the adapter attempts to reconnect as often as you specified for connection retries when you created the delivery channel. See Also: "Creating an Advanced Queuing Adapter Delivery Channel" |
| Enqueuing | Logs an error code initiated by JAQ or JDBC |
If native event validation fails for an inbound event, the Advanced Queuing adapter discards the message, since this is an unrecoverable validation error. However, the Oracle Application Server ProcessConnect runtime has already made a copy of the message available in memory for subsequent diagnostic analysis.
You can test the validity of the Advanced Queuing adapter delivery channel parameters against a running database by establishing a SQL*Plus connection. Enter the follow command from the command line prompt:
sqlplus "username/password@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) \ (HOST=hostname)(PORT=port))(CONNECT_DATA=(SERVICE_NAME=SID)))"
This section describes setup tasks to perform in addition to the delivery channel parameter and interaction question tasks that you perform with the Oracle Application Server ProcessConnect user interface tool.
This section contains the following sections:
The Advanced Queuing adapter only enables you to configure queues that it can find in the database at design time. At runtime, the queues must be in the STARTED state.
Ensure that you can access the queues. The admin user automatically created during Oracle Application Server ProcessConnect installation can access the queues owned by another user.
For example, assume user Username accesses a queue named QueueName owned by user Schema. QueueName is an Oracle object type queue, and its underlying queue table is QueueTableName. The Oracle object type is QueueADT, and it is owned by ADT_owner. (QueueName and QueueTableName must exist in the same schema.)
For this example, the minimum set of database privileges and grants assigned to or issued from the mentioned database users are as follows:
Oracle Object Type Owner (ADT_owner)
The following grants are necessary if the queue is an Oracle object type queue, and Schema and ADT_owner are different. The roles and privileges must be assigned to user ADT_owner, while the grants are executed as user ADT_owner.
Role: CONNECT
Privilege: CREATE TYPE
Grant: GRANT EXECUTE ON QueueADT TO Schema
Grant: GRANT EXECUTE ON QueueADT TO Username (Must be performed by Schema if this user owns the ADT.)
Queue Owner (assuming it's owned by Schema, not Username)
Role: CONNECT
Role: RESOURCE
Role: AQ_ADMINISTRATOR_ROLE
Grant: GRANT SELECT ON QueueTableName TO Username
Grant: GRANT UPDATE ON QueueTableName TO Username
Grant: DBMS_AQADM.GRANT_QUEUE_PRIVILEGE (privilege => ’DEQUEUE’,queue_name => ’ QueueName’ ,grantee => ’ Username’ , grant_option => FALSE);
Grant: DBMS_AQADM.GRANT_QUEUE_PRIVILEGE (privilege => ’ENQUEUE’, queue_name => ’ QueueName’,grantee => ’ Username’,grant_option => FALSE);
Queue Owner (if queue owned by Username; that is, Username = Schema)
Role: CONNECT
Grant (from SYS): GRANT EXECUTE ON SYS.DBMS_AQIN TO Username (Must be performed by Schema if this user owns the ADT.)
When Oracle Application Server ProcessConnect invokes an outbound interaction, messages are enqueued to an Oracle advanced queue for all adapter exchange protocols.
For inbound interactions, the Oracle Advanced Queuing adapter creates a configurable number of threads for each queue and dequeues (blocking) from each queue. Whenever a message is dequeued, the Oracle Advanced Queuing adapter creates an inbound record whose name is based on the naming convention shown in Table 8-9:
As described in "Advanced Queuing Adapter Additional Setup Tasks", the advanced queuing queue and the associated queue table must reside in the same schema.
For the two Oracle object type-based adapter exchange protocols, the following field (column) types are not supported:
PLSQL_INDEX_TABLE
JAVA_OBJECT
JAVA_STRUCT
BFILE
REF
OPAQUE
XMLTYPE
The following advanced queuing-specific features are not supported:
Nonpersistent queues
Rules
Advanced queuing global queues/topics
|
See Also: "Advanced Queuing Adapter Interaction and Record Naming Restrictions" for details about queue naming restrictions |
The Advanced Queuing adapter logs diagnostic messages to the Oracle Application Server ProcessConnect log files in the following situations:
When a connection is established
After a message is enqueued
When an error occurs while enqueuing
When an error occurs while dequeuing
When an XML message cannot be parsed or does not match an Oracle object
The Advanced Queuing adapter does not log diagnostic messages outside of Oracle Application Server ProcessConnect.
The configuration parameter logging level must be set to error (the default setting) for these errors to appear in the log files.
|
See Also: "Oracle Application Server ProcessConnect Middle-Tier Instance Configuration Parameters" for instructions on accessing the configuration parameters through Oracle Enterprise Manager 10g |
The following Problem-Solution pairs make references to database users Username and Schema (defined in "Queue Privileges") and to the delivery channel database connection properties for the hostname, TNS listener port number, and instance name of the application (spoke) database.
Problem:
MessageWriter_enqueue: Could not enqueue message due to database error java.sql.SQLException: ORA-01031: insufficient privileges ORA-06512: at "SYS.DBMS_LOB", line 708 ORA-06512: at line 1
Solution:
The database user Username does not have UPDATE permissions on the queue table.
Problem:
Adapter does not support the interaction description: Enqueue to <chosen-queue>(Message) Adapter does not support the interaction description: Dequeue to <chosen-queue>(Message)
Solution:
There are two potential explanations. The database user Username is either lacking SELECT permissions on the queue table or EXECUTE permissions on the queue ADT (if it is an Oracle Object type queue).
Problem:
Adapter does not support the interaction description: Dequeue to <chosen-queue>(Message)
Solution:
Verify that user Username has been granted DEQUEUE permissions on the queue by user Schema.
Problem:
Adapter does not support the interaction description: Enqueue to <chosen-queue>(Message)
Solution:
Verify that user Username has been granted ENQUEUE permissions on the queue by user Schema.
Problem:
oracle.AQ.AQOracleSQLException: ORA-01031: insufficient privileges ORA-06512: at "SYS.DBMS_AQIN", line 267 ORA-06512: at line 1 at oracle.AQ.AQOracleQueue.enqueue(AQOracleQueue.java:1236)
Solution:
Verify that user Username has been granted ENQUEUE permissions on the queue by user Schema.
Problem:
oracle.AQ.AQOracleSQLException: ORA-06550: line 1, column 7: PLS-00201: identifier ’DBMS_AQIN’ must be declared ORA-06550: line 1, column 7: PL/SQL: Statement ignored at oracle.AQ.AQOracleQueue.enqueue(AQOracleQueue.java:1236)
Solution:
Username must be granted EXECUTE on PL/SQL package SYS.DBMS_AQIN by the SYS user.
Problem:
DBConnection_connect: database error while try to connect to jdbc:oracle:thin:@(description=(address=(host=bstern-sun)(protocol=tcp) (port=1522))(connect_data=(sid=iasdb))) java.sql.SQLException: Io exception: The Network Adapter could not establish the connection at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:185)
or
java.sql.SQLException: ORA-12545: Connect failed because target host or object does not exist at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:185)
or
java.sql.SQLException: ORA-12541: TNS:no listener at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:185)
Solution:
One or both of the database connection parameters for the spoke database hostname or spoke database TNS listener port number are incorrect.
Problem:
DBConnection_connect: database error while try to connect to jdbc:oracle:thin:@(description=(address=(host=bstern-sun)(protocol=tcp) (port=1521))(connect_data=(sid=iasdbb))) java.sql.SQLException: Io exception: Connection refused(DESCRIPTION=(TMP=)(VSNNUM=150999808)(ERR=12505)(ERROR_ STACK=(ERROR=(CODE=12505)(EMFI=4)))) at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:185)
or
DBConnection_connect: database error while try to connect to jdbc:oracle:oci:@(description=(address=(host=bstern-sun)(protocol=tcp) (port=1521))(connect_data=(sid=iasdbb))) java.sql.SQLException: ORA-12505: TNS:listener could not resolve SID given in connect descriptor at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:185)
Solution:
The database connection property instance is incorrect.
Problem:
java.sql.SQLException: ORA-01045: user AQAPP2 lacks CREATE SESSION privilege; logon denied at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:185)
Solution:
The database user Username has not been granted the CONNECT role.
Problem:
java.sql.SQLException: ORA-01017: invalid username/password; logon denied at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:185)
Solution:
Username, Password, or both are incorrect.
Problem:
oracle.AQ.AQOracleSQLException: ORA-25207: enqueue failed, queue AQAPP.ECX_ OUTQUEUE2 is disabled from enqueueing ORA-06512: at "SYS.DBMS_AQIN", line 267 ORA-06512: at line 1 at oracle.AQ.AQOracleQueue.enqueue(AQOracleQueue.java:1236)
Solution:
The Advanced Queuing queue has not been started.
Problem:
oracle.AQ.AQException: JMS-190: Queue AQAPP.ECX_OUTQUEUE3 not found at oracle.AQ.AQUtil.throwAQEx(AQUtil.java:196) at oracle.AQ.AQOracleSession.getQueue(AQOracleSession.java:629)
Solution:
The Advanced Queuing queue no longer exists.
Problem:
MessageWriter_getEnqueueObjectFromXML: Parse exception while building enqueue object: Element ’PAYLOAD’ not expected. MessageWriter_enqueue: Could not enqueue message as it cannot be XML parsed according to it’s definition oracle.xml.parser.v2.XMLParseException: Element ’PAYLOAD’ not expected.
Solution:
The name of the actual payload column of the queue ADT in the database does not match the Oracle Application Server ProcessConnect metadata (’PAYLOAD’ in the example).
Problem:
AQDequeuerAdtLOB_raiseInboundInteraction: Exception while raising inbound AdtLOB interaction javax.resource.ResourceException: Received native event PROCESS_PO_007 but no inbound metadata has been defined for it. at oracle.tip.adapter.aq.inbound.AQDequeuer.lookupInteraction MetaData(AQDequeuer.java:288)
Solution:
The root element of message payload (in the PAYLOAD column) does not match any of the registered inbound interactions with the adapter. Ensure that there is a seeded inbound interaction for the native event (PROCESS_PO_007 in the example).
|
See Also: "Oracle Application Server ProcessConnect Middle-Tier Instance Configuration Parameters" for instructions on accessing the configuration parameters through Oracle Enterprise Manager 10g |
This section provides a brief example of the types of delivery channel and interaction details you must specify to use an Advanced Queuing adapter. For this example, the details are specified for an application named InventoryApp.
Figure 8-10 shows the delivery channel details specified for the Advanced Queuing adapter of the InventoryApp application.
Figure 8-10 Creating an Advanced Queuing Adapter Delivery Channel
|
See Also: "Creating an Advanced Queuing Adapter Delivery Channel" for specific details about creating an Advanced Queuing adapter delivery channel |
The Advanced Queuing adapter requires that you initially log in to the application (spoke) database with the credentials specified in the delivery channel created in Figure 8-10. Click InventoryAppDC to access the database, as shown in Figure 8-11. If successful, inbound and outbound adapter exchange protocols display for selection, as shown in Figure 8-12. If not, an error message appears and the delivery channel parameters shown in Figure 8-10 appear on-screen, enabling you to take corrective actions.
Figure 8-11 Advanced Queuing Adapter Delivery Channel Selection
Figure 8-12 shows the Enqueue to INVENTORYRECEIVERQ(Message) adapter exchange protocol to add for outbound interactions with the Advanced Queuing adapter:
Figure 8-12 Advanced Queuing Adapter Exchange Protocols
Figure 8-13 shows the interaction details to specify for the INVENTORYRECEIVERQ(Message) adapter exchange protocol of the HTTP adapter in the outbound direction.
Figure 8-13 Creating an Advanced Queuing Adapter Outbound Interaction
Figure 8-14 shows the INVENTORYRECEIVERQ(RAW_Record) outbound direction adapter exchange protocol after creation. Click this adapter exchange protocol for additional details. Note the original name of Message shown in Figure 8-12 has been replaced with RAW_Record. This is because you selected a RAW Queue adapter exchange protocol in Figure 8-12.
Figure 8-14 Advanced Queuing Adapter Outbound Adapter Exchange Protocol
|
See Also: "Adding an Advanced Queuing Adapter Interaction" for specific details about creating inbound and outbound Advanced Queuing adapter interactions |
This section provides details about using the E-Mail adapter. This section contains these topics:
|
See Also: "Layout of Adapter Details in this Chapter" for an overview of topics covered for each adapter in this chapter |
The E-Mail adapter enables you to integrate an Oracle E-Mail application with other applications using Oracle Application Server ProcessConnect. This adapter is useful in environments where e-mail uses the Internet Message Access Protocol 4 (IMAP4) and SMTP transport protocols.
The E-Mail adapter can monitor inbound messages in the form of e-mail placed on an IMAP server. The E-Mail adapter is also capable of sending messages to SMTP servers.
Figure 8-15 shows how the E-Mail adapter sends and receives messages.
The E-Mail adapter has been tested with dkimap, an open source IMAP server. Other JavaMail-compliant IMAP4 servers can work with the E-Mail adapter.
You must create a delivery channel to interact with the IMAP server (for inbound interactions) and SMTP server (for outbound interactions) by specifying a series of parameters that describe E-Mail adapter connection information, including SMTP and IMAP server hostnames, IMAP server username and password, SMTP server e-mail addresses, and a polling interval time. These parameter details comprise the delivery channel.
|
See Also: "Creating an E-Mail Adapter Delivery Channel" for the list of parameters you specify to create a delivery channel |
This section identifies and describes when to use the E-Mail adapter exchange protocols. The E-Mail adapter includes the following outbound (to an SMTP server) and inbound (from an IMAP server) adapter exchange protocols shown in Table 8-10:
Table 8-10 E-Mail Adapter Exchange Protocols - Inbound Direction
| Direction | Adapter Interaction | Description |
|---|---|---|
| Inbound | Receive E-Mail(E-MailRecord) | Reads an inbound e-mail message from an IMAP server. |
| Outbound | Send E-Mail(E-MailRecord) | Sends an outbound e-mail message to an SMTP server |
|
See Also:
|
This section describes the IN record element and OUT record element naming conventions for each adapter exchange protocol:
E-Mail Adapter Outbound Interaction and Record Element Naming Conventions
E-Mail Adapter Inbound Interaction and Record Element Naming Conventions
For all outbound interactions with an SMTP server, the interaction name is Send E-Mail. The record name is content_typeRecord.
There is no OUT record.
Table 8-11 describes Send E-Mail record element naming conventions for the E-Mail adapter.
Table 8-11 Send E-Mail Outbound Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
Headers
|
The e-mail header properties for dynamic setting | XML | Adapter | Headers | XSD only |
Subject
|
The e-mail subject text | CLOB | User | None | Cannot be D3L; you typically use token substituted text. |
Payload
|
The body of the e-mail message | Based on answer to Content Type interaction question:
|
User | None | If the value type is CLOB, then D3L cannot be used.
If the value type is XML, then only XSD can be used. |
|
See Also: "E-Mail Adapter Interaction and Record Naming Restrictions" for details about the content type |
For all inbound interactions to an IMAP server, the interaction name is Receive E-Mail. The record name is content_typeRecord. There is no OUT record.
Table 8-12 describes Receive E-Mail record element naming conventions for the E-Mail adapter.
Table 8-12 Receive E-Mail Inbound Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
Headers
|
The header properties from the inbound e-mail | XML | Adapter | Headers | XSD only |
Subject
|
The e-mail subject text | CLOB | User | None | XML or token substituted text |
Payload
|
The body of the e-mail message | Based on answer to Content Type interaction question:
|
User | None | If the value type is CLOB, then D3L cannot be used. D3L can only be used with BLOB.
If the value type is XML, then only XSD can be used. |
|
See Also:
|
The record name is created based on the content type you select when adding an interaction. Table 8-13 lists the available content types and their corresponding record names.
Table 8-13 E-Mail Adapter Interaction and Record Naming Restrictions
| Content Type | Record Name |
|---|---|
| Regular, text attachment | TextRecord |
| XML attachment | XMLRecord |
| Binary attachment | BinaryRecord |
If the same record name is used in the inbound and outbound directions due to the same content type being used for both directions, you must define an event map.
Table 8-14 lists when E-Mail adapter errors occur and how they are handled by the adapter.
The SMTP server and IMAP server must have valid hostnames.
The e-mail address must use the following form:
username@domain
Perform the following tasks for E-Mail adapter testing:
Ensure that you have an IMAP server username and password account.
Ensure that you have an e-mail account to send outbound messages.
Oracle recommends that you use a dedicated IMAP account for each e-mail application.
When Oracle Application Server ProcessConnect invokes an outbound interaction for each adapter exchange protocol, a message is sent to the SMTP server.
For inbound interactions, the E-Mail adapter creates a thread monitoring an Inbox you specified during delivery channel creation.
The adapter listens to Inboxes. Whenever a message is received, the adapter creates a record whose name is based on the endpoint information.
The E-Mail adapter has the following limitations:
IMAP with secure socket layer (SSL) is not supported.
Only IMAP4 is supported. POP3 is not supported.
If you use multiple adapter framework instances at runtime, ensure that only one adapter framework instance is hosting a given party for receiving e-mail (that is, do not allow more than one adapter framework instance to read from a given IMAP account).
The E-Mail adapter logs diagnostic messages to the Oracle Application Server ProcessConnect log files in the following situations:
When an IMAP connection is established
After an e-mail is sent
When an error occurs while sending an e-mail
When the IMAP servers being listened to are listed at startup
When an error occurs while retrieving an e-mail
The E-Mail adapter does not log diagnostic messages outside of Oracle Application Server ProcessConnect.
|
See Also: "Managing and Monitoring a Middle-Tier Instance from Oracle Enterprise Manager 10g Application Server Control Console" for instructions on setting adapter logging levels with Oracle Enterprise Manager 10g |
An example of sending an alert e-mail with the E-Mail adapter is provided in "Alert E-Mail Message Format".
This section provides details about using the File/FTP adapter. This section contains these topics:
File/FTP Adapter Application Integration and Runtime Behavior
|
See Also: "Layout of Adapter Details in this Chapter" for an overview of topics covered for each adapter in this chapter |
The FTP adapter enables you to integrate an Oracle FTP application with other applications using Oracle Application Server ProcessConnect. This adapter is useful in all environments involving the FTP transport protocol or local file system. The FTP adapter can monitor inbound messages in the form of FTP files placed on a remote FTP server or on local file systems. The FTP adapter also sends files to remote FTP servers.
Figure 8-16 shows how the File/FTP adapter sends and receives files.
You must create a delivery channel to interact with the FTP server or file system by specifying a series of parameters that describe the FTP server hostname, port, username, and password details for FTP mode and the polling interval time and directory location where files are sent or received for both FTP and File modes. These parameter details comprise the delivery channel.
|
See Also: "Creating a File/FTP Adapter Delivery Channel" for the list of parameters you specify to create a delivery channel |
This section identifies and describes when to use the File/FTP adapter exchange protocols. The File/FTP adapter includes the following inbound and outbound adapter exchange protocols for both the File and FTP modes of the File/FTP adapter:
File Adapter Exchange Protocols - Inbound and Outbound Directions
FTP Adapter Exchange Protocols - Inbound and Outbound Directions
|
See Also:
|
Table 8-15 describes the inbound and outbound adapter exchange protocols.
Table 8-16 describes the inbound and outbound adapter exchange protocols.
For all inbound and outbound interactions, the IN record name is file_extensionRecord. There are no OUT records.
Table 8-17 describes File/FTP adapter record element naming conventions for Read File (inbound) and Write File (outbound).
Table 8-17 Read File and Write File Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
Payload
|
The file contents | BLOB | User | None | None |
The record name is formed based on the file extension you choose when adding an interaction. Therefore, there is one record name for each extension. You can use event maps to handle different types of native messages that use the same file extension. If the same record name is used in the inbound and outbound directions due to the same file extension being chosen for inbound and outbound, you must define an event map.
Table 8-18 lists when File/FTP adapter errors occur and how they are handled by the adapter.
Table 8-18 File/FTP Adapter Errors
| An Error Occurs While... | Adapter Error Handling Behavior |
|---|---|
| Establishing an FTP connection | Displays the following error: CouldNotConnectFTP
|
| Retrieving a file | Aborts and retries every 30 seconds |
| Sending a file | Logs an error code based on the appropriate file system or FTP error code |
Follow these conventions when naming FTP file names:
Do not include special characters (for example, ^, &, and *) in the file name. Use a conventional alphanumeric combination to name files.
File names must be less than 30 characters in length.
Ensure that you have satisfied the following requirements for File/FTP adapter testing:
If using the File/FTP adapter in FTP mode, ensure that you have an FTP server username and password account.
If you use the staging directory in FTP mode, ensure that it exists.
When Oracle Application Server ProcessConnect invokes an outbound interaction, messages are sent as a file to a file system or an FTP server for each adapter exchange protocol.
For inbound interactions, the File/FTP adapter creates one thread for each file or FTP receiving endpoint. After Oracle Application Server ProcessConnect has retrieved and successfully processed a file, the file is deleted
Secure FTP and FTP/S (FTP over SSL) are not supported.
If you use multiple adapter framework instances at runtime, ensure that only one adapter framework instance is hosting a given party for reading files; that is, do not allow more than one adapter framework instance to read from a given directory.
The File/FTP adapter logs diagnostic messages to the Oracle Application Server ProcessConnect log files in the following situations:
When an FTP connection is established
After a message is sent as a file
When an error occurs while sending a file
When the file or FTP directories being listened to are listed at startup
When an error occurs while retrieving a file
The File/FTP adapter does not log diagnostic messages outside of Oracle Application Server ProcessConnect.
|
See Also: "Managing and Monitoring a Middle-Tier Instance from Oracle Enterprise Manager 10g Application Server Control Console" for instructions on setting adapter logging levels with Oracle Enterprise Manager 10g |
An example of using the File/FTP adapter is provided in Chapter 7, " Tutorial of an Integration within an Enterprise".
This section provides details about using the HTTP adapter. This section contains these topics:
|
See Also: "Layout of Adapter Details in this Chapter" for an overview of topics covered for each adapter in this chapter |
Use the HTTP adapter to integrate an HTTP or secure HTTP application with other applications using Oracle Application Server ProcessConnect. This adapter is useful in all environments that use the HTTP transport protocol. The HTTP adapter performs the following tasks:
Monitors inbound messages received in the form of HTTP requests to the HTTP adapter servlet
Sends messages to remote Web servers, optionally through a proxy host
The HTTP adapter supports HTTP versions 1.0 and 1.1.
For SSL, the HTTP client layer is based on the Oracle JavaSSL implementation, which may need an Oracle Wallet file if certificate-based client authentication is required. You must provide a wallet that contains the certificate of the certificate authority (CA) that signed the certificate of the server to which you are trying to connect.
The HTTP adapter works and is deployed automatically with the Oracle Application Server Containers for J2EE (OC4J) servlet container in Oracle Application Server. In a non-Oracle environment for the inbound direction, the HTTP adapter servlet can be deployed manually by the user in a J2EE-compliant environment.
The HTTP adapter servlet code does not make use of OC4J-specific features.
For the outbound direction, the HTTP adapter is compatible with all HTTP protocol-compliant HTTP servers.
Figure 8-17 shows how the HTTP adapter sends and receives messages.
You must create a delivery channel by specifying a series of parameters that describe the URL for outgoing messages; the proxy server hostname, port, username, and password; RMI instance name and port; and user authentication details. These parameter details comprise the delivery channel.
|
See Also: "Creating an HTTP Adapter Delivery Channel" for the list of parameters you specify to create a delivery channel |
This section identifies and describes when to use the HTTP adapter exchange protocols. The HTTP adapter includes the inbound and outbound adapter exchange protocols shown in Table 8-19:
Table 8-19 HTTP Adapter Exchange Protocols - Inbound and Outbound Direction
| Direction | Interactions | Description |
|---|---|---|
| Inbound | Receive Payload(PayloadRecord) | Receives a file from an HTTP server |
| Outbound | Send Payload(PayloadRecord,PayloadRecord) | Sends a file to an HTTP server |
|
See Also:
|
This section describes the IN record element and OUT record element naming conventions for each adapter exchange protocol:
HTTP Adapter Inbound Interaction and Record Element Naming Conventions
HTTP Adapter Outbound Interaction and Record Element Naming Conventions
For inbound interactions, the IN record name is HTTPReadrecord_type. The record_type is XMLRecord, TextRecord, or BinRecord.
There is no OUT record.
Table 8-20 describes the Receive Payload record element naming conventions.
Table 8-20 Receive Payload Inbound Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
| Payload | Payload to be received over HTTP | Based on answer to Content Type interaction question:
|
User | None | If the value type is CLOB, D3L cannot be used.
If the value type is XML, only XSD can be used. |
For all outbound interactions, the IN record name is the content_typeRecord.
You can have an OUT record if you choose the content type for the response content type parameter. If a content type is chosen for the response, the OUT record name is based on response_content_typeRecord. The record_type is XMLRecord, TextRecord, or BinRecord.
Table 8-21 describes HTTP adapter record element naming conventions for the Send Payload IN Record outbound interaction.
Table 8-21 Send Payload IN Record Outbound Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
Payload
|
Payload to be sent over HTTP | Based on answer to Content Type interaction question:
|
User | None | If the value type is CLOB, D3L cannot be used.
If the value type is XML, only XSD can be used. |
Table 8-22 describes HTTP adapter record element naming conventions for the Send Payload OUT Record outbound interaction.
Table 8-22 Send Payload OUT Record Outbound Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
Response
|
The response to be received as a result of sending the payload | Based on answer to Content Type interaction question:
|
User | None | If the value type is CLOB, D3L cannot be used.
If the value type is XML, only XSD can be used. |
There is one record name for each content type. You can use an event map to handle different types of native events that use the same content type.
Table 8-23 lists when HTTP adapter errors occur and how they are handled by the adapter.
You must define an event map if the same content type is used in the inbound and outbound directions.
Ensure that the following delivery channel details that you specify are valid:
The root URL for outbound messages is a valid HTTP URL.
The proxy server hostname for outbound messages is valid.
The proxy server port number is a valid port number greater than zero.
The proxy server username and password are valid.
The RMI port matches with the setting in the web.xml file.
The remote username for filtering incoming messages is valid.
The Oracle Wallet location and password are valid (if secure HTTP is used).
The authentication username, password, and security realm for outbound messages are valid.
This section describes the following setup tasks:
Steps 0 through Step 3 describe how to add a user for basic authentication. Steps 5 and 7 describe how to enable secure socket layer (SSL).
Open the orion-application.xml file in the $ORACLE_HOME/j2ee/OC4J_ProcessConnect/application-deployments/integration directory.
Add the following contents after the <principals path="principals.xml" /> line.
<security-role-mapping name="sr_manager"> <group name="managers"/> </security-role-mapping>
Open the jazn-data.xml file in the $ORACLE_HOME/j2ee/OC4J_ProcessConnect/application-deployments/integration directory.
Add the entire <realm> section show in this step to the jazn-data.xml file.
<realm>
<name>ip</name>
<users>
<user>
<name>manager</name>
<display-name>manager</display-name>
<credentials>!welcome</credentials>
</user>
</users>
<roles>
<role>
<name>managers</name>
<display-name>Manager Role</display-name>
<members>
<member>
<type>user</type>
<name>manager</name>
</member>
</members>
</role>
</roles>
</realm>
Ensure that the correct server certificate is in the $ORACLE_HOME/Apache/Apache/conf/ssl.wlt/default directory.
Place the ewallet.p12 file in this directory.
Ensure the following entries in the httpd.conf are correct (you have to add them if they are not there):
SSLWallet file:/<path-to-wallet-directory> SSLWalletPassword <wallet password>
Restart the Oracle HTTP server:
%$ORACLE_HOME/opmn/bin/opmnctl stopall %$ORACLE_HOME/opmn/bin/opmnctl startall
Test the configuration by invoking the following URL:
A diagnostic page appears.
Or, if you enabled SSL with the HTTP adapter in Steps 5 through 7, use HTTPS:
https://hostname:port/integration/transportServletB
The B appended to transportServlet tests that you have correctly configured your environment in the orion-application.xml and jazn-data.xml files. If you do not specify B, the environment configuration is not tested and a more general set of testing details is provided.
|
Note: Do not delete the/tmp/tsvalidation.log file after starting Oracle Enterprise Manager 10g. The information in this file is useful for debugging purposes.
|
Perform the following tasks for HTTP adapter testing:
Ensure the transport servlet is running in OC4J.
Ensure the transport servlet is working and basic authentication is enabled.
Ensure that the adapter framework is running. If it is not, you receive an error saying that the RMI server is not running.
Send a message to the HTTP server from the command prompt:
java oracle.tip.adapter.test.AdapterTest httpout1.properties
When Oracle Application Server ProcessConnect invokes an outbound interaction for each adapter exchange protocol, a message is sent to an HTTP listener.
For inbound interactions, the HTTP adapter creates one thread to monitor messages sent by the transport servlet. Depending on the delivery channel details (remote username used as a party identifier), the message is routed to the appropriate interaction. If the message's party is not found, the message is rejected.
When a post is made to the HTTP adapter (through the transport servlet) during an inbound interaction, the transport servlet returns a message based on whether the message is processed successfully or not.
If a message is unsuccessfully processed, you see the following HTTP response:
TransportServlet RMI Server cannot be contacted!
If a message is processed successfully, the following message is received:
TransportServlet Request has been processed successfully!
If the adapter framework is not started and the servlet is running, you receive the following status 503 error:
TransportServlet RMI Server cannot be contacted!
To see if the transport servlet is deployed correctly, attempt to access the following URL through a browser:
http://hostname:port/integration/servlet/transportServlet
where port can be determined from viewing the $ORACLE_HOME/install/portlist.ini file.
A window appears prompting you for the username and password for the OC4J environment. After you enter the correct username and password, the following diagnostic page appears:
The HTTP adapter has the following limitations:
The transport servlet must be used as the inbound servlet.
For the outbound direction, if the get method is used, the attribute name used is message, and the maximum message size allowed is 8k.
For the outbound direction, if the POST method is used, the message is sent as is; there is no multipurpose internet mail extensions (MIME) packaging support.
Cookies are not supported.
Get is not supported in the inbound direction.
For secure HTTP, only the Oracle Wallet export file is supported.
Only the POST method is supported in the transport servlet.
Only the POST method is supported in the inbound direction.
If you use multiple adapter framework instances at runtime, ensure that only one adapter framework instance is hosting a given party for receiving HTTP requests; that is, do not allow more than one adapter framework instance to read from a given HTTP server.
Oracle supports using Microsoft Internet Information Server (IIS) with the HTTP adapter. This support is provided through use of the OracleAS Proxy Plugin for Microsoft IIS for inbound communications.
The HTTP adapter logs diagnostic messages to the Oracle Application Server ProcessConnect log files in the following situations:
After a message is sent
When an error occurs while sending a message
At startup
The HTTP adapter does not log diagnostic messages outside of Oracle Application Server ProcessConnect.
|
See Also: "Managing and Monitoring a Middle-Tier Instance from Oracle Enterprise Manager 10g Application Server Control Console" for instructions on setting adapter logging levels with Oracle Enterprise Manager 10g |
This section provides a brief example of the types of delivery channel and interaction details you must specify to use an HTTP adapter. For this example, the details are specified for an application named SupplierApp.
Figure 8-18 shows the delivery channel details specified for the HTTP adapter of the SupplierApp application.
|
See Also: "Creating an HTTP Adapter Delivery Channel" for specific details about creating an HTTP adapter delivery channel |
Figure 8-19 shows the two adapter exchange protocols to add for inbound and outbound interactions with the HTTP adapter:
Receive Payload(PayloadRecord) is the adapter exchange protocol to add for inbound interactions.
Send Payload(PayloadRecord, PayloadRecord) is the adapter exchange protocol to add for outbound interactions.
You add one interaction at a time.
Figure 8-20 shows the interaction details specified for the Receive Payload(PayloadRecord) adapter exchange protocol of the HTTP adapter in the inbound direction.
Figure 8-20 Creating an HTTP Adapter Inbound Interaction
Figure 8-21 shows the interaction details specified for the Send Payload(PayloadRecord, PayloadRecord) adapter exchange protocol of the HTTP adapter in the outbound direction.
Figure 8-21 Creating an HTTP Adapter Outbound Interaction
Figure 8-22 shows the Receive Payload(XmlRecord) inbound and Send Payload(XmlRecord) outbound adapter exchange protocols after creation. Click an adapter exchange protocol for details. The original names of PayloadRecord shown in Figure 8-19 have been replaced with XMLRecord. This is because you selected xml as the content type for each interaction.
Figure 8-22 HTTP Adapter Inbound and Outbound Adapter Exchange Protocols
|
See Also: "Adding an HTTP Adapter Interaction" for specific details about creating HTTP adapter interactions |
This section provides details about using the Java Message Service (JMS) adapter. This section contains these topics:
|
See Also: "Layout of Adapter Details in this Chapter" for an overview of topics covered for each adapter in this chapter |
The JMS adapter enables Oracle Application Server ProcessConnect to send and receive messages to and from the queues and topics administered by any JMS provider; the Oracle JMS (OJMS) and MQSeries JMS (IBM) providers are certified with Oracle Application Server ProcessConnect.
The JMS adapter provides benefits over using Advanced Queuing or the MQSeries:
Standards-based
No lock in
One adapter supports multiple vendor implementations
Multiple naming schemes are supported for connection factories, queues, and topics (JNDI, LDAP, and vendor-specific class and user-supplied class names)
The JMS adapter supports the following components:
JMS providers OJMS 8.1.7, 9.0.1.4, 9.2, and IBM MQSeries JMS 5.2 and 5.3
|
Note: When using OJMS with Oracle Database 8.1.7, the bodilessjavax.jms.Message type is not supported (adapter exchange protocol Message Payload).
|
JMS protocol 1.0.1 (inbound and outbound directions)
Other JMS providers may work, but have not been tested and certified, and are not supported.
You must create a delivery channel to interact with the JMS service by specifying a series of parameters that describe the JMS connection and JNDI location details. These parameter details comprise the delivery channel.
|
See Also: "Creating a JMS Adapter Delivery Channel" for the list of parameters you specify to create a delivery channel |
This section identifies and describes when to use the JMS adapter exchange protocols. The JMS adapter supports the following inbound and outbound adapter exchange protocols.
JMS Adapter Exchange Protocols - Outbound Direction
|
See Also:
|
Table 8-24 describes the inbound adapter exchange protocols.
Table 8-24 JMS Adapter Exchange Protocols - Inbound DIrection
| Inbound Direction | Description |
|---|---|
| TextMessage Payload | Interaction description for receiving JMS text messages |
| StreamMessage Payload | Interaction description for receiving JMS stream messages |
| BytesMessage Payload | Interaction description for receiving JMS bytes messages |
| Message Payload | Interaction description for receiving JMS messages (headers and properties only) |
| MapMessage Payload | Interaction description for receiving JMS map messages |
Table 8-25 describes the outbound adapter exchange protocols.
Table 8-25 JMS Adapter Exchange Protocols - Outbound DIrection
| Outbound Direction | Description |
|---|---|
| TextMessage Payload | Interaction description for sending JMS text messages |
| StreamMessage Payload | Interaction description for sending JMS stream messages |
| BytesMessage Payload | Interaction description for sending JMS bytes messages |
| Message Payload | Interaction description for sending JMS messages (headers and properties only) |
| MapMessage Payload | Interaction description for sending JMS map messages |
This section describes the adapter exchange protocol and IN and OUT record element conventions:
Table 8-26 describes the JmsHeaders record element naming conventions for each adapter exchange protocol.
Table 8-26 JmsHeaders Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
JmsHeaders
|
Includes the JMS headers | XML | Adapter | JmsHeaders | XSD only |
Table 8-27 describes the JmsProperties record element naming conventions for each adapter exchange protocol.
Table 8-27 JmsProperties Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
JmsProperties
|
Includes the JMS properties | XML | Adapter | JmsProperties | XSD only |
Table 8-28 describes the Payload record element naming conventions for each adapter exchange protocol.
Table 8-28 Payload Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
Payload
|
The payload to be sent.
This is not present for the MessagePayload adapter exchange protocol and message
|
CLOB if the adapter exchange protocol is TextMessage or MapMessage
BLOB if the adapter exchange protocol is StreamMessage or BytesMessage |
User | None | If the value type is CLOB, then D3L cannot be used. D3L can only be used with BLOB. |
For the MapMessage Payload adapter exchange protocol, you define the Payload record element through an XSD that must match the contents of the MapMessage (property names) and the XML document format into which the JMS adapter converts the MapMessage. For example:
<?xml version="1.0" encoding="US-ASCII"?> <Destination-name> <name-of-map-entry-1 type="String"> string-value-of-map-entry-1 </name-of-map-entry-1> ... <name-of-map-entry-n type="Integer"> string-value-of-map-entry-n </name-of-map-entry-n> </Destination-name>
The value of the type attribute can be Boolean, byte, short, integer, long, float, double, string, and ByteArray.
The example structure defined in the preceding code matches the following JMS Map message:
MapMessage msg = new MapMessage();
msg.setString("name-of-map-entry-1", "string-value-of-map-entry-1");
...
msg.setInt("name-of-map-entry-n", "string-value-of-map-entry-n");
The name of the root element is the same as the destination name parameter entered when adding a JMS adapter interaction.
If the map message entry name is Payload, the MapMessage Payload adapter exchange protocol offers a special case. In this case, the value of the Payload entry is viewed as the entire payload, while the other map message entries are ignored.
|
See Also:
|
It is always the case that you must create event maps if more than one event uses the same record type.
Since the destination name is part of the JMS record names, once a certain record definition is assigned, the record name becomes tied to that definition. Therefore, queues (or topics) with the same name, but which externally can be distinguished by additional characteristics (like schema location) besides the name, must use the same record definition if they both are being used by the JMS adapter.
For example, for Oracle JMS, the queue name PROCESS_QUEUE (text type) can exist both in database schemas ORDER and INVENTORY. However, since the record name for this queue is PROCESS_QUEUE_Text_Record, the same record definition is used for both queues.
Table 8-29 lists when JMS adapter errors occur and how they are handled by the adapter.
Table 8-29 JMS Adapter Errors
| An Error Occurs While... | Adapter Error Handling Behavior |
|---|---|
| Locating a JMS-administered object (for example, factories and destinations | Logs the following error: JNDI exception
|
| Establishing a connection | Logs the following error: CouldNotConnect
|
| Enqueuing | JMS provider library initiates an error message |
| Dequeuing | Retries every 30 seconds |
In this release of Oracle Application Server ProcessConnect, there are no automated or user interface-based means for verifying and validating the correctness of the delivery channel configuration, except when starting the JMS adapter in runtime.
Typical values for the JNDI locations for an OJMS-based setup are as follows:
For the JMS Connection Factory:
java:comp/resource/Ojms/QueueConnectionFactories/qcf
Vendor properties:
blank
where blank indicates to leave the field blank.
For the JMS Destination:
java:comp/resource/Ojms/Queues/$[DestinationName]
Vendor properties:
blank
where the Ojms substring must match the resource provider instance name (See "Instructions for Oracle JMS ".) and blank indicates to leave the field blank.
For an MQSeries JMS-based setup, the same two settings are as follows:
JMS Connection Factory:
com.ibm.mq.jms.MQQueueConnectionFactory
Vendor properties:
QueueManager=my.queue.manager;TransportType=1;Host=...
JMS Destination:
queue:///$[DestinationName]
Vendor properties:
?targetClient=1
This section describes setup tasks to perform in addition to the delivery channel parameter and interaction question tasks that you perform with the Oracle Application Server ProcessConnect user interface tool.
Depending on the method used for locating JMS administrative objects (connection factories and destinations), the following tasks must be performed:
Vendor- and user-specific JAR files must be appended to the adapter class path.
Objects must be bound in a JNDI namespace through pertinent deployment descriptors.
Queues, topics, or both must also be created and enabled in the third-party queuing system. Pertinent third-party listeners, channels, daemons, and so on must also be started.
Add an OJMS resource provider instance through Oracle Enterprise Manager 10g.
|
Note: Do not add an OJMS resource provider instance by editing theapplication.xml file. Use Oracle Enterprise Manager 10g to add a provider.
|
Log in to the Oracle Enterprise Manager 10g Application Server Control Console.
Select the Oracle Application Server ProcessConnect middle tier instance in which to add the JMS resource provider.
Click OC4J_ProcessConnect in the System Components section of the Application Server : middle_tier_instance page.
Click Administration.
The OC4J: OC4J_ProcessConnect page appears.
The Data Sources page appears.
Click Data Sources. You must create a data source before you can add a JMS provider.
The Create Data Source page appears.
Select a data source and click Create.
Follow the on-screen instructions to add connectivity details (username, password, and URL) and a JNDI location.
Click Create when done.
Return to the OC4J: OC4J_ProcessConnect page shown in Step 4.
Click JMS Providers.
Click Add new JMS Provider.
Follow the on-screen instructions to add the JMS provider and JNDI location. The JNDI location you enter here is the same one as specified in Step 7.
Exit Oracle Enterprise Manager 10g.
Ensure the following files are available in the CLASSPATH of the JMS adapter (that is, the adapter framework instance):
jndi.properties META-INF/application-client.xml
The middle-tier directory $ORACLE_HOME/ip/config is typically part of the adapter framework CLASSPATH after installing the product, so these files are preinstalled in this directory. You can customize the jndi.properties file to point to any given OC4J instance, where the OJMS resource provider instance in "Instructions for Oracle JMS " was installed. Upon installation, it points by default to the Oracle Application Server ProcessConnect OC4J instance, which runs the design time Oracle Application Server ProcessConnect user interface tool.
If you want to customize jndi.properties to point to another OC4J instance, you must modify the second line:
java.naming.provider.url= opmn:ormi://myhost:6101:OC4J_ProcessConnect
In addition, the third and fourth lines (principal/credentials) must be assigned values that match either values in principals.xml or jazn-data.xml on the OC4J server configuration ($J2EEHOME/config), for example:
principals.xml:
<principals>
...
<users>
<user username="admin" password="abc123">
<group-membership group="administrators" />
</user>
...
jndi.properties:
... java.naming.security.principal=admin java.naming.security.credentials=abc123
Perform the following steps to enable the JMS adapter to communicate with the IBM MQSeries JMS Service:
Install an MQSeries client (or server) on the host where the JMS adapter runs. See the IBM MQSeries documentation for instructions on installing the MQSeries client (or server) software.
Add the MQSeries JMS jar files to the adapter framework CLASSPATH:
Add the following jar files to the middle-tier $ORACLE_HOME/opmn/conf/opmn.xml file:
/opt/mqm/java/lib/jms.jar /opt/mqm/java/lib/connector.jar /opt/mqm/java/lib/com.ibm.mqjms.jar /opt/mqm/java/lib/com.ibm.mq.jar
|
Note: The exact location of these IBM jar files may vary depending on the MQSeries version and the installation choices. |
Perform this task by modifying the Oracle Process Management and Notification (OPMN) configuration in Oracle Enterprise Manager 10g or by directly modifying the following section in the opmn.xml file:
<ias-component id="ProcessConnect" status="enabled"> <environment> ... <variable id="CLASSPATH" value="$ORACLE_HOME/ip/lib/ip.jar" append="true"/> <variable id="CLASSPATH" value="/opt/mqm/java/lib/jms.jar" append="true"/> ...
Add any additional jar files in a similar fashion.
Restart the adapter framework instance for the modified CLASSPATH to take effect.
When Oracle Application Server ProcessConnect invokes an outbound interaction, a JMS message is enqueued to a queue or published to a topic for each adapter exchange protocol.
For inbound interactions, the JMS adapter creates a pool of threads for each queue and topic and consumes (blocks) from each inbound destination for each adapter exchange protocol. If the JMS service provider supports JMS message listener's (like OJMS), then the inbound threads are suspended until a message is ready for consumption, at which point the JMS provider notifies the inbound thread (controlled by the inbound direction interaction parameter Use JMS message listener? set in Step 1 of "Inbound Direction").
When the JMS Adapter has received an inbound message, the JMS adapter creates a record whose name is defined in "JMS Adapter Design-Time Tasks".
The JMS adapter does not support the JMS ObjectMessage message type:
(javax.jms.ObjectMessage)
For the OJMS provider, the ADTMessage message type is not specifically supported. The underlying physical advanced queuing queue must be an Object type queue based on one of these (OJMS-specific) ADTs for the OJMS provider:
SYS.AQ$_JMS_TEXT_MESSAGE
SYS.AQ$_JMS_BYTES_MESSAGE
SYS.AQ$_JMS_MAP_MESSAGE
SYS.AQ$_JMS_STREAM_MESSAGE
SYS.AQ$_JMS_MESSAGE (Not supported with Oracle 8.1.7)
The JMS adapter logs diagnostic messages to the Oracle Application Server ProcessConnect log files in the following situations:
When an administered JMS object is located or instantiated
When a JMS connection is established
When a JMS session is created
After a message is enqueued or dequeued
When an error occurs while enqueuing a message
When the queues being listened to are listed at startup
When an error occurs while dequeuing
The JMS adapter does not log diagnostic messages outside of Oracle Application Server ProcessConnect.
|
See Also: "Managing and Monitoring a Middle-Tier Instance from Oracle Enterprise Manager 10g Application Server Control Console" for instructions on setting adapter logging levels with Oracle Enterprise Manager 10g |
This section provides a brief example of the types of delivery channel and interaction details you must specify to use a JMS adapter. For this example, the details are specified for an application named OrderProcurementApp.
Figure 8-23 shows the delivery channel details specified for the JMS adapter of the OrderProcurementApp application.
|
See Also: "Creating a JMS Adapter Delivery Channel" for specific details about creating a JMS adapter delivery channel |
Figure 8-24 shows the two adapter exchange protocols to add for inbound and outbound interactions with the JMS adapter:
Consume a message(JMS Text Message) is the adapter exchange protocol to add for inbound interactions.
Produce a message(JMS Text Message) is the adapter exchange protocol to add for outbound interactions.
You add one interaction at a time.
Figure 8-25 shows the interaction details specified for the Consume a message(JMS Text Message) adapter exchange protocol of the JMS adapter in the inbound direction.
Figure 8-25 Creating a JMS Adapter Inbound Interaction
Figure 8-26 shows the interaction details specified for the Produce a message(JMS Text Message) adapter exchange protocol of the JMS adapter in the outbound direction.
Figure 8-26 Creating a JMS Adapter Outbound Interaction
Figure 8-27 shows the Consume a message(SupplierPOQueue_Text_Record) inbound direction and Produce a message(ReqReceiverQueue_Text_Record) outbound direction adapter exchange protocols after creation. Click a specific adapter exchange protocol for additional details. A third adapter exchange protocol (Produce a message(SupplierResQ_Text_Record)) that is not described in this use case has also been created. Note the original names of JMS Text Message shown in Figure 8-24 have been replaced with the JMS queue or topic names you specified for each interaction.
Figure 8-27 JMS Adapter Inbound and Outbound Adapter Exchange Protocols
|
See Also: "Adding a JMS (Java Message Service) Adapter Interaction" for specific details about creating inbound and outbound JMS adapter interactions |
This section provides details about using the Oracle Database adapter. This section contains these topics:
Oracle Database Adapter Application Delivery Channel Description
Oracle Database Adapter Interaction and Record Naming Restrictions
Oracle Database Adapter Application Integration and Runtime Behavior
Oracle Database Adapter Use Case
|
See Also: "Layout of Adapter Details in this Chapter" for an overview of topics covered for each adapter in this chapter |
The Oracle Database adapter enables you to integrate an Oracle application, typically PL/SQL-based, with other applications using Oracle Application Server ProcessConnect. This adapter is useful in all environments involving Oracle database applications.
The Oracle Database adapter supports Oracle database server versions 8.1.7, 9.0.1, and 9.2.0 as the application (spoke) database. The application database is a separate database from the Oracle Application Server Metadata Repository. This repository contains the Oracle Application Server ProcessConnect schema and modeling metadata and profile data that you create with the Oracle Application Server ProcessConnect user interface tool.
An application represents a database user within a particular database server. To interact with the database server, you must specify delivery channel parameters, including database server hostname and JDBC driver details, a connection username and password, and a username for the objects being selected in the database server. These parameter details comprise the delivery channel.
|
See Also: "Creating an Oracle Database Delivery Channel" for the list of parameters you specify to create a delivery channel |
This section identifies and describes when to use the Oracle Database adapter exchange protocols. The Oracle Database adapter includes the following inbound and outbound adapter exchange protocols:
Oracle Database Adapter Exchange Protocols - Inbound Direction
Oracle Database Adapter Exchange Protocols - Outbound Direction
|
See Also:
|
Read Record from Interface Table
This adapter exchange protocol supports reading records by specifying a SQL query against an interface table. An interface table is typically defined separately from the database application schema and populated using some mechanism, such as a trigger, from the application schema. However, the protocol can be used directly against an application schema table.
The Oracle Database adapter periodically issues a user-defined query statement for the table and converts each row returned to a record to be created as a native event. If the native event is created successfully, then the Oracle Database adapter issues an UPDATE or DELETE statement for the row to mark it as processed; this prevents it from being processed again.
Use this adapter exchange protocol in the following situations:
A record is to be read from a table or view row.
The record is defined by the columns belonging to the interface table, or a subset of those columns. Joins to other tables are not supported in the query. However, this task is achieved by defining a view and using the view as the interface table.
The row values remain relatively constant. For example, if a row is inserted into the table and the row is subsequently updated, the Oracle Database adapter can process the record at any time. This means that the row can be processed as it was inserted or updated depending on when the Oracle Database adapter issues the query.
The connection specified by the delivery channel has SELECT and UPDATE or DELETE privileges on the table or view.
Write Record to Table
This adapter exchange protocol supports inserting or updating a table row with record values. The record is defined by the table columns.
Use this adapter exchange protocol in the following situations:
A record is to be written to a table or view. If a view is selected, and the view is not key-updatable, then define instead of triggers against the view to perform the table updates.
The connection specified by the delivery channel has INSERT, UPDATE, and SELECT privileges on the table.
This adapter exchange protocol supports the invocation of a stored procedure. The set of IN parameters for the procedure forms the IN record. If the procedure has OUT parameters, these form the OUT record for the interaction.
Use this adapter exchange protocol in the following situations:
A record is to be written using a PL/SQL procedure. This adapter exchange protocol can be preferable to the Write Record to Table adapter exchange protocol in cases where the application of the database server requires multiple inserts, updates, or deletes to process the record.
The integration requires invocation of business logic to determine a result or decision based on input parameters.
The connection specified by the delivery channel has EXECUTE privileges on the procedure.
|
See Also:
|
This section describes the adapter exchange protocol and IN and OUT record element conventions.
Table 8-30 provides examples of the naming conventions available for selection for adapter exchange protocols in the Oracle Application Server ProcessConnect user interface tool.
Table 8-30 Adapter Exchange Protocol Naming Conventions
| Adapter Exchange Protocol | User Interface Naming Convention |
|---|---|
| Inbound |
|
|
Grouped by the first letter of the table name. For example:
|
| Outbound
|
|
|
Grouped by the first letter of the table name. For example:
|
|
Grouped by package name with unpackaged procedures in a group named No Package Name. For example:
|
Table 8-31 describes Read Record from Interface Table and Write Record to Table record element naming conventions.
Table 8-31 Read Record From Interface Table and Write Record to Table Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
Payload
|
Represents the columns retrieved from a query for the Read Record from Interface Table. For the Write Record to Table, this represents all columns in the table. | XML | Adapter | Schema_Name.Table_Name
|
XSD only |
Table 8-32 describes the Stored Procedure Invocation IN record element naming conventions.
Table 8-32 Stored Procedure Invocation IN Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
Payload
|
Represents all IN and IN OUT arguments of the stored procedure | XML | Adapter | Schema_Name.Package_Name.In
|
XSD only |
Table 8-33 describes the Stored Procedure Invocation OUT record element naming conventions.
Table 8-33 Stored Procedure Invocation OUT Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
Payload
|
Represents all OUT and OUT IN arguments in the stored procedure | XML | Adapter | Schema_Name.Package_Name.Out
|
XSD only |
|
See Also:
|
The interaction record is named for the schema object being accessed. This means that you cannot create two interactions for the same schema and table name in two different databases where the table structure differs.
|
See Also: "Oracle Database Adapter Design-Time Tasks" for details on record naming for the individual adapter exchange protocols |
Table 8-34 lists when Oracle Database adapter errors occur and how they are handled by the adapter.
Table 8-34 Oracle Database Adapter Errors
| An Error Occurs While... | Adapter Error Handling Behavior |
|---|---|
| Establishing a connection | Retries the connection after the retry interval duration. |
| Reading from Table | Logs the database error. |
| Writing to Table | Logs the database error and raises a system exception. |
| Invocation of Stored Procedure | Logs the database error and raises a system exception. |
Adapter exchange protocols typically have requirements that you must satisfy before they can be included and successfully validated in a deployed configuration. Table 8-35 describes the Oracle Database adapter exchange protocol requirements.
Table 8-35 Oracle Database Adapter Validation Prerequisites
| Adapter Exchange Protocol | Description |
|---|---|
| Read Record from Interface Table | If the table does not have a primary key, ensure that the unique columns selected are truly unique. The unique columns are used to update or delete the row after processing. If the columns are not unique, multiple rows can be updated or deleted. This means that rows not yet processed are ignored. Also, ensure that the update column is not a unique column.
If the table has a primary key, the update column must not be one of the primary key columns. The unique columns must be selected as part of the query. If the update option is selected for marking a row as processed, the query must exclude processed rows. For example, consider if the following answers were provided for the Update Column Options interaction question set:
A suitable query is as follows (assuming the status column is initially null):
No constraints must be violated as a result of the update or delete action to mark a processed row. |
| Write Record to Table | If the table does not have a primary key and the update option is used, the user must ensure that the unique columns selected are truly unique. If the columns are not unique, multiple rows can be updated, which may not be desirable.
If the table has any foreign key constraints, the foreign key column values in the record instance must refer to a row in the referenced table. Otherwise, the constraint is violated. Similarly, the record instance values must not violate other constraints defined against the table. |
| Stored Procedure Invocation | There are no additional requirements. |
The Oracle Database adapter requires no additional setup tasks to function. However, integrating the Oracle Database adapter with existing applications may require the creation of additional schema objects, as described in Table 8-36 of "Oracle Database Adapter Application Integration and Runtime Behavior".
Table 8-36 describes the additional schema objects to create when integrating the Oracle Database adapter with existing applications.
Table 8-36 Oracle Database Adapter Setup Tasks
| Adapter Exchange Protocol | Description |
|---|---|
| Read Record from Interface Table | Identify or define the interface table to use. You can use a table from the database application schema. In this case, the connection must support the following:
For example, it may be invalid to delete a purchase order. A true interface table is typically defined separately for the following reasons:
The interface table can then be populated by the database application (for example, using triggers against the database application schema). The interface table can safely have rows updated or deleted without impacting the application. |
| Write Record to Table | As with the Read Record from Interface Table adapter exchange protocol, identify or define the table. If a table from the database application schema is used, the connection must support the INSERT or UPDATE action and the database application must support either new rows being written or existing ones being updated. The SELECT privilege is also required. In the case of update, all columns are updated with values from the record instance. You can also define a separate interface table and define triggers against the interface table to populate the database application schema.
|
| Stored Procedure Invocation | An existing database application stored procedure can perform application-specific behavior. Alternatively, a new stored procedure can be defined that performs a complex update to the application schema. |
This section describes the following Oracle Database adapter features and limitations:
Table 8-37 describes the features and restrictions of each Oracle Database adapter exchange protocol.
Table 8-37 Adapter Exchange Protocol Features and Restrictions
| Adapter Exchange Protocol | Features | Restrictions |
|---|---|---|
| Read Record from Interface Table | Reads from relational or object tables and views |
|
| Write Record to Table | Writes to relational or object tables and views |
|
| Stored Procedure Invocation | Invocations of PL/SQL and PL/SQL wrapped Java procedures |
|
This section describes common problems and describes solutions to these problems.
Problem
The following error appears when adding a Read Record from Interface Table interaction:
An error occurred when adding the Interaction Read record from interface table EMP(EMPRecord). oracle.tip.adapter.api.exception.DomainResourceException : Error creating metadata for the DB adapter ORA-00942: table or view does not exist
Solution
Satisfy the following requirements:
The query specified for the interaction must query against the table selected for the interaction.
The query must not include joins to other tables.
If the database username and schema name differ in the delivery channel, then either qualify the table name with the schema name in the SELECT query or create a synonym for the table for the database user.
Problem
Table rows are being raised multiple times for the Read Record from Interface Table interaction at runtime.
Solution
Satisfy the following requirements:
Ensure that the DELETE or UPDATE operation against the table succeeds; that is, it is not prevented due to privilege issues or constraint failures.
If the UPDATE option is being used, ensure that the query excludes processed rows.
Problem
Repeated failure of the Write Record to Table interaction or Stored Procedure Invocation interaction at runtime.
Solution
The Oracle Database adapter treats all database-related errors as system exceptions, causing the operation to be retried. Examine the database error given in the log file and fix the issue. Common causes and corrective actions are as follows:
If the database is down, restart the database and listener.
If there are a lack of system or object privileges, grant the required privileges to the user.
If the database is out of tablespace, add more tablespace.
If there are constraint failures, modify or disable the constraints.
|
See Also: "Managing and Monitoring a Middle-Tier Instance from Oracle Enterprise Manager 10g Application Server Control Console" for instructions on setting adapter logging levels with Oracle Enterprise Manager 10g |
This section describes how to create an object relational view to resolve a complex relational model.
Consider the following relational schema:
create table contact (
id number(10) not null
, name varchar2(50) not null
, address varchar2(100) not null
, city varchar2(50) not null
, state varchar(2) not null
, zip varchar2(5) not null
, phone varchar2(10)
, constraint contact_pk primary key(id)
)
/
create table purchaseorder (
id number(10) not null
, request_date date
, ship_date date
, ship_to number(10) not null
, bill_to number(10) not null
, constraint purchaseorder_pk primary key(id)
, constraint purchaseorder_shipto_fk foreign key (ship_to) references contact(id)
, constraint purchaseorder_billto_fk foreign key (bill_to) references contact(id)
)
/
create table lineitem (
po_id number(10) not null
, line number(10) not null
, item varchar2(500) not null
, quantity number(10) not null
, price number(10,2) not null
, shipto number(10)
, constraint lineitem_pk primary key(po_id, line)
, constraint lineitem_poid_fk foreign key (po_id) references purchaseorder(id) on delete cascade
)
/
The schema does not permit querying or updating a purchase order including the line items and contact information. This is because joins are not supported. This task can be achieved by defining an object relational view and using the object support that the Oracle database server provides. This permits defining simple and collection object types as a column. This enables the whole purchase order to be selected as a single row from the view.
The following types corresponding to the table structure are created:
create type contact_type as object (
name varchar2(50)
, address varchar2(100)
, city varchar2(50)
, state varchar(2)
, zip varchar2(5)
, phone varchar2(10)
);
/
create type lineitem_type as object (
line number(10)
, item varchar2(500)
, quantity number(10)
, price number(10,2)
, shipto contact_type
);
/
create type lineitem_list as table of lineitem_type
/
create type purchaseorder_type as object (
id number(10)
, request_date date
, ship_date date
, ship_to contact_type
, bill_to contact_type
, lineitems lineitem_list
);
/
contact_type and lineitem_type do not include the id and po_id columns, respectively. This is because the relationship to the purchase order is implicit in the row selected from the view. The object view is then defined using the following types:
create or replace view purchaseorder_objview of purchaseorder_type
with object identifier (id) as
select
po.id
, po.request_date
, po.ship_date
, contact_type(st.name, st.address, st.city, st.state, st.zip, st.phone) ship_to
, contact_type(bt.name, bt.address, bt.city, bt.state, bt.zip, bt.phone) nill_to
, cast(multiset(
select li.line, li.item, li.quantity, li.price
, contact_type(lc.name, lc.address, lc.city, lc.state, lc.zip,
lc.phone) ship_to
from lineitem li, contact lc
where li.po_id = po.id) as lineitem_list) lineitems
from purchaseorder po, contact st, contact bt
where po.ship_to = st.id
and po.bill_to = bt.id
Select this view for the Read Record from Interface Table adapter exchange protocol with a query such as SELECT * FROM purchaseorder_objview. In this case, the view supports write through of a delete action to the base purchaseorder table. If the view is not key-updatable, triggers must be defined.
You can also use the view for the Write Record to Table adapter exchange protocol. If you use the view, you must create instead of triggers on the view to perform the appropriate inserts and updates to the base tables.
An alternative approach is to define an object table that can be written to directly by the adapter. Triggers on this table can maintain the inserts and updates with the relational application schema.
CREATE TABLE purchaseorder_obj OF purchaseorder_type NESTED TABLE lineitems STORE AS lineitems_obj
The application datatypes created from the XML Schema for the view (similar for the object table) are as follows:
USER.PURCHASEORDER_OBJVIEW
ID long
REQUEST_DATE string
SHIP_DATE string
SHIP_TO CONTACT_TYPE
BILL_TO CONTACT_TYPE
LINEITEMS LINEITEM_LIST
CONTACT_TYPE
NAME string
ADDRESS string
CITY string
STATE string
ZIP string
PHONE string
LINEITEM_LIST
LINEITEMS_ITEM LINEITEM_TYPE [0, N]
LINEITEM_TYPE
LINE long
ITEM string
QUANTITY long
PRICE double
SHIPTO CONTACT_TYPE
This section provides details about using the Web Service adapter. This section contains these topics:
Web Service Adapter Application Delivery Channel Description
Web Service Adapter Interaction and Record Naming Restrictions
|
See Also: "Layout of Adapter Details in this Chapter" for an overview of topics covered for each adapter in this chapter |
The Web Service adapter enables you to interact with a Web service operation selected from a Web Service Description Language (WSDL) document.
The Web Service adapter provides support for the components shown in Table 8-38.
Table 8-38 Supported Web Service Adapter Components
| Component | Support Provided |
|---|---|
| WSDL | Web service using WSDL 1.1 with Simple Object Access Protocol (SOAP) bindings |
| Protocols | SOAP used over the HTTP and secure HTTP protocols. The Web Service adapter functions only as a client, and not as a server (that is, only the outbound direction is supported). |
| Applications | Any application wrapped in a Web Service that provides WSDL and SOAP/HTTP bindings |
When creating a delivery channel, you must specify a Web Service port name or URL. The other delivery channel parameters that you specify, such as a proxy server hostname, port, username, and password, and user authentication details, may or may not be required.
|
See Also: "Creating a Web Service Delivery Channel" for the list of parameters you specify to create a delivery channel |
The Web Service adapter includes the Web Service Operation outbound adapter exchange protocol. This adapter exchange protocol supports the selection of a WSDL definition and a specific Web Service operation from that definition. The interaction description is as follows:
Invoke Web Service Operation(RequestRecord,ResponseRecord)
where RequestRecord is the actual request message name and ResponseRecord is the actual response message name.
This example uses a unique interaction name based on concatenation of the following elements:
targetNamespace of the WSDL definition containing the operation
The # character
Operation name
After you have added this interaction, the name displays in the Oracle Application Server ProcessConnect user interface tool in the Details section of the native event type details page and on the Interaction page (See Figure 8-31).
Schemas describing native datatypes are generated automatically by the Web Service adapter and can be viewed by browsing the native datatype repository and by examining the ui.log file (if the adapter logging level is set to information or higher).
|
Note: If the WSDL definition is included in a file instead of a URL, place the file in the$ORACLE_HOME/ip/import directory. This makes the file available for selection when you add a Web Service adapter interaction.
|
|
See Also:
|
Records are named according to their associated interaction. This is because they contain operation-specific metadata in their annotations and this is the convention with SOAP. The IN record name is the same as the interaction name.
The OUT record name is the concatenation of the following elements:
The IN record name
The string Response
Table 8-39 describes Web Service adapter IN record element naming conventions.
Table 8-39 Web Service Operation IN Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
Message_Part_Name
|
Input message part to Web Service | XML | Adapter | NS#WSDL _ Message_Part_Name
|
XSD only |
n record elements, where n is any number.Table 8-40 describes Web Service adapter OUT record element naming conventions.
Table 8-40 Web Service Operation OUT Record Element Naming Conventions
| Record Element Name | Description | Value Type | Definition Provided By User or Adapter | Native Datatype Name for Adapter-Provided Definition | Native Format Restrictions |
|---|---|---|---|---|---|
Message_Part_Name
|
Output message part to Web Service | XML | Adapter | NS#WSDL _ Message_Part_NameResponse
|
XSD only |
The value NS in Table 8-39 and Table 8-40 reflects a namespace value that depends on the type of the message part:
If the message part has an xsd primitive type (for example, xsd:int or xsd:string), the namespace used is the WSDL target namespace.
If the message part has a type that is described by a schema within the WSDL, the namespace used is the schema target namespace.
For example, an interaction generated from the following WSDL fragment:
<definitions
name="oracle.tip.adapter.ws.test.HotelImpl"
targetNamespace="http://oracle/tip/adapter/ws/test/HotelImpl.wsdl"
xmlns="http://schemas.xmlsoap.org/wsdl/"
…
<operation name="getDetails"
<input name="getDetails1Request" message="tns:getDetails1Request"/>
<output name="getDetails1Response" message="tns:getDetails1Response"/>
</operation>
…
</definitions>
is named:
http://oracle/tip/adapter/ws/test/HotelImpl.wsdl#getDetails
with an IN record named:
http://oracle/tip/adapter/ws/test/HotelImpl.wsdl#getDetails
and an OUT record named:
http://oracle/tip/adapter/ws/test/HotelImpl.wsdl#getDetailsResponse
The interaction name appears in the Interactions page of the Oracle Application Server ProcessConnect user interface tool as follows:
Web Service Adapter
Web Service
http://oracle/tip/adapter/ws/test/HotelImpl.wsdl#getDetails(http://oracle/tip/adapter/ws/test/HotelImpl.wsdl#getDetails,http://oracle/tip/adapter/ws/test/ HotelImpl.wsdl#getDetailsResponse)
XML is the native format of all Web Service IN and OUT record elements. XML is the only native format that you can select.
Two different Web services implemented by different providers with the same namespace and operation, but with different inputs and outputs, cannot be used together.
This section describes Web Service adapter errors that can occur.
Two types of errors can occur during WSDL definition processing:
Domain errors
All definitions are removed during WSDL processing
Too many rounds of questions (ten or more) to choose a unique operation
System errors
Fetching a WSDL (or its imports) using a URL
Two types of errors can occur during execution:
Domain errors can occur in the following cases:
If the SOAP request message cannot be constructed from the input Oracle record based on the information specified during interaction questioning (for example, the number of record elements does not equal the number of message parts)
If the connection details cannot be used to obtain an HTTP connection (that is, the name or URL of the Web Service port string does not start with http: or https:, and is not listed in PortInfo). Failures to actually connect are reported as system errors.
If the output Oracle record cannot be constructed from the SOAP response message (for example, the response contained a SOAP FAULT that was not declared in the WSDL)
System errors can occur in the following cases:
Errors that occur from the time that a connection is requested, until the last response byte is read from the wire message. Some of these errors are likely transient. Use caution when issuing a retry (for example, limit the number and frequency of retries, and be aware that the remote Web service can possibly be invoked more than once.
Ensure that the Web Service port name or URL delivery channel parameter setting that you specify matches with that listed in the WSDL file.
This section describes setup tasks to perform in addition to the delivery channel parameter and interaction question tasks that you perform with the Oracle Application Server ProcessConnect user interface tool.
A Web Service interaction (accessed through a native role) cannot be used until the following tasks have been performed:
A port (represented by an application party and associated delivery channel) is configured
That port is configured with the native role by an application agreement
If the port present in the WSDL definition defines the interaction, the name or URL of the port delivery channel parameter must be set to the port name. If the port was not present in the WSDL file, but you obtained a WSDL definition for a port that references the interaction operation through the same binding, you can provide the new party’s URL (found in the <soap:address> element) as the value of the name or URL of the Web Service port parameter when configuring the new application party. You can then use existing interactions by defining an agreement between the new party and existing native roles that use the existing interactions.
The Web Service adapter includes the following restrictions:
The schema for each message part, and therefore for each Oracle record element, must not reference elements or types from any namespace other than its own targetNamespace and the XML Schema (xsd) namespace. For example, operations that use SOAP Section 5 array encoding to transmit parameters or results are not supported.
Overloaded operations (operations with the same name, but different parameter types) are not supported.
Inbound communication is not supported.
The underlying SOAP stack is Apache SOAP. A Web service that does not interoperate with Apache SOAP cannot interoperate with the Web Service adapter.
The schema for each message part, and therefore for each Oracle record element, must not reference the XML Schema (xsd) any or anyType elements, or any unsupported schema constructs.
The Web Service adapter provides the following logging capabilities.
The following logging occurs during processing of a WSDL definition (modeling):
A WARNING entry for each WSDL element that is removed from further consideration:
A schema import, element, or type definition is removed if it references a namespace other than its own target namespace or the xsd and xsi namespaces. This means that SOAP-encoded arrays are not supported because those definitions are in a different namespace.
A message is removed if part of it refers to an unknown type. Known types are the xsd:primitive types and nonremoved global types and elements defined in schemas.
A binding operation is removed if it refers to an unknown (removed) message.
A binding is removed if it is not a supported SOAP/HTTP binding, or if all of its operations have been removed.
A port is removed if it refers to an unknown binding.
A service is removed if all its ports are removed.
INFORMATION entries for each WSDL document processed, showing nonremoved elements
EXCEPTION entries for errors occurring during processing of the current WSDL document. WSDL text showing all elements (removed or not) is logged.
The following logging occurs during execution (in the adapter framework):
INFORMATION entries for the SOAP envelope (request and response)
EXCEPTION entries for OperationInfo, PortInfo, and SOAP envelope (request and response)
|
See Also: "Managing and Monitoring a Middle-Tier Instance from Oracle Enterprise Manager 10g Application Server Control Console" for instructions on setting adapter logging levels with Oracle Enterprise Manager 10g |
This section provides a brief example of the types of delivery channel and interaction details you must specify to use a Web Service adapter.
Figure 8-28 shows the delivery channel details to specify for the Web Service adapter.
|
See Also: "Creating a Web Service Delivery Channel" for specific details about creating a Web Service adapter delivery channel |
Figure 8-29 shows the Invoke Web Service Operation(RequestRecord, ResponseRecord) adapter exchange protocol to add for outbound interactions with the Web Service adapter:
Figure 8-30 shows the interaction details to specify for the Invoke Web Service Operation(RequestRecord, ResponseRecord) adapter exchange protocol of the Web Service adapter in the outbound direction. More than one page of questions can appear.
Figure 8-30 Creating a Web Service Adapter Outbound Interaction
Figure 8-31 shows a portion of the outbound direction adapter exchange protocol after creation. Click this adapter exchange protocol for additional details. Note the original name of RequestRecord shown in Figure 8-29 has been replaced with the URL to the WSDL file specified in Figure 8-30. The name of ResponseRecord shown in Figure 8-29 has also been replaced with this URL to the specified WSDL file. In addition, however, the word Response is appended to the end.
Figure 8-31 Web Service Adapter Outbound Adapter Exchange Protocol
|
See Also: "Adding a Web Service Adapter Interaction" for specific details about creating an outbound Web Service adapter interaction |
This chapter describes the following details about the Advanced Queuing, E-Mail, File/FTP, HTTP, JMS, Oracle Database, and Web Service technology adapters:
Benefits of using the adapter
Supported versions
Application delivery channel descriptions
Adapter exchange protocols
Design-time tasks
Interaction and record naming restrictions
Errors
Validation prerequisites
Additional setup tasks
Application integration and runtime behavior
Limitations
Diagnostics and troubleshooting
Use cases
