10g (9.0.4)
Part Number B12121-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle® Application Server ProcessConnect User's Guide 10g (9.0.4) Part Number B12121-01 |
|
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.
| 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. |
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:
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.
| Native Format | XML Value Type | CLOB Value Type | BLOB Value Type |
|---|---|---|---|
|
XSD |
Yes |
Yes |
Yes |
|
Token substituted text |
No |
Yes |
Yes |
|
D3L |
No |
No |
Yes |
This section provides details about using the Advanced Queuing adapter. This section contains these topics:
"Layout of Adapter Details in this Chapter" for an overview of topics covered for each adapter in this chapter
See Also:
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.
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.
|
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-5 describes RAW Queue record element naming conventions.
Table 8-6 describes Oracle Object Queue record element naming conventions.
Table 8-7 describes 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 |
|---|---|---|---|---|---|
|
|
Includes the advanced queuing headers |
XML |
Adapter |
AQ-Headers |
XSD only |
|
Object_Type _Name |
Includes the nonpayload fields of the object type |
XML |
Adapter |
Object_Type_Name |
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. |
|
|
|
|
|
|
|
|
1
There can be one to n record elements, where n is any number. |
|
See Also:
"Wire Messages and Oracle Records" for conceptual details about Oracle records. |
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.
|
See Also:
"Advanced Queuing Adapter Design-Time Tasks" for additional details on record naming |
Table 8-8 lists when Advanced Queuing adapter errors occur and how they are handled by the adapter.
| An Error Occurs While... | Adapter Error Handling Behavior |
|---|---|
|
Establishing a connection |
Displays the following error: 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 re-establish 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 kind of validation error is unrecoverable. 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.
CONNECT
CREATE TYPE
GRANT EXECUTE ON QueueADT TO Schema
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)
CONNECT
RESOURCE
AQ_ADMINISTRATOR_ROLE
GRANT SELECT ON QueueTableName TO Username
GRANT UPDATE ON QueueTableName TO Username
DBMS_AQADM.GRANT_QUEUE_PRIVILEGE (privilege => 'DEQUEUE',queue_name => ' QueueName' ,grantee => ' Username' , grant_option => FALSE);
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)
CONNECT
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:
| Adapter Exchange Protocol | Oracle Record Name |
|---|---|
|
RAW Queue |
|
|
Oracle Object Queue |
|
|
Oracle Object Queue with payload fields |
|
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:
The following advanced queuing-specific features are not supported:
"Advanced Queuing Adapter Interaction and Record Naming Restrictions" for details about queue naming restrictions
See Also:
The Advanced Queuing adapter logs diagnostic messages to the Oracle Application Server ProcessConnect log files in the following situations:
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 |
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 |
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.
|
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-12 shows the Enqueue to INVENTORYRECEIVERQ(Message) adapter exchange protocol to add for outbound interactions with the Advanced Queuing adapter:
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-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.
|
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:
"Layout of Adapter Details in this Chapter" for an overview of topics covered for each adapter in this chapter
See Also:
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:
|
See Also:
|
This section describes the IN record element and OUT record element naming conventions for each adapter exchange protocol:
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.
|
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.
|
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.
| 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:
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:
The E-Mail adapter logs diagnostic messages to the Oracle Application Server ProcessConnect log files in the following situations:
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 Application Server Control" for instructions on setting adapter logging levels with Oracle Enterprise Manager |
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:
"Layout of Adapter Details in this Chapter" for an overview of topics covered for each adapter in this chapter
See Also:
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:
See Also:
Table 8-15 describes the inbound and outbound adapter exchange protocols.
| Direction | Adapter Exchange Protocol | Description |
|---|---|---|
|
Inbound |
Read File(FileRecord) |
Retrieves a file from a directory |
|
Outbound |
Write File(FileRecord) |
Places a file into a directory |
Table 8-16 describes the inbound and outbound adapter exchange protocols.
| Direction | Adapter Exchange Protocol | Description |
|---|---|---|
|
Inbound |
Read File(FileRecord) |
Retrieves a file from an FTP server |
|
Outbound |
Write File(FileRecord) |
Places a file onto an FTP server |
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).
.
|
See Also:
"Wire Messages and Oracle Records" for conceptual details about Oracle records. |
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.
Follow these conventions when naming FTP file names:
Ensure that you have satisfied the following requirements for File/FTP adapter testing:
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
The File/FTP adapter logs diagnostic messages to the Oracle Application Server ProcessConnect log files in the following situations:
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 Application Server Control" for instructions on setting adapter logging levels with Oracle Enterprise Manager |
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:
"Layout of Adapter Details in this Chapter" for an overview of topics covered for each adapter in this chapter
See Also:
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:
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:
| 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:
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.
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-22 describes HTTP adapter record element naming conventions for the Send Payload OUT Record outbound interaction.
|
See Also:
"Wire Messages and Oracle Records" for conceptual details about Oracle records. |
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:
web.xml file.
This section describes the following setup tasks:
Steps 1 through Step 3 describe how to add a user for basic authentication. Steps 5 and 7 describe how to enable secure socket layer (SSL).
jazn-data.xml file in the $ORACLE_HOME/j2ee/OC4J_ProcessConnect/application-deployments/integration directory.
"principals" tag.
<principals path="principals.xml" /> <security-role-mapping name="sr_manager"> <group name="managers"/> </security-role-mapping>
orion-application.xml file in the $ORACLE_HOME/j2ee/OC4J_ProcessConnect/application-deployments/integration directory.
<users> and <roles> elements and change <credential> to the appropriate password.
<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>
$ORACLE_HOME/Apache/Apache/conf/ssl.wlt/default directory.
ewallet.p12 file in this directory.
httpd.conf are correct (you have to add them if they are not there):
SSLWallet file:/<path-to-wallet-directory> SSLWalletPassword <wallet password>
%$ORACLE_HOME/opmn/bin/opmnctl stopall %$ORACLE_HOME/opmn/bin/opmnctl startall
https://hostname:4443/integration/transportServlet
A diagnostic page appears.
Perform the following tasks for HTTP adapter testing:
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 HTTP adapter logs diagnostic messages to the Oracle Application Server ProcessConnect log files in the following situations:
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 Application Server Control" for instructions on setting adapter logging levels with Oracle Enterprise Manager |
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:
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-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-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.
|
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:
"Layout of Adapter Details in this Chapter" for an overview of topics covered for each adapter in this chapter
See Also:
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:
The JMS adapter supports the following components:
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.
See Also:
Table 8-24 describes the inbound adapter exchange protocols.
Table 8-25 describes the outbound adapter exchange protocols.
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-27 describes the JmsProperties record element naming conventions for each adapter exchange protocol.
Table 8-28 describes the Payload record element naming conventions for each adapter exchange protocol.
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.
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:
java:comp/resource/Ojms/QueueConnectionFactories/qcf
blank
where blank indicates to leave the field blank.
java:comp/resource/Ojms/Queues/$[DestinationName]
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:
com.ibm.mq.jms.MQQueueConnectionFactory
QueueManager=my.queue.manager;TransportType=1;Host=...
queue:///$[DestinationName]
?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:
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.
The OC4J: OC4J_ProcessConnect page appears.
The Data Sources page appears.
The Create Data Source page appears.
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.
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:
CLASSPATH:
$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
Perform this task by modifying the Oracle Process Management and Notification (OPMN) configuration in Oracle Enterprise Manager 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"/> ...
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:
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 Application Server Control" for instructions on setting adapter logging levels with Oracle Enterprise Manager |
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:
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-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-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.
|
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:
"Layout of Adapter Details in this Chapter" for an overview of topics covered for each adapter in this chapter
See Also:
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:
See Also:
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:
SELECT and UPDATE or DELETE privileges on the table or view.
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:
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:
EXECUTE privileges on the procedure.
See Also:
http://otn.oracle.com
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-31 describes Read Record from Interface Table and Write Record to Table record element naming conventions.
Table 8-32 describes the Stored Procedure Invocation IN record element naming conventions.
Table 8-33 describes the Stored Procedure Invocation OUT record element naming conventions.
|
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.
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.
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.
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.
The Oracle Database adapter currently only works with the Oracle database.
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:
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:
DELETE or UPDATE operation against the table succeeds; that is, it is not prevented due to privilege issues or constraint failures.
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:
"Managing and Monitoring a Middle-Tier Instance from Oracle Enterprise Manager Application Server Control" for instructions on setting adapter logging levels with Oracle Enterprise Manager
See Also:
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:
"Layout of Adapter Details in this Chapter" for an overview of topics covered for each adapter in this chapter
See Also:
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.
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:
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).
|
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:
Table 8-39 describes Web Service adapter 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 |
|
|
|
|
|
|
|
|
1
There can be one to n record elements, where n is any number. |
Table 8-40 describes Web Service adapter 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_Name |
XSD only |
|
|
|
|
|
|
|
|
1
There can be one to n record elements, where n is any number. |
The value NS in Table 8-39 and Table 8-40 reflects a namespace value that depends on the type of the message part:
xsd primitive type (for example, xsd:int or xsd:string), the namespace used is the WSDL 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 AdapterWeb Servicehttp://oracle/tip/adapter/ws/test/HotelImpl.wsdl#getDetails(http://oracl e/tip/adapter/ws/test/HotelImpl.wsdl#getDetails,http://oracle/tip/adapte r/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.
|
See Also:
"Wire Messages and Oracle Records" for conceptual details about Oracle records. |
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:
Two types of errors can occur during execution:
http: or https:, and is not listed in PortInfo). Failures to actually connect are reported as system errors.
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:
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:
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.
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):
xsd and xsi namespaces. This means that SOAP-encoded arrays are not supported because those definitions are in a different namespace.
xsd:primitive types and nonremoved global types and elements defined in schemas.
The following logging occurs during execution (in the adapter framework):
OperationInfo, PortInfo, and SOAP envelope (request and response)
"Managing and Monitoring a Middle-Tier Instance from Oracle Enterprise Manager Application Server Control" for instructions on setting adapter logging levels with Oracle Enterprise Manager
See Also:
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-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.
|
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:
|
 Copyright © 2003 Oracle Corporation. All Rights Reserved. |
|