Xavier technology adapters

Oracle® Fusion Middleware
User's Guide for Technology Adapters
11g Release 1 (11.1.1)
E10231-01
May 2009

Oracle Fusion Middleware User's Guide for Technology Adapters, 11g Release 1 (11.1.1)
E10231-01
Copyright © 2007, 2009, Oracle and/or its affiliates. All rights reserved.
Primary Authors: Brintha Bennet, Sheela Vasudevan, Vimmika Dinesh
Contributor: Amandeep Mahajan, Bo Stern, Srimant Misra, Deepak Agarwal, Raghavendra Chandrashekar,
Stephen Mcritchie, Michael Chiocca, Rod Fernandez, Sunil Gopal, Manas Panda, Sagar Shiruguppi, Vikas
Anand, Sujay Bandyopadhyay, Syed Zarina, Anuj Kaushal, Ashish Mathur, Prateek Maheshwari, Dhaval B
Shah, Sandeep Jain
This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.
If this software or related documentation is delivered to the U.S. Government or anyone licensing it on
behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data
delivered to U.S. Government customers are "commercial computer software" or "commercial technical data"
pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As
such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and
license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of
the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software
License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.
This software is developed for general use in a variety of information management applications. It is not
developed or intended for use in any inherently dangerous applications, including applications which may
create a risk of personal injury. If you use this software in dangerous applications, then you shall be
responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use
of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of
this software in dangerous applications.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks
of their respective owners.
This software and documentation may provide access to or information on content, products, and services
from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all
warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and
its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of
third-party content, products, or services.

iii
Contents
Preface............................................................................................................................................................... xxi
Audience..................................................................................................................................................... xxi
Documentation Accessibility................................................................................................................... xxi
Related Documents .................................................................................................................................. xxii
Conventions .............................................................................................................................................. xxii
Part I Introduction and Concepts
1 Introduction to Oracle JCA Adapters
1.1 Features of Oracle JCA Adapters.............................................................................................. 1-1
1.2 Types of Oracle JCA Adapters.................................................................................................. 1-2
1.2.1 Oracle Technology Adapters ............................................................................................. 1-3
1.2.1.1 Architecture................................................................................................................... 1-4
1.2.1.2 Design-Time Components........................................................................................... 1-4
1.2.1.3 Run-Time Components................................................................................................ 1-7
1.2.1.4 Deployment................................................................................................................... 1-7
1.2.2 Packaged-Application Adapters ....................................................................................... 1-8
1.2.2.1 Architecture................................................................................................................... 1-8
1.2.2.1.1 Application Explorer............................................................................................. 1-9
1.2.2.1.2 BSE........................................................................................................................... 1-9
1.2.2.1.3 J2CA 1.5 Resource Adapter .............................................................................. 1-10
1.2.2.2 Design-Time Components........................................................................................ 1-10
1.2.2.3 Run-Time Components............................................................................................. 1-11
1.2.2.4 Deployment................................................................................................................ 1-11
1.2.3 Legacy Adapters ............................................................................................................... 1-12
1.2.3.1 Architecture................................................................................................................ 1-12
1.2.3.1.1 Oracle Connect.................................................................................................... 1-12
1.2.3.1.2 Oracle Studio....................................................................................................... 1-14
1.2.3.1.3 J2CA Adapter...................................................................................................... 1-14
1.2.3.2 Design-Time Components........................................................................................ 1-14
1.2.3.3 Run-Time Components............................................................................................. 1-15
1.2.3.4 Deployment................................................................................................................ 1-16
1.3 Types of Oracle JCA Adapters Adapter Services................................................................ 1-16
1.3.1 Request-Response (Outbound Interaction) Service..................................................... 1-16
1.3.2 Event Notification (Inbound Interaction) Service........................................................ 1-16

iv
1.3.3 Metadata Service............................................................................................................... 1-17
2 Adapter Life-Cycle Management
2.1 Installing Oracle JCA Adapters ................................................................................................ 2-2
2.2 Starting and Stopping Oracle JCA Adapters .......................................................................... 2-2
2.3 Physically Deploying Oracle JCA Adapters ........................................................................... 2-2
2.4 Adding an Adapter Connection Factory................................................................................. 2-2
2.4.1 Creating a Data Source........................................................................................................ 2-3
2.4.2 Creating a Connection Pool................................................................................................ 2-4
2.5 Handling Deployment Plan When Working on a Remote Oracle SOA Server................. 2-5
2.6 Setting the Trace Level of Oracle JCA Adapters ................................................................... 2-5
2.7 Viewing Adapter Logs ............................................................................................................... 2-7
2.8 Using Header Properties for Oracle JCA Adapters ............................................................... 2-7
2.8.1 The InteractionSpec or ActivationSpec Properties ......................................................... 2-7
2.8.1.1 Oracle AQ Adapter Properties ................................................................................... 2-8
2.8.1.2 Oracle Database Adapter Properties ......................................................................... 2-8
2.8.1.3 Oracle File Adapter Properties................................................................................... 2-8
2.8.1.4 Oracle FTP Adapter Properties .................................................................................. 2-8
2.8.1.5 Oracle JMS Adapter Properties .................................................................................. 2-8
2.8.1.6 Oracle MQ Series Adapter Properties ....................................................................... 2-8
2.8.1.7 Oracle Socket Adapter Properties.............................................................................. 2-8
2.8.2 Endpoint Properties............................................................................................................. 2-9
2.9 Describing XML Data Structure................................................................................................ 2-9
2.10 Error Handling ............................................................................................................................ 2-9
2.10.1 Handling Rejected Messages ............................................................................................. 2-9
2.10.1.1 Configuring Rejection Handlers.............................................................................. 2-10
2.10.1.2 Rejected Message Handlers ..................................................................................... 2-11
2.10.1.3 Checking for Rejected Messages ............................................................................. 2-13
2.10.2 Handling Connection Errors........................................................................................... 2-13
2.10.2.1 Outbound Interaction ............................................................................................... 2-13
2.10.2.1.1 Retryable Exceptions for Outbound Interaction............................................ 2-14
2.10.2.1.2 Nonretryable Exceptions for Outbound Interaction..................................... 2-14
2.10.2.2 Inbound Interaction................................................................................................... 2-15
2.10.2.2.1 Retryable Exceptions for Inbound Interaction............................................... 2-16
2.10.2.2.2 Nonretryable Exceptions for Inbound Interaction ........................................ 2-16
2.10.3 Handling Message Errors................................................................................................ 2-17
2.11 How Oracle JCA Adapters Ensure No Message Loss ........................................................ 2-18
2.11.1 Local Transactions and Global (XA) Transactions....................................................... 2-18
2.11.2 Inbound Transactions....................................................................................................... 2-19
2.11.3 Outbound Transactions ................................................................................................... 2-19
2.12 Streaming Large Payload........................................................................................................ 2-19
2.13 Composite Availability and Inbound Adapters.................................................................. 2-20
2.14 Manually Deploying an Adapter RAR File.......................................................................... 2-20
2.15 Defining Adapter Interface by Importing an Existing WSDL........................................... 2-21
2.16 Creating an Application Server Connection for Oracle JCA Adapters............................ 2-23
2.17 Deploying Oracle JCA Adapter Applications from Oracle JDeveloper .......................... 2-26
2.18 Testing Applications................................................................................................................ 2-27

v
2.19 Batching and Debatching Support ........................................................................................ 2-28
2.20 Migrating Repositories............................................................................................................ 2-28
2.21 Recommended Setting for Data Sources Used by Oracle JCA Adapters ........................ 2-28
3 Adapter Integration with Oracle Application Server Components
3.1 Adapter Integration with Oracle WebLogic Server............................................................... 3-1
3.1.1 Oracle WebLogic Server Overview................................................................................... 3-1
3.1.2 Oracle WebLogic Server Integration with Adapters ...................................................... 3-3
3.2 Adapter Integration with Oracle Fusion Middleware........................................................... 3-4
3.2.1 Oracle BPEL Process Manager Overview ........................................................................ 3-4
3.2.2 Oracle Mediator Overview................................................................................................. 3-4
3.2.3 Oracle Fusion Middleware Integration with Adapters.................................................. 3-4
3.2.4 Oracle SOA Composite Integration with Adapters..................................................... 3-12
3.2.4.1 Oracle SOA Composite Overview .......................................................................... 3-12
3.2.4.2 Adapters Integration With Oracle SOA Composite............................................. 3-12
3.3 Monitoring Oracle JCA Adapters.......................................................................................... 3-14
4 Oracle JCA Adapter for Files/FTP
4.1 Introduction to Oracle File and FTP Adapters ....................................................................... 4-1
4.1.1 Oracle File and FTP Adapters Architecture..................................................................... 4-1
4.1.2 Oracle File and FTP Adapters Integration with BPEL PM ............................................ 4-2
4.1.3 Oracle File and FTP Adapters Integration with Mediator............................................. 4-3
4.1.4 Oracle File and FTP Adapters Integration with SOA Composite................................. 4-4
4.2 Oracle File and FTP Adapters Features................................................................................... 4-4
4.2.1 File Formats .......................................................................................................................... 4-5
4.2.2 FTP Servers ........................................................................................................................... 4-5
4.2.3 Inbound and Outbound Interactions................................................................................ 4-5
4.2.4 File Debatching .................................................................................................................... 4-6
4.2.5 File ChunkedRead ............................................................................................................... 4-7
4.2.6 File Sorting............................................................................................................................ 4-7
4.2.7 Dynamic Outbound Directory and File Name Specification ........................................ 4-7
4.2.8 Security.................................................................................................................................. 4-7
4.2.9 Nontransactional.................................................................................................................. 4-7
4.2.10 Proxy Support ...................................................................................................................... 4-8
4.2.11 No Payload Support............................................................................................................ 4-8
4.2.12 Large Payload Support ....................................................................................................... 4-8
4.2.13 File-Based Triggers .............................................................................................................. 4-9
4.2.14 Error Handling..................................................................................................................... 4-9
4.2.15 Threading Model .............................................................................................................. 4-10
4.2.15.1 Default Threading Model......................................................................................... 4-10
4.2.15.2 Modified Threading Model...................................................................................... 4-11
4.2.16 Performance Tuning......................................................................................................... 4-12
4.2.17 High Availability .............................................................................................................. 4-12
4.2.18 Multiple Directories.......................................................................................................... 4-12
4.2.19 Append Mode ................................................................................................................... 4-13
4.2.20 Recursive Processing of Files Within Directories in Oracle FTP Adapter................ 4-14

vi
4.2.21 Securing Enterprise Information System Credentials................................................. 4-17
4.3 Oracle File and FTP Adapter Concepts ................................................................................ 4-22
4.3.1 Oracle File Adapter Read File Concepts........................................................................ 4-22
4.3.1.1 Inbound Operation.................................................................................................... 4-22
4.3.1.2 Inbound File Directory Specifications .................................................................... 4-23
4.3.1.2.1 Specifying Inbound Physical or Logical Directory Paths in SOA Composite......
4-24
4.3.1.2.2 Archiving Successfully Processed Files .......................................................... 4-25
4.3.1.2.3 Deleting Files After Retrieval ........................................................................... 4-25
4.3.1.3 File Matching and Batch Processing....................................................................... 4-25
4.3.1.3.1 Specifying a Naming Pattern............................................................................ 4-26
4.3.1.3.2 Including and Excluding Files.......................................................................... 4-26
4.3.1.3.3 Debatching Multiple Inbound Messages........................................................ 4-28
4.3.1.4 File Polling.................................................................................................................. 4-28
4.3.1.5 Postprocessing ........................................................................................................... 4-31
4.3.1.6 Native Data Translation ........................................................................................... 4-31
4.3.1.7 Inbound Service ......................................................................................................... 4-32
4.3.1.8 Inbound Headers....................................................................................................... 4-33
4.3.2 Oracle File Adapter Write File Concepts....................................................................... 4-33
4.3.2.1 Outbound Operation................................................................................................. 4-34
4.3.2.2 Outbound File Directory Creation.......................................................................... 4-34
4.3.2.2.1 Specifying Outbound Physical or Logical Directory Paths in BPEL PM ... 4-35
4.3.2.2.2 Specifying Outbound Physical or Logical Directory Paths in Mediator.... 4-36
4.3.2.2.3 Specifying a Dynamic Outbound Directory Name....................................... 4-36
4.3.2.2.4 Specifying the Outbound File Naming Convention ..................................... 4-39
4.3.2.2.5 Specifying a Dynamic Outbound File Name ................................................. 4-42
4.3.2.2.6 Batching Multiple Outbound Messages.......................................................... 4-43
4.3.2.3 Native Data Translation ........................................................................................... 4-44
4.3.2.4 Outbound Service Files............................................................................................. 4-44
4.3.2.5 Outbound Headers.................................................................................................... 4-45
4.3.3 Oracle File Adapter Synchronous Read Concepts....................................................... 4-45
4.3.4 Oracle File Adapter File Listing Concepts .................................................................... 4-46
4.3.4.1 Listing Operation....................................................................................................... 4-47
4.3.4.2 File Directory Specifications .................................................................................... 4-48
4.3.4.2.1 Specifying Inbound Physical or Logical Directory Paths in SOA Composite......
4-48
4.3.4.3 File Matching.............................................................................................................. 4-49
4.3.4.3.1 Specifying a Naming Pattern............................................................................ 4-49
4.3.4.3.2 Including and Excluding Files.......................................................................... 4-50
4.3.5 Oracle FTP Adapter Get File Concepts.......................................................................... 4-51
4.3.6 Oracle FTP Adapter Put File Concepts.......................................................................... 4-55
4.3.7 Oracle FTP Adapter Synchronous Get File Concepts.................................................. 4-56
4.3.8 Oracle FTP Adapter File Listing Concepts.................................................................... 4-57
4.4 Configuring Oracle File and FTP Adapters ......................................................................... 4-58
4.4.1 Configuring Oracle File and FTP Adapters for High Availability............................ 4-58
4.4.1.1 Prerequisites for High Availability......................................................................... 4-58
4.4.1.2 High Availability in Inbound Operations.............................................................. 4-59
4.4.1.3 High Availability in Outbound Operations .......................................................... 4-61

vii
4.4.2 Using Secure FTP with the Oracle FTP Adapter.......................................................... 4-63
4.4.2.1 Secure FTP Overview................................................................................................ 4-64
4.4.2.2 Installing and Configuring OpenSSL ..................................................................... 4-65
4.4.2.3 Installing and Configuring vsftpd .......................................................................... 4-66
4.4.2.4 Creating an Oracle Wallet ........................................................................................ 4-67
4.4.2.5 Setting Up the Oracle FTP Adapter ........................................................................ 4-68
4.4.3 Using SFTP with Oracle FTP Adapter........................................................................... 4-68
4.4.3.1 SFTP Overview .......................................................................................................... 4-69
4.4.3.1.1 Encryption ........................................................................................................... 4-69
4.4.3.1.2 Authentication .................................................................................................... 4-69
4.4.3.1.3 Integrity ............................................................................................................... 4-69
4.4.3.1.4 Data Compression.............................................................................................. 4-70
4.4.3.2 Install and Configure OpenSSH for Windows...................................................... 4-70
4.4.3.3 Set Up Oracle FTP Adapter for SFTP...................................................................... 4-71
4.4.3.3.1 Configuring Oracle FTP Adapter for Password Authentication................. 4-72
4.4.3.3.2 Configuring Oracle FTP Adapter for Public Key Authentication............... 4-73
4.4.3.3.3 Configuring OpenSSH for Public-Key Authentication................................. 4-73
4.4.3.3.4 Configuring Oracle FTP Adapter for Public Key Authentication with
OpenSSH Running Inside a Firewall 4-74
4.4.3.3.5 Configuring Oracle FTP Adapter for Public Key Authentication with
OpenSSH Running Outside a Firewall 4-74
4.4.4 Configuring Oracle FTP Adapter for HTTP Proxy...................................................... 4-75
4.4.4.1 Configuring for Plain FTP Mode............................................................................. 4-76
4.4.4.1.1 Proxy Definition File.......................................................................................... 4-76
4.4.4.2 Configuring for SFTP Mode..................................................................................... 4-78
4.5 Oracle File and FTP Adapters Use Cases ............................................................................. 4-79
4.5.1 Oracle File Adapter XML Debatching ........................................................................... 4-80
4.5.1.1 Prerequisites............................................................................................................... 4-80
4.5.1.2 Designing the SOA Composite................................................................................ 4-80
4.5.1.3 Creating the Inbound Oracle File Adapter Service .............................................. 4-83
4.5.1.4 Creating the Outbound File Adapter Service........................................................ 4-87
4.5.1.5 Wiring Services and Activities................................................................................. 4-89
4.5.1.6 Deploying with Oracle JDeveloper......................................................................... 4-97
4.5.1.7 Monitoring Using Enterprise Manager Console................................................... 4-97
4.5.2 Flat Structure for BPEL PM ............................................................................................. 4-98
4.5.2.1 Prerequisites............................................................................................................... 4-98
4.5.2.3 Creating the Inbound Oracle File Adapter Service .............................................. 4-99
4.5.2.4 Creating the Outbound Oracle File Adapter Service ......................................... 4-100
4.5.2.5 Wiring Services and Activities............................................................................... 4-101
4.5.2.6 Deploying with Oracle JDeveloper....................................................................... 4-105
4.5.2.7 Monitoring Using Oracle Enterprise Manager Console .................................... 4-105
4.5.3 Flat Structure for Mediator............................................................................................ 4-106
4.5.3.1 Prerequisites............................................................................................................. 4-106
4.5.3.2 Creating a Mediator Application and Project ..................................................... 4-106
4.5.3.3 Importing the Schema Definition (.XSD) Files .................................................... 4-107
4.5.3.4 Creating the Inbound Oracle File Adapter Service ............................................ 4-107

viii
4.5.3.5 Creating the Outbound Oracle FTP Adapter Service......................................... 4-107
4.5.3.6 Wiring Services ........................................................................................................ 4-108
4.5.3.7 Creating the Routing Rule...................................................................................... 4-109
4.5.3.9 Run-Time Task......................................................................................................... 4-111
4.5.4 Oracle File Adapter Scalable DOM .............................................................................. 4-111
4.5.4.1 Prerequisites............................................................................................................. 4-111
4.5.4.2 Designing the SOA Composite.............................................................................. 4-111
4.5.4.7 Monitoring Using Enterprise Manager Console................................................. 4-121
4.5.5 Oracle File Adapter ChunkedRead.............................................................................. 4-122
4.5.5.1 Prerequisites............................................................................................................. 4-122
4.5.6 Oracle File Adapter Read File As Attachments.......................................................... 4-137
4.5.6.1 Prerequisites............................................................................................................. 4-138
4.5.7 Oracle File Adapter File Listing.................................................................................... 4-149
4.5.7.1 Prerequisites............................................................................................................. 4-149
4.5.8 Oracle File Adapter Complex Structure...................................................................... 4-157
4.5.8.1 Prerequisites............................................................................................................. 4-157
4.5.9 Oracle FTP Adapter Debatching .................................................................................. 4-165
4.5.9.1 Prerequisites............................................................................................................. 4-165

ix
4.5.9.3 Creating the Inbound Oracle FTP Adapter Service............................................ 4-166
4.5.10 Oracle FTP Adapter Dynamic Synchronous Read..................................................... 4-174
4.5.10.1 Prerequisites............................................................................................................. 4-174
4.5.11 Copying, Moving, and Deleting Files.......................................................................... 4-185
4.5.11.1 Moving a File from a Local Directory on the File System to Another Local
Directory 4-186
4.5.11.2 Copying a File from a Local Directory on the File System to Another Local
Directory 4-189
4.5.11.3 Deleting a File from a Local File System Directory ............................................ 4-189
4.5.11.4 Using a Large CSV Source File ............................................................................. 4-190
4.5.11.5 Moving a File from One Remote Directory to Another Remote Directory on the
Same FTP Server 4-191
4.5.11.6 Moving a File from a Local Directory on the File System to a Remote Directory on
the FTP Server 4-194
4.5.11.7 Moving a File from a Remote Directory on the FTP Server to a Local Directory on
the File System 4-195
4.5.11.8 Moving a File from One FTP Server to another FTP Server.............................. 4-195
5 Oracle JCA Adapter for Sockets
5.1 Introduction to Oracle Socket Adapter.................................................................................... 5-1
5.1.1 Oracle Socket Adapter Architecture ................................................................................. 5-1
5.1.2 Oracle Socket Adapter Integration with Mediator ......................................................... 5-2
5.1.3 Oracle Socket Adapter Integration with BPEL PM......................................................... 5-2
5.1.4 Oracle Socket Adapter Integration with SOA Composite............................................. 5-3
5.2 Oracle Socket Adapter Features................................................................................................ 5-3
5.3 Oracle Socket Adapter Concepts .............................................................................................. 5-4
5.3.1 Communication Modes ...................................................................................................... 5-4
5.3.1.1 Inbound Synchronous Request/Response ............................................................... 5-4
5.3.1.2 Outbound Synchronous Request/Response............................................................ 5-5
5.3.1.3 Inbound Receive ........................................................................................................... 5-5
5.3.1.4 Outbound Invoke ......................................................................................................... 5-6
5.3.2 Mechanisms for Defining Protocols.................................................................................. 5-6
5.3.2.1 Protocol with Handshake Mechanism Using Style Sheet....................................... 5-6
5.3.2.2 Protocol with Handshake Mechanism Using Custom Java Code......................... 5-8
5.3.2.3 Protocol Without Handshake Mechanism............................................................. 5-11
5.3.3 Character Encoding and Byte Order.............................................................................. 5-11

x
5.4 Configuring Oracle Socket Adapter...................................................................................... 5-13
5.4.1 Modifying the weblogic-ra.xml File............................................................................... 5-13
5.4.2 Modeling a Handshake.................................................................................................... 5-14
5.4.2.1 Modeling an Outbound Handshake....................................................................... 5-14
5.4.2.2 Modeling an Inbound Handshake.......................................................................... 5-15
5.4.3 Designing an XSL File Using the XSL Mapper Tool.................................................... 5-15
5.4.3.1 Designing XSL for Inbound Synchronous Request/Reply ................................. 5-16
5.4.3.2 Designing XSL for Outbound Synchronous Request/Reply.............................. 5-23
5.5 Oracle Socket Adapter Use Cases.......................................................................................... 5-30
5.5.1 Oracle Socket Adapter Hello World .............................................................................. 5-30
5.5.1.1 Prerequisites............................................................................................................... 5-31
5.5.1.3 Creating the Inbound Oracle Socket Adapter Service ......................................... 5-33
5.5.1.4 Creating the Outbound Oracle Socket Adapter Service ...................................... 5-38
5.5.1.7 Monitoring Using the Enterprise Manager Console ............................................ 5-52
5.5.2 Flight Information Display System................................................................................ 5-53
5.5.2.1 Prerequisites............................................................................................................... 5-53
5.5.2.3 Creating the Inbound Oracle Socket Adapter Service ......................................... 5-54
5.5.2.4 Creating Outbound Oracle Socket Adapter Services........................................... 5-58
5.5.2.7 Monitoring Using the Enterprise Manager Console ............................................ 5-86
6 Native Format Builder Wizard
6.1 Creating Native Schema Files with the Native Format Builder Wizard............................. 6-1
6.1.1 Supported File Formats....................................................................................................... 6-2
6.1.1.1 Delimited ....................................................................................................................... 6-3
6.1.1.2 Fixed Length (Positional) ............................................................................................ 6-3
6.1.1.3 Complex Type............................................................................................................... 6-3
6.1.1.4 DTD ................................................................................................................................ 6-3
6.1.1.5 COBOL Copybook........................................................................................................ 6-3
6.1.2 Editing Native Schema Files .............................................................................................. 6-7
6.2 Native Schema Constructs......................................................................................................... 6-8
6.2.1 Understanding Native Schema Constructs...................................................................... 6-8
6.2.2 Using Native Schema Constructs................................................................................... 6-10
6.2.2.1 Defining Fixed-Length Data .................................................................................... 6-11
6.2.2.2 Defining Terminated Data ....................................................................................... 6-13
6.2.2.3 Defining Surrounded Data....................................................................................... 6-15
6.2.2.4 Defining Lists ............................................................................................................. 6-17
6.2.2.5 Defining Arrays ......................................................................................................... 6-18
6.2.2.6 Conditional Processing............................................................................................. 6-24
6.2.2.7 Defining Dates............................................................................................................ 6-31
6.2.2.8 Using Variables.......................................................................................................... 6-34
6.2.2.9 Defining Prefixes and Suffixes................................................................................. 6-35

xi
6.2.2.10 Defining Skipping Data ............................................................................................ 6-36
6.2.2.11 Defining fixed and default Values .......................................................................... 6-37
6.2.2.12 Defining write ............................................................................................................ 6-38
6.2.2.13 Defining LookAhead................................................................................................. 6-38
6.2.2.14 Defining outboundHeader....................................................................................... 6-40
6.2.2.15 Defining Complex Condition in conditionValue.................................................. 6-41
6.2.2.16 Defining Complex Condition in choiceCondition................................................ 6-43
6.2.2.17 Defining dataLines .................................................................................................... 6-44
6.2.2.18 Defining Date Formats with Time Zone ................................................................ 6-45
6.2.2.19 Implementing Validation During Translation ...................................................... 6-47
6.2.2.19.1 Payload Validation............................................................................................. 6-47
6.2.2.19.2 Schema Validation.............................................................................................. 6-48
6.2.2.20 Processing Files with BOM ...................................................................................... 6-48
6.3 Translator XPath Functions.................................................................................................... 6-49
6.3.1 Terminologies.................................................................................................................... 6-49
6.3.2 Translator XPath Functions ............................................................................................ 6-50
6.3.2.1 doTranslateFromNative Function........................................................................... 6-50
6.3.2.2 doTranslateToNative Function................................................................................ 6-55
6.3.2.3 doStreamingTranslate Function ............................................................................. 6-57
6.3.2.4 Batching Transformation Features.......................................................................... 6-58
6.4 Use Cases for the Native Format Builder............................................................................. 6-61
6.4.1 Defining the Schema for a Delimited File Structure.................................................... 6-61
6.4.1.1 Defining a Asterisk (*) Separated Value File Structure........................................ 6-69
6.4.2 Defining the Schema for a Fixed Length File Structure .............................................. 6-70
6.4.3 Defining the Schema for a Complex File Structure ..................................................... 6-77
6.4.4 Removing or Adding Namespaces to XML with No Namespace............................. 6-93
6.4.5 Defining the Choice Condition Schema for a Complex File Structure ..................... 6-93
6.4.6 Defining Choice Condition With LookAhead for a Complex File Structure........... 6-98
6.4.7 Defining Array Type Schema for a Complex File Structure..................................... 6-104
6.4.8 Defining the Schema for a DTD File Structure........................................................... 6-108
6.4.9 Defining the Schema for a COBOL Copybook File Structure.................................. 6-111
Part II Message Adapters
7 Oracle JCA Adapter for AQ
7.1 Introduction to the Oracle AQ Adapter .................................................................................. 7-1
7.1.1 Oracle AQ Adapter Integration with Oracle BPEL Process Manager ......................... 7-1
7.1.2 Oracle AQ Adapter Integration with Oracle Mediator.................................................. 7-1
7.2 Oracle AQ Adapter Features..................................................................................................... 7-2
7.2.1 Enqueue-Specific Features (Message Production).......................................................... 7-2
7.2.2 Dequeue and Enqueue Features........................................................................................ 7-3
7.2.3 Supported ADT Payload Types......................................................................................... 7-4
7.2.4 Native Format Builder Wizard .......................................................................................... 7-5
7.2.5 Normalized Message Support ........................................................................................... 7-6
7.2.6 Is DOM 2 Compliant ........................................................................................................... 7-7
7.2.7 Is .......................................................................................................Message-Size Aware 7-7

xii
7.2.8 Multiple Receiver Threads ................................................................................................. 7-7
7.2.9 DequeueTimeout Property................................................................................................. 7-7
7.2.10 Control Dequeue Timeout and Multiple Inbound Polling Threads ............................ 7-8
7.2.11 Stream Payload Support..................................................................................................... 7-8
7.2.12 Oracle AQ Adapter Inbound Retries ................................................................................ 7-8
7.2.13 Error Handling Support...................................................................................................... 7-9
7.3 Oracle AQ Adapter Use Cases.................................................................................................. 7-9
7.3.1 Generic Use Case ................................................................................................................. 7-9
7.3.1.1 Adapter Configuration Wizard Walkthrough ......................................................... 7-9
7.3.1.1.1 Meeting Prerequisites ........................................................................................... 7-9
7.3.1.1.2 Creating an Application and an SOA Project................................................. 7-10
7.3.1.1.3 Defining an Oracle AQ Adapter Service......................................................... 7-12
7.3.1.1.4 Generated WSDL and JCA Files....................................................................... 7-23
7.3.1.2 Dequeuing and Enqueuing Object and ADT Payloads ...................................... 7-24
7.3.1.3 Dequeuing One Column of the Object Payload.................................................... 7-24
7.3.1.4 Using Correlation ID for Filtering Messages During Dequeue ......................... 7-25
7.3.1.5 Enqueuing and Dequeuing from Multisubscriber Queues................................. 7-26
7.3.1.6 Rule-Based Subscription for Multiconsumer Queues.......................................... 7-27
7.3.2 Oracle AQ Adapter ADT Queue .................................................................................... 7-28
7.3.2.1 Meeting Prerequisites ............................................................................................... 7-28
7.3.2.2 Creating an Application and an SOA Project........................................................ 7-29
7.3.2.3 Creating an Inbound Oracle AQ Adapter.............................................................. 7-30
7.3.2.4 Creating an Outbound Oracle AQ Adapter .......................................................... 7-32
7.3.2.6 Configuring Routing Service ................................................................................... 7-35
7.3.2.7 Configuring the Data Sources in the Oracle WebLogic Server Administration
Console 7-37
7.3.2.9 Monitoring Using the Oracle Enterprise Manager Console................................ 7-43
7.3.3 Oracle AQ Adapter RAW Queue................................................................................... 7-43
7.3.3.1 Prerequisites............................................................................................................... 7-43
7.3.3.3 Creating an Inbound Adapter Service.................................................................... 7-44
7.3.3.4 Creating an Outbound Adapter Service ................................................................ 7-48
7.3.3.6 Configuring the Data Sources in the Oracle WebLogic Server Administration
Console 7-55
8 Oracle JCA Adapter for JMS
8.1 Introduction to the Oracle JMS Adapter.................................................................................. 8-1
8.1.1 Oracle JMS Adapter Integration with Oracle BPEL Process Manager ........................ 8-1
8.1.2 Oracle JMS Adapter Integration with Oracle Mediator................................................. 8-1
8.2 Oracle JMS Adapter Features................................................................................................... 8-2
8.3 Oracle JMS Adapter Concepts .................................................................................................. 8-5
8.3.1 Point-to-Point ....................................................................................................................... 8-5

xiii
8.3.2 Publish/Subscribe ............................................................................................................... 8-5
8.3.3 Destination, Connection, Connection Factory, and Session.......................................... 8-6
8.3.4 Structure of a JMS Message................................................................................................ 8-6
8.3.5 Oracle JMS Adapter Header Properties ........................................................................... 8-6
8.4 Oracle JMS Adapter Use Cases................................................................................................. 8-7
8.4.1 Configuring Oracle JMS Adapter...................................................................................... 8-7
8.4.1.1 Creating an Application and an SOA Project........................................................... 8-7
8.4.1.2 Using the Adapter Configuration Wizard to Configure Oracle JMS Adapter. 8-10
8.4.1.3 Generated Files .......................................................................................................... 8-16
8.4.1.4 weblogic-ra.xml file................................................................................................... 8-18
8.4.1.5 Produce Message Procedure.................................................................................... 8-20
8.4.2 Configuring Oracle JMS Adapter with TIBCO JMS .................................................... 8-21
8.4.2.1 NonDirect Connection.............................................................................................. 8-21
8.4.2.2 Direct Connection...................................................................................................... 8-23
8.4.3 Configuring Oracle JMS Adapter with IBM WebSphere MQ JMS............................ 8-24
8.4.3.1 Non-XA Data Sources............................................................................................... 8-24
8.4.3.2 XA Data Sources ........................................................................................................ 8-25
8.4.4 WLS JMS Text Message.................................................................................................... 8-26
8.4.4.1.1 Creating Queues in the Oracle WebLogic Server Administration Console..........
8-26
8.4.4.2 Creating an Application Server Connection.......................................................... 8-27
8.4.5 Accessing Queues and Topics from WLS JMS Server in a Remote Oracle WebLogic
Server Domain 8-36
8.4.6 Synchronous/Asynchronous Request Reply Interaction Pattern ............................. 8-36
8.4.7 AQ JMS Text Message...................................................................................................... 8-37
8.4.7.1.1 Configuring AQ JMS in Oracle WebLogic Server Administration Console.........
8-38
8.4.7.1.2 Creating Queues in Oracle Database............................................................... 8-41
8.4.7.2 Create an Application Server Connection ............................................................. 8-41
8.4.8 Accessing Queues and Topics Created in 11g from the OC4J 10.1.3.4 Server ......... 8-46
9 Oracle JCA Adapter for Database
9.1 Introduction to the Oracle Database Adapter......................................................................... 9-1

xiv
9.1.1 Oracle Database Adapter Features.................................................................................... 9-1
9.1.1.1 Oracle Database Adapter Integration with Oracle BPEL Process Manager ........ 9-2
9.1.2 Design Overview ................................................................................................................. 9-2
9.2 Complete Walkthrough of the Adapter Configuration Wizard .......................................... 9-4
9.2.1 Creating an Application and an SOA Project.................................................................. 9-5
9.2.2 Defining an Oracle Database Adapter.............................................................................. 9-7
9.2.3 Connecting to a Database ................................................................................................... 9-8
9.2.4 Selecting the Operation Type............................................................................................. 9-9
9.2.5 Selecting and Importing Tables...................................................................................... 9-11
9.2.6 Defining Primary Keys .................................................................................................... 9-12
9.2.7 Creating Relationships..................................................................................................... 9-13
9.2.7.1 What Happens When Relationships Are Created or Removed ......................... 9-15
9.2.7.2 Different Types of One-to-One Mappings............................................................. 9-16
9.2.7.3 When Foreign Keys Are Primary Keys .................................................................. 9-16
9.2.8 Creating the Attribute Filter............................................................................................ 9-16
9.2.9 Defining a WHERE Clause.............................................................................................. 9-17
9.2.10 Choosing an After-Read Strategy................................................................................... 9-19
9.2.10.1 Delete the Rows That Were Read............................................................................ 9-20
9.2.10.2 Update a Field in the Table (Logical Delete) ......................................................... 9-20
9.2.10.3 Update a Sequencing Table...................................................................................... 9-21
9.2.10.4 Update an External Sequencing Table on a Different Database......................... 9-22
9.2.10.5 Update a Sequencing File......................................................................................... 9-23
9.2.11 Specifying Polling Options.............................................................................................. 9-24
9.2.12 Specifying Advanced Options ........................................................................................ 9-24
9.2.13 Entering the SQL String for the Pure SQL Operation ................................................. 9-26
9.3 Oracle Database Adapter Features........................................................................................ 9-26
9.3.1 Transaction Support......................................................................................................... 9-27
9.3.1.1 Configuring Oracle Database Adapter for Global Transaction Participation .. 9-28
9.3.1.2 Both Invokes in Same Global Transaction ............................................................ 9-28
9.3.1.3 Failure Must Cause Rollback ................................................................................... 9-28
9.3.1.3.1 Using the Same Sessions for Both Invokes ..................................................... 9-28
9.3.1.4 Transaction/XA Support.......................................................................................... 9-29
9.3.1.4.1 Configuring an Oracle Database Adapter for Global Transaction Participation.
9-29
9.3.1.4.2 Failure Must Cause Rollback............................................................................ 9-29
9.3.2 Pure SQL - XML Type Support....................................................................................... 9-30
9.3.3 Proxy Authentication Support........................................................................................ 9-30
9.3.4 Streaming Large Payload................................................................................................. 9-31
9.3.5 Schema Validation............................................................................................................ 9-31
9.3.6 High Availability .............................................................................................................. 9-31
9.3.6.1 Surviving Database Restart...................................................................................... 9-31
9.3.6.1.1 Oracle Database Adapter Gets Stuck on DataSource Closed Exceptions . 9-31
9.3.6.1.2 Auto-Retrying Remote Faults........................................................................... 9-32
9.3.6.1.3 Exception Misclassification............................................................................... 9-32
9.3.6.1.4 Recoverable Instances........................................................................................ 9-32
9.3.6.2 Undying ...................................................................................................................... 9-32
9.3.7 Scalability........................................................................................................................... 9-33
9.3.7.1 Distributed Polling Best Practice: MarkReservedValue ...................................... 9-33

xv
9.3.7.2 Distributed Polling Second Best Practice: SELECT FOR UPDATE.................... 9-35
9.3.7.3 Distributed Polling Third Best Practice: Tuning on a Single Node First........... 9-36
9.3.9 detectOmissions Feature........................................................................................... 9-37
9.3.10 OutputCompletedXml Feature.................................................................................... 9-39
9.3.11 QueryTimeout for Inbound and Outbound Transactions.......................................... 9-39
9.3.12 Doing Synchronous Post to BPEL (Allow In-Order Delivery)................................... 9-39
9.4 Oracle Database Adapter Concepts ...................................................................................... 9-40
9.4.1 Relational-to-XML Mapping........................................................................................... 9-40
9.4.1.1 Relational Types to XML Schema Types................................................................ 9-44
9.4.1.2 Mapping Any Relational Schema to Any XML Schema...................................... 9-45
9.4.1.3 Querying over Multiple Tables ............................................................................... 9-45
9.4.1.3.1 Using Relationship Queries (TopLink Default)............................................. 9-46
9.4.1.3.2 Twisting the Original Select (TopLink Batch-Attribute Reading)............... 9-46
9.4.1.3.3 Returning a Single Result Set (TopLink Joined-Attribute Reading)........... 9-47
9.4.1.3.4 Comparison of the Methods Used for Querying over Multiple Tables ..... 9-49
9.4.2 SQL Operations as Web Services.................................................................................... 9-50
9.4.2.1 DML Operations........................................................................................................ 9-50
9.4.2.2 Polling Strategies ....................................................................................................... 9-52
9.5 Deployment .............................................................................................................................. 9-60
9.6 Third Party JDBC Driver and Database Connection Configuration ................................ 9-63
9.6.1 Using a Microsoft SQL Server......................................................................................... 9-64
9.6.1.1 MS JDBC Driver......................................................................................................... 9-64
9.6.1.2 DataDirect Driver ...................................................................................................... 9-64
9.6.2 Using an IBM DB2 Database........................................................................................... 9-66
9.6.2.1 IBM DB2 Driver ......................................................................................................... 9-66
9.6.2.2 JT400 Driver (AS400 DB2) ........................................................................................ 9-66
9.6.2.3 IBM Universal Driver................................................................................................ 9-66
9.6.3 Using an InterSystems Caché Database ........................................................................ 9-66
9.6.4 Using a MySQL 4 Database............................................................................................. 9-66
9.6.5 Summary of Third-Party and Oracle Olite Database Connection Information....... 9-67
9.6.6 Location of JDBC Driver JAR Files and Setting the Class Path.................................. 9-67
9.7 Stored Procedure and Function Support.............................................................................. 9-68
9.7.1 Design Time: Using the Adapter Configuration Wizard............................................ 9-68
9.7.1.1 Using Top-Level Standalone APIs .......................................................................... 9-68
9.7.1.2 Using Packaged APIs and Overloading................................................................. 9-75
9.7.2 Design Time: Using the Command-Line Utility .......................................................... 9-77
9.7.2.1 Common Command-Line Functionality................................................................ 9-77
9.7.2.2 Generated Output...................................................................................................... 9-78
9.7.2.3 Supported Third-Party Databases........................................................................... 9-79
9.7.2.3.1 Microsoft SQL Server 2000 and 2005............................................................... 9-79
9.7.2.3.2 IBM DB2 v8.x and v9.x ...................................................................................... 9-81
9.7.2.3.3 IBM DB2 AS/400 ................................................................................................ 9-84
9.7.2.3.4 MySQL v5.x and v6.x......................................................................................... 9-85
9.7.2.4 Creating Database Connections .............................................................................. 9-87
9.7.3 Design Time: Artifact Generation .................................................................................. 9-90
9.7.3.1 The WSDL–XSD Relationship.................................................................................. 9-91

xvi
9.7.3.2 JCA File ....................................................................................................................... 9-92
9.7.3.3 Oracle Data Types ..................................................................................................... 9-93
9.7.3.4 Generated XSD Attributes........................................................................................ 9-93
9.7.3.5 User-Defined Types................................................................................................... 9-94
9.7.3.6 Complex User-Defined Types ................................................................................. 9-96
9.7.3.7 Object Type Inheritance............................................................................................ 9-96
9.7.3.8 Object References....................................................................................................... 9-97
9.7.3.9 Referencing Types in Other Schemas ..................................................................... 9-97
9.7.3.10 XSD Pruning Optimization...................................................................................... 9-98
9.7.4 Run Time: Before Stored Procedure Invocation .......................................................... 9-99
9.7.4.1 Value Binding............................................................................................................. 9-99
9.7.4.2 Data Type Conversions .......................................................................................... 9-101
9.7.5 Run Time: After Stored Procedure Invocation........................................................... 9-102
9.7.5.1 Data Type Conversions .......................................................................................... 9-102
9.7.5.2 Null Values............................................................................................................... 9-103
9.7.5.3 Function Return Values.......................................................................................... 9-103
9.7.6 Run Time: Common Third-Party Database Functionality........................................ 9-103
9.7.6.1 Processing ResultSets.............................................................................................. 9-103
9.7.6.2 Returning an INTEGER Status Value................................................................... 9-104
9.7.7 Advanced Topics ............................................................................................................ 9-105
9.7.7.1 Support for REF CURSOR...................................................................................... 9-105
9.7.7.1.1 Design Time ...................................................................................................... 9-105
9.7.7.1.2 Run Time ........................................................................................................... 9-106
9.7.7.2 Support for PL/SQL Boolean, PL/SQL Record, and PL/SQL Table Types... 9-107
9.7.7.2.1 Default Clauses in Wrapper Procedures....................................................... 9-109
9.8 Oracle Database Adapter Use Cases................................................................................... 9-110
9.8.1 Use Cases for Oracle Database Adapter...................................................................... 9-110
9.8.2 Use Cases for Oracle Database Adapter - Stored Procedures.................................. 9-112
9.8.2.1 Creating and Configuring a Stored Procedure in Oracle JDeveloper BPEL Designer
9-112
9.8.2.1.1 Prerequisites...................................................................................................... 9-112
9.8.2.1.2 Creating an Application and an SOA Composite........................................ 9-113
9.8.2.1.3 Creating the Outbound Oracle Database Adapter Service ........................ 9-114
9.8.2.1.4 Add an Invoke Activity................................................................................... 9-115
9.8.2.1.5 Change the Message Part of the Request Message...................................... 9-116
9.8.2.1.6 Change the Message Part of the Response Message................................... 9-117
9.8.2.1.7 Add a Assign Activity for the Input Variable.............................................. 9-117
9.8.2.1.8 Add an Assign Activity for the Output Variable ........................................ 9-118
9.8.2.1.9 Deploying with Oracle JDeveloper................................................................ 9-119
9.8.2.1.10 Creating a DataSource in Oracle WebLogic Server Administration Console ......
9-120
9.8.2.1.11 Monitoring Using the Oracle Enterprise Manager Console ...................... 9-121
9.8.2.2 File To StoredProcedure Use Case........................................................................ 9-122
9.8.2.2.1 Prerequisites...................................................................................................... 9-122
9.8.2.2.2 Creating an Application and an SOA Project............................................... 9-123
9.8.2.2.3 Creating the Outbound Oracle Database Adapter Service ........................ 9-124
9.8.2.2.4 Creating an Invoke Activity............................................................................ 9-125
9.8.2.2.5 Creating the Inbound File Adapter Service.................................................. 9-126

xvii
9.8.2.2.6 Adding a Receive Activity .............................................................................. 9-127
9.8.2.2.7 Adding an Assign Activity ............................................................................. 9-128
9.8.2.2.8 Wiring Services and Activities ....................................................................... 9-131
9.8.2.2.9 Deploying with Oracle JDeveloper................................................................ 9-131
9.8.2.2.10 Creating a Data Source .................................................................................... 9-131
9.8.2.2.11 Adding a Connection-Instance....................................................................... 9-133
9.8.2.2.12 Testing using the File Adapter Service and SQL*Plus................................ 9-134
9.8.2.2.13 Monitoring Using the Oracle Enterprise Manager Console ...................... 9-135
10 Oracle JCA Adapter for MQ Series
10.1 MQ Series Message Queuing Concepts................................................................................ 10-1
10.1.1 MQ Series Concepts.......................................................................................................... 10-3
10.2 Introduction to Native Oracle MQ Series Adapter............................................................. 10-4
10.2.1 The Need for Oracle MQ Series Adapter ...................................................................... 10-4
10.2.2 Oracle MQ Series Adapter Integration with Oracle BPEL Process Manager .......... 10-5
10.2.3 Oracle MQ Series Adapter Integration with Oracle Mediator................................... 10-6
10.3 Oracle MQ Series Adapter Features...................................................................................... 10-6
10.3.1 RFH Version 2 (RFH2) Header ....................................................................................... 10-6
10.3.1.1 Fixed Portion .............................................................................................................. 10-7
10.3.1.2 Variable Portion......................................................................................................... 10-8
10.3.2 SSL Enabling...................................................................................................................... 10-9
10.3.3 XA Transactions.............................................................................................................. 10-10
10.3.4 High Availability ............................................................................................................ 10-11
10.3.4.1 Prerequisites for High Availability....................................................................... 10-11
10.3.4.2 High Availability in Inbound/Outbound Operations....................................... 10-11
10.3.5 Scalability......................................................................................................................... 10-11
10.3.6 Securing Enterprise Information System Credentials............................................... 10-12
10.3.7 Fault Policy ...................................................................................................................... 10-12
10.3.8 Inbound Rejection Handler........................................................................................... 10-12
10.3.9 Retry Mechanism............................................................................................................ 10-12
10.3.9.1 JCA Inbound Retry Mechanism ............................................................................ 10-13
10.3.9.2 Message Backout Queue......................................................................................... 10-13
10.4 Oracle MQ Series Adapter Concepts .................................................................................. 10-13
10.4.1 Messaging Scenarios ...................................................................................................... 10-13
10.4.1.1 Enqueue Message .................................................................................................... 10-14
10.4.1.2 Dequeue Message.................................................................................................... 10-17
10.4.1.3 Asynchronous Request-Response (Oracle BPEL Process Manager As Client) ...........
10-19
10.4.1.4 Synchronous Request-Response (Oracle BPEL Process Manager As Server) 10-24
10.4.1.5 Asynchronous Request-Response (Oracle BPEL Process Manager As Server)...........
10-28
10.4.1.6 Synchronous Request-Response (Oracle Mediator As Server)......................... 10-34
10.4.1.7 Synchronous Request-Response (Oracle BPEL Process Manager As Client). 10-35
10.4.1.8 Synchronous Request-Response (Oracle Mediator as Client)........................... 10-37
10.4.1.9 Asynchronous Request-Response (Oracle Mediator As Client)....................... 10-37
10.4.1.10 Outbound Dequeue Scenario................................................................................. 10-39
10.4.2 Message Properties......................................................................................................... 10-40

xviii
10.4.2.1 Messages Types ....................................................................................................... 10-40
10.4.2.2 Message Format....................................................................................................... 10-40
10.4.2.3 Message Expiry........................................................................................................ 10-41
10.4.2.4 Message Priority ...................................................................................................... 10-41
10.4.2.5 Message Persistence ................................................................................................ 10-41
10.4.3 Correlation Schemas....................................................................................................... 10-41
10.4.4 Distribution List Support............................................................................................... 10-42
10.4.5 Report Messages ............................................................................................................. 10-42
10.4.6 Message Delivery Failure Options............................................................................... 10-43
10.4.7 Message Segmentation................................................................................................... 10-43
10.4.8 Integration with CICS .................................................................................................... 10-43
10.4.9 Supported Encodings..................................................................................................... 10-49
10.5 Configuring the Oracle MQ Series Adapter....................................................................... 10-52
10.5.1 Adding com.ibm.mq.jar to the Oracle MQ Series Adapter Classpath.................... 10-52
10.5.2 Adding JNDI Entry......................................................................................................... 10-52
10.5.3 Enabling Binding Mode for Connections.................................................................... 10-55
10.6 Oracle MQ Series Adapter Use Cases................................................................................. 10-56
10.6.1 Dequeue Enqueue........................................................................................................... 10-56
10.6.1.1 Prerequisites............................................................................................................. 10-57
10.6.1.3 Creating an Inbound Adapter Service.................................................................. 10-60
10.6.1.4 Creating an Outbound Adapter Service .............................................................. 10-64
10.6.1.7 Monitoring Using the Enterprise Manager Console .......................................... 10-69
10.6.2 Inbound Synchronous Request-Reply......................................................................... 10-70
10.6.2.1 Prerequisites............................................................................................................. 10-70
10.6.2.5 Deploying with JDeveloper ................................................................................... 10-75
10.6.3 Inbound-Outbound Synchronous Request-Reply ..................................................... 10-76
10.6.3.1 Prerequisites............................................................................................................. 10-76
10.6.3.4 Creating an Outbound Adapter Service .............................................................. 10-78
10.6.4 Asynchronous-Request-Reply ...................................................................................... 10-87
10.6.4.1 Prerequisites............................................................................................................. 10-87
10.6.4.4 Creating an Asynchronous Outbound Request Reply Adapter Service Outbound...
10-89
10.6.4.5 Creating Another Outbound Adapter Service.................................................... 10-91

xix
10.6.5 Outbound Dequeue........................................................................................................ 10-97
10.6.5.1 Prerequisites............................................................................................................. 10-98
10.6.5.3 Creating an Outbound Dequeue Adapter Service.............................................. 10-99
10.6.5.4 Wiring Services and Activities............................................................................. 10-100
10.6.5.5 Deploying with JDeveloper ................................................................................. 10-103
10.6.5.6 Monitoring Using the Enterprise Manager Console ........................................ 10-103
A Oracle JCA Adapter Properties
A.1 Oracle File and FTP Adapters Properties............................................................................... A-1
A.2 Oracle Socket Adapter Properties ........................................................................................... A-6
A.3 Oracle AQ Adapter Properties................................................................................................. A-6
A.4 Oracle JMS Adapter Properties................................................................................................ A-7
A.5 Oracle Database Adapter Properties....................................................................................... A-8
A.6 Oracle MQ Series Adapter Properties..................................................................................... A-9
B Troubleshooting and Workarounds
B.1 Troubleshooting the Oracle JCA Adapter for Database....................................................... B-1
B.1.1 Could Not Create TopLink Session Exception............................................................... B-2
B.1.2 Could Not Find Adapter for eis/DB/my_connection..................................................... B-2
B.1.3 Cannot Change Customers_table.xsd.............................................................................. B-3
B.1.4 No Target Foreign Keys Error........................................................................................... B-3
B.1.5 No Primary Key Exception................................................................................................ B-3
B.1.6 dateTime Conversion Exceptions..................................................................................... B-4
B.1.7 Issues with Oracle DATE................................................................................................... B-5
B.1.8 TIMESTAMP Data Type Is Not Supported for a Microsoft SQL Server Database... B-5
B.1.9 Handling an Oracle Database Adapter Fault ................................................................. B-6
B.1.10 Table Not Found: SQL Exception..................................................................................... B-6
B.1.11 Switching from a Development Database to a Production Database ......................... B-7
B.1.12 Only One Employee Per Department Appears.............................................................. B-7
B.1.13 Outbound SELECT on a CHAR(X) or NCHAR Column Returns No Rows.............. B-7
B.1.14 ORA-00932: Inconsistent Data Types Exception Querying CLOBs ............................ B-8
B.1.15 ORA-17157: 4K/32K Driver Limit with CLOBs and BLOBs........................................ B-8
B.1.16 MERGE Sometimes Does UPDATE Instead of INSERT, or Vice Versa...................... B-9
B.1.17 Message Loss with the MERGE Invoke Operation........................................................ B-9
B.1.18 Integrity Violation Occurs with Delete or DeletePollingStrategy ............................. B-10
B.1.19 Some Queried Rows Appear Twice or Not at All in the Query Result .................... B-11
B.1.20 Importing a Same-Named Table, with Same Schema Name, but Different Databases ....
B-11
B.1.21 Problems Creating a Relationship Manually for a Composite Primary Key .......... B-12
B.1.22 Must Fully Specify Relationships Involving Composite Primary Keys ................... B-12
B.1.23 Oracle Database Adapter Throws an Exception When Using a BFILE .................... B-12
B.1.24 Relationships Not Autogenerated When Tables Are Imported Separately............. B-12
B.1.25 Primary Key Is Not Saved ............................................................................................... B-12

xx
B.1.26 Table Column Name Is a Java Keyword....................................................................... B-13
B.1.27 Catching a Database Exception....................................................................................... B-14
B.1.28 Connection Settings Error: Too Many Transactions.................................................... B-14
B.1.29 ORA-01747: invalid user.table.column, table.column, or column specification, When
Using SELECT FOR UPDATE B-15
B.1.30 Update Only Sometimes Performs Inserts/Deletes for Child Records.................... B-15
B.1.31 Issue When Design-Time And Run-Time Connection Users Are Different ............ B-16
B.2 Troubleshooting the Oracle JCA Adapter for Database When Using Stored Procedures .......
B-16
B.2.1 Design Time: Unsupported or Undefined Parameter Types ..................................... B-16
B.2.2 Design Time: Referencing User-Defined Types in Other Schemas........................... B-17
B.2.3 Run Time: Parameter Mismatches ................................................................................. B-18
B.2.4 Run Time: Stored Procedure Not Defined in the Database........................................ B-18
B.2.5 Configuring Multiple Adapters in the Inbound Direction using Correlation Sets. B-19
B.3 Troubleshooting the Oracle JCA Adapter for Files/FTP ................................................... B-19
B.3.1 Changing Logical Names with the Adapter Configuration Wizard......................... B-20
B.3.2 Creating File Names with Spaces with the Native Format Builder Wizard ............ B-20
B.3.3 Creating Schema Definition Files using Native Format Builder Constructs ........... B-20
B.3.4 Setting AUTOEXTEND for Tablespaces for Processing More Than 30000 Files..... B-20
B.3.5 Setting MinimumAge to Ensure Processing of All Files During Multiple Processing......
B-20
B.3.6 Common User Errors ....................................................................................................... B-21
B.4 Troubleshooting the Oracle JCA Adapter for AQ............................................................... B-22
B.4.1 Inbound Errors.................................................................................................................. B-23
B.4.1.1 JNDI Lookup Failed .................................................................................................. B-23
B.4.1.2 Queue Not Found...................................................................................................... B-24
B.4.2 Outbound Errors............................................................................................................... B-24
B.4.2.1 JNDI Lookup Failed .................................................................................................. B-24
B.4.2.2 Queue Not Found...................................................................................................... B-25
B.5 Troubleshooting the Oracle JCA Adapter for JMS.............................................................. B-25
Index

xxi
Preface
This guide describes how to use the technology adapters that are provided with Oracle
BPEL Process Manager and Oracle Mediator.
This preface contains the following topics:
■ Audience
■ Documentation Accessibility
■ Related Documents
■ Conventions
Audience
Oracle Fusion Middleware User's Guide for Technology Adapters is intended for anyone
who is interested in using these adapters.
Documentation Accessibility
Our goal is to make Oracle products, services, and supporting documentation
accessible to all users, including users that are disabled. To that end, our
documentation includes features that make information available to users of assistive
technology. This documentation is available in HTML format, and contains markup to
facilitate access by the disabled community. Accessibility standards will continue to
evolve over time, and Oracle is actively engaged with other market-leading
technology vendors to address technical obstacles so that our documentation can be
accessible to all of our customers. For more information, visit the Oracle Accessibility
Program Web site at http://www.oracle.com/accessibility/.
Accessibility of Code Examples in Documentation
Screen readers may not always correctly read the code examples in this document. The
conventions for writing code require that closing braces should appear on an
otherwise empty line; however, some screen readers may not always read a line of text
that consists solely of a bracket or brace.
Accessibility of Links to External Web Sites in Documentation
This documentation may contain links to Web sites of other companies or
organizations that Oracle does not own or control. Oracle neither evaluates nor makes
any representations regarding the accessibility of these Web sites.

xxii
Deaf/Hard of Hearing Access to Oracle Support Services
To reach Oracle Support Services, use a telecommunications relay service (TRS) to call
Oracle Support at 1.800.223.1711. An Oracle Support Services engineer will handle
technical issues and provide customer support according to the Oracle service request
process. Information about TRS is available at
http://www.fcc.gov/cgb/consumerfacts/trs.html, and a list of phone
numbers is available at http://www.fcc.gov/cgb/dro/trsphonebk.html.
Related Documents
For more information, see the following documents in the Oracle Other Product One
Release 7.0 documentation set or in the Oracle Other Product Two Release 6.1
documentation set:
■ Oracle Application Server Adapter Concepts Guide
■ Oracle Application Server Administrator’s Guide
■ Oracle Enterprise Service Bus Developer's Guide
■ Oracle BPEL Process Manager Developer's Guide
Conventions
The following text conventions are used in this document:
Convention Meaning
boldface Boldface type indicates graphical user interface elements associated
with an action, or terms defined in text or the glossary.
italic Italic type indicates book titles, emphasis, or placeholder variables for
which you supply particular values.
monospace Monospace type indicates commands within a paragraph, URLs, code
in examples, text that appears on the screen, or text that you enter.

Part IPart I
Introduction and Concepts
Part I contains the following chapters:
■ Introduction to Oracle JCA Adapters
■ Adapter Life-Cycle Management
■ Adapter Integration with Oracle Application Server Components
■ Oracle JCA Adapter for Files/FTP
■ Native Format Builder Wizard

1
Introduction to Oracle JCA Adapters 1-1
1Introduction to Oracle JCA Adapters
With the growing need for business process optimization, efficient integration with
existing back-end applications has become the key to success. To optimize business
processes, you can integrate applications by using JCA 1.5 compliant resource
adapters. Adapters support a robust, light weight, highly scalable, and
standards-based integration framework, which enables disparate applications to
communicate with each other. For example, adapters enable you to integrate packaged
applications, legacy applications, databases, and Web services. Using Oracle JCA
Adapters, you can ensure interoperability by integrating applications that are
heterogeneous, provided by different vendors, based on different technologies, and
run on different platforms.
This chapter includes the following sections:
■ Section 1.1, "Features of Oracle JCA Adapters"
■ Section 1.2, "Types of Oracle JCA Adapters"
■ Section 1.3, "Types of Oracle JCA Adapters Adapter Services"
1.1 Features of Oracle JCA Adapters
Oracle JCA Adapters provide the following benefits:
■ Provide a connectivity platform for integrating complex business processes:
Adapters integrate mainframe and legacy applications with enterprise resource
planning (ERP), customer relationship management (CRM), databases, and
messaging systems. Oracle provides adapters to connect various packaged
applications, such as SAP and Siebel, and databases. In addition, adapters
integrate middleware messaging systems, such as MQSeries and Oracle Advanced
Queuing, and legacy applications, such as CICS and Tuxedo, to provide a
complete solution.
■ Support open standards: Adapters are based on a set of standards such as J2EE
Connector Architecture (JCA) version 1.5, Extensible Markup Language (XML),
and Web Service Definition Language (WSDL). The support for standards reduces
the learning curve of a user and eliminates the dependency of users on a single
vendor.
■ Service Component Architecture (SCA) assembly model: Provides the service
details and their interdependencies to form composite applications. SCA enables
Note: This document addresses the integration of adapters with
Oracle WebLogic Server and Oracle Fusion Middleware.

Types of Oracle JCA Adapters
1-2 Oracle Fusion Middleware User's Guide for Technology Adapters
you to represent business logic as reusable service components that can be easily
integrated into any SCA-compliant application. The resulting application is known
as an SOA composite application. The specification for the SCA standard is
maintained by the Organization for the Advancement of Structured Information
Standards (OASIS).
■ Implement a Service-Oriented Architecture (SOA): The support for open standards
enables adapters to implement an SOA, which facilitates loose coupling, flexibility,
and extensibility.
■ Use native APIs: Adapters support multiple ways of interfacing with the back-end
system and provide various deployment options. Using native APIs, adapters
communicate with the back-end application and also translate the native data to
standard XML, which is provided to the client.
■ Model data: Adapters convert native APIs to standard XML and back, based on
the adapter metadata configured during design time. Adapter configurations are
defined during design time, which will be used by run-time components.
■ Facilitate real-time and bidirectional connectivity: Adapters offer bidirectional
communication with various back-end systems. This includes sending requests to
back-end systems and receiving a response. Adapters also support the real-time
event notification service. This service notifies about the back-end events
associated with successful back-end transactions for creating, deleting, and
updating back-end data. This two-way connectivity ensures faster, flexible,
efficient integration, and reduces the cost of integration.
■ Maximize availability: Oracle JCA Adapters are based on the J2CA 1.5
specification. Adapters can, therefore, fully leverage the scalability and high
availability of the underlying Oracle Application Server platform. In addition,
adapters can be deployed on the JBoss and WebSphere platforms.
■ Provide easy-to-use design-time tools: Adapters use design-time tools that provide
a graphical user interface (GUI) to configure and administer adapters for fast
implementation and deployment. In addition, the tools let you to browse,
download, and configure back-end schemas.
■ Support seamless integration with Oracle Application Server components:
Adapters integrate with Oracle Fusion Middleware. Adapters integrate with the
JCA Binding Component of the Oracle Fusion Middleware platform, thereby
seamlessly integrating with other service engines and binding components.
1.2 Types of Oracle JCA Adapters
There are three types of Oracle JCA Adapters: Oracle technology adapters, Oracle
Adapter for Oracle Applications, packaged application adapters, and legacy adapters.
Figure 1–1 illustrates the different types of adapters.

Figure 1–1 Types of Oracle JCA Adapters
This section describes the following types of adapters:
■ Oracle Technology Adapters
■ Packaged-Application Adapters
■ Legacy Adapters
1.2.1 Oracle Technology Adapters
Oracle JCA Adapters integrate Oracle Application Server with transport protocols,
data stores, and messaging middleware. These adapters include Oracle JCA Adapter
for Files, Oracle JCA Adapter for FTP, Oracle JCA Adapter for JMS, Oracle JCA
Adapter for Database, Oracle JCA Adapter for Advanced Queuing, Oracle JCA
Adapter for MQ Series, Oracle JCA Adapter for Sockets, and Oracle Adapter for
Oracle Applications. Oracle technology adapters are installed as part of Oracle Fusion
Middleware.
This section describes the File, FTP, Database, and enterprise messaging adapters that
are provided with Oracle Fusion Middleware. The adapters enable you to integrate
Oracle BPEL Process Manager or Mediator components to file systems, FTP servers,
database tables, database queues (advanced queues, or AQ), message queues, Java
Message Services (JMS), and Oracle Applications.
This section includes the following topics:
J2EE
Applications
Mediator
BPEL
PM
Oracle JCA Adapters
Oracle WebLogic Server
Technology
Oracle
Applications
Legacy
Application
Packaged
Application
Adapters
Design
Time
J2CA
SOAP

■ Section 1.2.1.1, "Architecture"
■ Section 1.2.1.2, "Design-Time Components"
■ Section 1.2.1.3, "Run-Time Components"
■ Section 1.2.1.4, "Deployment"
1.2.1.1 Architecture
Oracle technology adapters are based on J2EE Connector Architecture (JCA) 1.5
standards and deployed as a resource adapter in the same Oracle WebLogic Server as
Oracle Fusion Middleware. Oracle Adapter for Oracle Applications consists of the
same architecture as Oracle technology adapters. Figure 1–2 illustrates the architecture
of Oracle technology adapters.
Figure 1–2 Oracle Technology Adapters Architecture
1.2.1.2 Design-Time Components
During design time, Oracle technology adapters use Oracle JDeveloper to generate the
adapter metadata. The request-response service, also known as J2CA outbound
interaction, and the event-notification service, also known as J2CA inbound
interaction, are described in J2CA binding configuration files. These binding
configuration files consist of J2CA-centric XML markup. The J2CA binding
configuration files are used by the JCA Binding Component to seamlessly integrate the
J2CA 1.5 resource adapter with Oracle Fusion Middleware.
For more information about integration of Oracle technology adapters with Oracle
Fusion Middleware, see Section 3.2, "Adapter Integration with Oracle Fusion
Middleware.".
J2EE
Applications
Mediator
BPEL
PM
Oracle JCA Adapters
Files/FTP
Socket
Oracle
Applications
JMS/AQ
Database
JDeveloper
Adapter
Wizard
J2CA

Example 1–1 Generating WSDL and Binding Configuration Files for Oracle JCA Adapter
for Database
By using Oracle JDeveloper, you can configure Oracle JCA Adapter for Database. This
adapter helps you to perform data manipulation operations, call stored procedures or
functions, and publish database events in real time. To configure adapter definitions,
drag and drop Database Adapter from the Component Palette to the External
References swim lane.
Figure 1–3 shows how to browse through the Import Tables window to select the
required tables for the adapter.
Figure 1–3 Browsing for Required Tables
Figure 1–4 shows how to specify the WSDL settings for Oracle JCA Adapter for
Database.
Figure 1–4 Specifying WSDL Settings

Next, you must establish a database connection, select an operation type, and select
the required tables. The run-time connection parameters are specified in the
weblogic-ra.xml file and linked to a Java Naming and Directory Interface (JNDI)
name, which is specified during design time. Figure 1–5 shows the creation of a new
database connection.
Figure 1–5 Creating a New Database Connection
Finally, Oracle JDeveloper generates a WSDL file and a binding configuration file with
the J2CA binding for the Oracle JCA Adapter for Database, as shown in Figure 1–6.

Figure 1–6 Structure of a JCA File
1.2.1.3 Run-Time Components
The run-time component of Oracle technology adapters is the J2CA 1.5 resource
adapter for the specific back-end application. Oracle technology adapters are deployed
in the J2CA container of the Oracle WebLogic Server. Oracle Fusion Middleware
integrates with these J2CA 1.5 adapters through the JCA Binding Component, which
converts Web service messages into J2CA interactions and back.
Oracle Fusion Middleware uses JCA Binding Component to integrate the
request-response service (J2CA outbound interaction) with a SCA composite reference
and publish the adapter events to a SCA composite service.
For more information about integration with Oracle Fusion Middleware, see Chapter
"Adapter Integration with Oracle Application Server Components".
1.2.1.4 Deployment
Oracle technology adapters are deployed as J2CA 1.5 resource adapters within the
same Oracle WebLogic Server container as that of Oracle Fusion Middleware
during installation. Although Oracle technology adapters are physically deployed as
J2CA 1.5 resource adapters, their logical deployment involves creating the Connection
Factory entries for the J2CA 1.5 resource adapter by editing the weblogic-ra.xml
file and using Oracle JDeveloper during design time. By using Oracle JDeveloper, you
specify the JNDI name, which acts as a placeholder for the connection used when your
composite is deployed to the Oracle WebLogic Server. This enables you to use different
databases for development and later production. However, for the logical deployment
changes (that is, only if you are creating a new outbound connection) to take effect, the
Oracle WebLogic Server container process should be updated. However, if you are
updating any outbound connection property for an existing JNDI, then you must
restart the Oracle WebLogic Server.

1.2.2 Packaged-Application Adapters
Packaged-application adapters integrate Oracle Application Server with various
packaged applications, such as SAP and Siebel. These adapters include OracleAS
Adapter for PeopleSoft, OracleAS Adapter for SAP R/3, OracleAS Adapter for Siebel,
and OracleAS Adapter for J.D. Edwards. Packaged-application adapters are available
as part of the OracleAS Adapters CD.
This section describes the architecture of packaged-application adapters.
■ Section 1.2.2.3, "Run-Time Components"
Packaged-application adapters can be deployed as J2EE Connector Architecture
(J2CA) 1.5 resource adapters or as Web service servlets within the Oracle WebLogic
Server container. Packaged-application adapters support the Web Service Definition
Language (WSDL) and Simple Object Access Protocol (SOAP) interface, in addition to
a J2CA interface. J2CA and Web service deployments of packaged-application
adapters should have a repository project. In J2CA deployment, the resource adapter
points to a repository project that can contain multiple back-end connection objects.
The deployment descriptor, weblogic-ra.xml, points to the J2CA repository project
and the connection name to access within the J2CA repository project. In the WSDL
deployment, the WSDL repository project consists of a set of WSDL files that describe
the adapter metadata.
The architecture of packaged-application adapters consists of OracleAS Adapter
Application Explorer (Application Explorer), J2CA 1.5 resource adapter, and Business
Services Engine (BSE).
Figure 1–7 illustrates the architecture of packaged-application adapters:
Note: Only four packaged-application adapters, OracleAS Adapter
for SAP, OracleAS Adapter for Siebel, OracleAS Adapter for
Peoplesoft, and OracleAS Adapter for J.D. Edwards, support WSDL
and SOAP extensions in this release. The architecture of the OracleAS
Adapter for Oracle Applications is similar to Oracle technology
adapters.

Figure 1–7 Packaged-Application Adapters Architecture
This section describes the components of the packaged-application adapter
architecture.
■ Section 1.2.2.1.1, "Application Explorer"
■ Section 1.2.2.1.2, "BSE"
■ Section 1.2.2.1.3, "J2CA 1.5 Resource Adapter"
1.2.2.1.1 Application Explorer
Application Explorer is a Java swing-based design-time tool for configuring
packaged-application adapters. Using Application Explorer, you can configure the
back-end application connection, browse the back-end application schemas, and
expose these schemas as adapter services. Application Explorer is shipped with
packaged application-specific plug-ins for browsing the back-end application-specific
metadata.
You can use Application Explorer to create repository projects for either OracleAS
Adapter J2CA or BSE. Each repository project can consist of multiple back-end
application connections. The schemas are represented as either XML Schema
Definition (XSD) for the OracleAS Adapter J2CA interface or as a WSDL with SOAP
binding.
1.2.2.1.2 BSE
Application Explorer works in conjunction with the BSE, which is deployed in the
Oracle WebLogic Server container of the Oracle Application Server. BSE uses SOAP as
a protocol for accepting requests from clients, interacting with the back-end
application, and sending responses from the back-end application back to clients.
J2EE
Applications
Mediator
BPEL
PM
Oracle JCA Adapters
Siebel
J.D.Edwards
Sap
Peoplesoft
Adapter
Application
Explorer
J2CA
BSE
SOAP

1.2.2.1.3 J2CA 1.5 Resource Adapter
The J2CA 1.5 resource adapter consists of a Channel component for receiving back-end
events.
Application Explorer is used to configure packaged-application adapters during
design time. This tool is used to create a repository project for the J2CA 1.5 resource
adapter, which contains a list of back-end connections. Application Explorer exposes
back-end metadata as XSD and WSDL with J2CA extensions. The XSD metadata is
used by the Oracle WebLogic Server application clients for integration through the
J2CA Common Client Interface (CCI) Application Programming Interface (API). The
WSDL with J2CA extension is used for integration with Business Process Execution
Language for Web Services (BPEL) Process Manager. The BSE metadata can be defined
as WSDL or SOAP.
Figure 1–8 shows the Application Explorer.
Figure 1–8 Application Explorer
Example 1–2 Generating XML Request Schema for OracleAS Adapter for SAP
You can use Application Explorer to establish a connection for OracleAS Adapter for
SAP. For this, you must first define a target to OracleAS Adapter for SAP, as shown in
Figure 1–9 and Figure 1–10.

Figure 1–9 Selecting OracleAS Adapter for SAP
Figure 1–10 Defining a Target to OracleAS Adapter for SAP
After you have explored the SAP business function library and have selected an object,
you can use Application Explorer to create the XML request schema and the XML
response schema for that function. To view the XML for each schema type, select the
required tab, as shown in Figure 1–11:
Figure 1–11 Viewing the XML Schema
The run-time components of packaged-application adapters include J2CA 1.5 resource
adapter, BSE, and servlet. The Oracle WebLogic Server application clients use the CCI
API to directly interface with the J2CA 1.5 resource adapter. The J2CA 1.5 resource
adapter integrates with Oracle Fusion Middleware through the JCA Binding
Component. During run time, the JCA Binding Component translates the Oracle
Fusion Middleware service requests to J2CA calls and back based on the adapter
metadata (WSDL and binding configuration) configured during design time.
During run time, the WSDL files generated during design time are consumed by the
integrating components. For example, Oracle Fusion Middleware uses JCA Binding
Component to integrate the request-response service (J2CA outbound interaction) with
a BPEL process invoke activity and to publish adapter events to a BPEL process
receive activity.
For more information about integrating with Oracle Fusion Middleware, see
Section 3.2, "Adapter Integration with Oracle Fusion Middleware".
1.2.2.4 Deployment
Packaged-application adapters are deployed as J2CA 1.5 resource adapters within the
Oracle WebLogic Server J2CA container during installation. The adapter needs to be in
the same Oracle WebLogic Server container as Oracle BPEL Process Manager for
integration.
You can integrate any Web service client with the BSE servlet. The BSE exposes the
underlying back-end functionality as Web services, which can be either WSDL or
SOAP. Oracle BPEL Process Manager can integrate with the BSE layer, as well, through
WSDL and SOAP binding.

BSE is deployed as a servlet within the Oracle WebLogic Server container during
installation. BSE can be remotely located and need not be in the same container as the
Oracle BPEL Process Manager.
1.2.3 Legacy Adapters
Legacy adapters integrate Oracle Application Server with legacy and mainframe
applications. These adapters include OracleAS Adapter for Tuxedo, OracleAS Adapter
for CICS, OracleAS Adapter for VSAM, OracleAS Adapter for IMS/TM, and OracleAS
Adapter for IMS/DB. Legacy adapters are available as part of the OracleAS Adapters
CD.
■ Run-Time ComponentsSection 1.2.3.3, "Run-Time Components"
Legacy adapters include the following components in the architecture
■ Section 1.2.3.1.1, "Oracle Connect"
■ Section 1.2.3.1.2, "Oracle Studio"
■ Section 1.2.3.1.3, "J2CA Adapter"
Figure 1–12 illustrates the architecture of legacy adapters.
Note that Changed Data Capture (CDC) adapters have the same architecture as well.
Figure 1–12 Legacy Adapter Architecture
1.2.3.1.1 Oracle Connect
Oracle JCA Adapters
J2CA
VSAM
Tuxedo
IMS DB/TM
CICS
Oracle
Studio
Oracle Connect
Mainframe/Legacy
J2EE
Applications
Mediator
BPEL
PM

Oracle Connect is a component that resides on the legacy and mainframe platforms. It
consists of native adapters for communicating with the mainframe application and
data stores. Oracle Connect consists of the following components:
■ Server Processes
■ Native Adapters
■ Daemon
■ Repository
Server Processes
Oracle Connect consists of multiple servers to process client requests.
Native Adapters
Oracle Connect consists of various embedded native adapters to communicate with
Tuxedo and IMS-TM transaction systems, and database drivers to communicate with
various databases and file systems on mainframe systems such as VSAM and IMS-DB.
The native adapters convert application structures, such as the legacy COBOL
applications data, to and from XML. The XSD schema is used for precise mapping
between mainframe data and standard XML data.
Daemon
Daemon is an RPC-based listener that manages and maintains multiple server
configurations. It runs on every computer running Oracle Connect and handles user
authentication and authorization, connection allocation, and server process
management.
When a client requests for a connection, the daemon allocates a server process to
handle this connection. The allocated server process may be a new process or any
process that might have been already running. Further communication between the
client session and the server process is direct and does not involve the daemon.
However, the daemon is notified when the connection ends and the server process is
either killed or being used by another client.
The daemon supports multiple server configurations called workspaces. Each
workspace defines accessible data sources, applications, environment settings, security
requirements, and server allocation rules. The daemon authenticates clients, authorizes
requests for a server process within a certain server workspace, and provides clients
with the required servers. The allocation of servers by the daemon is based on the
workspace that the client uses. Thus, a client can access a data source using one
workspace, where a server process is allocated from an existing pool of servers, or the
client can access a data source using a different workspace, where a new server process
is allocated for each client request. A fail-safe mechanism enables the specification of
alternate daemons, which function as a standby for high availability.
Repository
Oracle Connect supports a repository for storing the XML-based schema and
configuration information. There is a single repository for each Oracle Connect
instance. The repository stores the following information:
■ Oracle Connect configuration settings (including the Daemon settings to control
client/server communication)
■ User profiles to enable single sign-on to multiple back-end applications and data
sources

■ Adapter metadata for each adapter, which includes adapter request-response and
event services
1.2.3.1.2 Oracle Studio
Oracle Studio is the design-time tool for configuring the Oracle AS Adapters for
mainframes. It enables you to configure the services, events, and connection
information for native adapters. The configuration information is stored in the Oracle
Connect repository on the legacy or mainframe application. In addition, it enables you
to do management and monitoring of Oracle Connect. The Oracle Studio is available
only on the Windows platform. The Oracle Studio is based on the Eclipse GUI
framework.
1.2.3.1.3 J2CA Adapter
The J2EE Connector Architecture (J2CA) adapter forwards the Oracle WebLogic Server
application client requests to the Oracle Connect application. Oracle Connect
communicates with the mainframe application and forwards the response back to the
J2CA adapter. The response might contain the transaction data or might contain the
exception data if the request generated an error. Oracle Fusion Middleware integrates
with Oracle Connect through the J2CA Legacy adapter.
To configure legacy adapters during design time, use Oracle Studio, as shown in
Figure 1–13.
Figure 1–13 Oracle Studio
Example 1–3 Configuring OracleAS Adapter for Tuxedo
Using Oracle Studio, you can configure OracleAS adapter for Tuxedo, as shown in
Figure 1–14 and Figure 1–15.

Figure 1–14 Configuring OracleAS Adapter for Tuxedo
Figure 1–15 Selecting the Types of Interactions for OracleAS Adapter for Tuxedo
During run time, WSDL files generated during design time are consumed by the
integrating components. For example, Oracle Fusion Middleware uses the JCA
Binding Component to integrate the request-response service (J2CA outbound
interaction) with a BPEL Invoke activity and to publish the events to a BPEL process
receive activity.
For more information, see Section 3.2, "Adapter Integration with Oracle Fusion
Middleware."

Types of Oracle JCA Adapters Adapter Services
1.2.3.4 Deployment
Legacy adapters are deployed as J2CA resource adapters within the Oracle WebLogic
Server J2CA container during installation. The adapter must be in the same Oracle
WebLogic Server container as that of the Oracle Fusion Middleware for integration.
1.3 Types of Oracle JCA Adapters Adapter Services
Adapters provide the following types of services to facilitate communication between
applications:
■ Section 1.3.1, "Request-Response (Outbound Interaction) Service"
■ Section 1.3.2, "Event Notification (Inbound Interaction) Service"
■ Section 1.3.3, "Metadata Service"
1.3.1 Request-Response (Outbound Interaction) Service
Adapters support the synchronous request-response service. The adapters receive
requests from adapter clients, translate these requests into the native back-end data
format, and call the appropriate method in the back-end application. In addition, the
request-response service retrieves the back-end response to the JCA Binding
Component after performing reverse translation. In J2CA terminology, this type of
service is also known as outbound interaction.
The request-response service can be used to create, delete, update, and query back-end
data as well as to call back-end workflows and transactions. For example, an Oracle
WebLogic Server application client can use OracleAS Adapter for SAP to create a
customer within the SAP application.
Figure 1–16 illustrates the request-response service.
Figure 1–16 Request-Response Service
1.3.2 Event Notification (Inbound Interaction) Service
Adapters support the event-notification service, which is an asynchronous
communication paradigm. In J2CA terminology, this type of service is also known as
inbound interaction.
Adapters either listen or poll for back-end event changes. When listening for events,
an adapter registers as a listener for the back-end application that is configured to
push events to the adapter. The adapter can also poll the back-end application, which
is usually a database or file, for the events required by the client application.
Back-End
ApplicationNative API
Oracle
Application
Server
AdapterAdapter
Client
Request-Response
CCI
Request-Response

The event-notification service can be used to keep a track of back-end events
associated with successful back-end transactions for creating, deleting, and updating
back-end data.
Figure 1–17 illustrates the event-notification service.
Figure 1–17 Event-Notification Service
1.3.3 Metadata Service
The adapter metadata definition stores information about the back-end connection and
schemas for business objects and services. Adapters consist of a design-time
component for browsing and storing metadata and a run-time component for running
services. The adapter metadata definitions are generated as XML Schema Definition
(XSD), WSDL, and binding configuration files. Figure 1–18 illustrates the metadata
interaction.
Figure 1–18 Metadata Service
Publish
Native API
Oracle
Application
Server
Adapter
SPI
PublishAdapter
Client
Back-End
Application
Back-End Applicaton
Browse & Select
Back-End Application
Schemas
Adapter
Design-Time Tool
File Repository
Native API
Stores
Configuration
(XSD/WSDL)

Adapter Life-Cycle Management 2-1
2
Adapter Life-Cycle Management
Oracle JCA Adapters are based on J2EE Connector Architecture (J2CA) 1.5 standards
and deployed in the Oracle WebLogic Server. The life cycle of Oracle JCA Adapters
depend on Oracle Fusion Middleware. These adapters integrate with Oracle Fusion
Middleware through the JCA Binding Component.
■ Section 2.1, "Installing Oracle JCA Adapters"
■ Section 2.2, "Starting and Stopping Oracle JCA Adapters"
■ Section 2.3, "Physically Deploying Oracle JCA Adapters"
■ Section 2.4, "Adding an Adapter Connection Factory"
■ Section 2.5, "Handling Deployment Plan When Working on a Remote Oracle SOA
Server"
■ Section 2.6, "Setting the Trace Level of Oracle JCA Adapters"
■ Section 2.7, "Viewing Adapter Logs"
■ Section 2.8, "Using Header Properties for Oracle JCA Adapters"
■ Section 2.9, "Describing XML Data Structure"
■ Section 2.10, "Error Handling"
■ Section 2.11, "How Oracle JCA Adapters Ensure No Message Loss"
■ Section 2.12, "Streaming Large Payload"
■ Section 2.13, "Composite Availability and Inbound Adapters"
■ Section 2.14, "Manually Deploying an Adapter RAR File"
■ Section 2.15, "Defining Adapter Interface by Importing an Existing WSDL"
■ Section 2.16, "Creating an Application Server Connection for Oracle JCA Adapters"
■ Section 2.17, "Deploying Oracle JCA Adapter Applications from Oracle
JDeveloper"
■ Section 2.18, "Testing Applications"
■ Section 2.19, "Batching and Debatching Support"
■ Section 2.20, "Migrating Repositories"
■ Section 2.21, "Recommended Setting for Data Sources Used by Oracle JCA
Adapters"

Installing Oracle JCA Adapters
2.1 Installing Oracle JCA Adapters
Oracle JCA Adapters and Oracle Adapter for Oracle Applications are available as part
of the Oracle Fusion Middleware install. In addition, these adapters support both
Oracle WebLogic Server and middle tier deployments. Packaged-application adapters
and legacy adapters are available as part of the Oracle Applications Adapter CD.
These adapters support middle tier deployment only.
2.2 Starting and Stopping Oracle JCA Adapters
Oracle JCA Adapters are deployed as JCA 1.5 resource adapters. Therefore, to start or
stop an adapter, every resource adapter must implement the start
(BootstrapContext) and stop methods as part of the SPI interface. Oracle JCA
Adapters are started when an SOA composite using them starts a JCA outbound
interaction. Adapters can also be started when an SOA composite is itself loaded for
inbound interactions or when adapters publish events to the Oracle BPEL process.
Once you have started an adapter, you can stop the adapter by shutting down the
Oracle WebLogic Server or by stopping the J2EE application within Oracle Fusion
Middleware. In this release, the JCA Binding Component acts as a part of the JCA 1.5
container.
2.3 Physically Deploying Oracle JCA Adapters
Oracle JCA Adapters are deployed as JCA 1.5 resource adapters in an Oracle WebLogic
Server container. Adapters are packaged as Resource Adapter Archive (RAR) files
using the Java Archive (JAR) format. The physical deployment of adapters involves
using the RAR file and registering the adapters as connectors with the underlying
Oracle WebLogic Server or the middle tier platform. The RAR file contains the ra.xml
file, which is the deployment descriptor XML file containing deployment-specific
information about the resource adapter. In addition, the RAR file contains declarative
information about the contract between Oracle WebLogic Server and the resource
adapter.
In addition to the ra.xml file in the.rar file, adapters package the
weblogic-ra.xml template file. The weblogic-ra.xml file is used to define
resource adapter ConnectorFactory objects (logical deployment). The
weblogic-ra.xml file is the Oracle WebLogic Server-specific deployment descriptor
for a resource adapter. It contains deployment configurations for deploying resource
adapters to Oracle WebLogic Server, which includes the back-end application
connection information as specified in the deployment descriptor of the resource
adapter, Java Naming and Directory Interface (JNDI) name to be used, connection
pooling parameters, resource principal mapping mechanism, and configurations.
For more information about creating connection factory, see Oracle Fusion Middleware
Installation Guide for Oracle WebLogic Server.
2.4 Adding an Adapter Connection Factory
The logical deployment of adapters refers to the creation of ConnectionFactory
objects in the weblogic-ra.xml deployment descriptor file. To add the connection
information and assign to a JNDI name, edit the corresponding weblogic-ra.xml
file of the resource adapter by either using Oracle WebLogic Server Administration
Console or WLST scripts. The weblogic-ra.xml file contains run-time connection
parameters for an adapter.

Adding an Adapter Connection Factory
For more information about creating connection factory, see Oracle Fusion Middleware
Installation Guide for Oracle WebLogic Server.
The following steps describe how to set up a Database connection factory in the Oracle
WebLogic Server Administration Console.
■ Section 2.4.1, "Creating a Data Source"
■ Section 2.4.2, "Creating a Connection Pool"
2.4.1 Creating a Data Source
To create a data source:
1. Navigate to http://servername:portnumber/console.
2. Use the required credentials to open the Home page of the Oracle WebLogic
Server Administration Console.
The Home page of the Oracle WebLogic Server Administration Console is
displayed.
3. Under Domain Structure, select Services, JBDC, and then click DataSources.
The Summary of JDBC Data Sources page is displayed.
4. Click New. The Create a New JDBC Data Source page is displayed.
5. Enter the following values for the properties to be used to identify your new JDBC
data source:
■ Name: soademoDatabase
■ JNDI Name: jdbc/soademoDatabase
■ Database Type: Oracle
Retain the default value for Database driver.
6. Click Next. The Create a New JDBC Data Source Transaction Options page is
displayed.
7. Click Next. The Create a New JDBC Data Source Connection Properties page is
displayed.
8. Enter the connection properties in the Connection Properties page, and then click
Next.
The Create a New JDBC Data Source Test Database Connection page is displayed.
9. Click Test Configuration to test the database availability and the connection
properties you provided. A message stating that the connection test succeeded is
displayed at the top of the Create a New JDBC Data Source Test Database
Connection page.
10. Click Next. The Create a New JDBC Data Source Select Targets page is displayed.
11. Select a target, and then click Finish. You have created a data source.
The Summary of JDBC Data Sources page is displayed. This page summarizes the
JDBC data source objects that have been created in this domain. The Data Source
that you created is displayed in this list.

Adding an Adapter Connection Factory
2.4.2 Creating a Connection Pool
To create a connection pool:
1. Under Domain Structure, click Deployments.
The Summary of Deployments page is displayed.
2. Click the Database adapter name from the Deployments list.
The Settings for DbAdapter page is displayed.
3. Click Configuration tab, and then click Outbound Connection Pools tab.
The Outbound Connection Pool Configuration Table is displayed.
4. Click New.
5. Select javax.resource.cci.ConnectionFactory, and then click Next.
The Create a New Outbound Connection page is displayed.
6. In the JNDI Name: field, enter eis/DB/soademoDatabase.
7. Click Finish.
The Settings for DbAdapter page displaying a table of Outbound Connection Pool
groups and instances for this resource adapter is displayed.
The configuration changes that you made must be stored in a new deployment
plan.
8. In the Path field, select or enter the path of a deployment plan file. The path must
end with ".xml".
9. In the Properties field, enter the value for xADataSourceName as
jdbc/soademoDatabase
10. Click Save.
11. Under Domain Structure, click Deployments.
Note: The JNDI value that you enter in this step is not the same
value that you entered in Step 5 in Section 2.4.1, "Creating a Data
Source." The JNDI name specified in this step must match the value
you enter in your database connection you create when building your
application later.
Note: If the Adminserver is running on computer A and the Oracle
SOA server is running on computer B, then you must copy the
deployment plan file to computer B before you activate changes made
on the Oracle SOA server. If you try to activate changes without
copying the deployment plan to the Oracle SOA Server computer,
then a NullPointerException is thrown.
Note: Note that the properties do not get saved when you click Save
as mentioned in this step. Instead, you have to press Enter in the
keyboard to save the changes you made.

Setting the Trace Level of Oracle JCA Adapters
The Summary of Deployments is displayed.
12. Do either of the following steps:
a. Select the DbAdapter check box, and then click Update.
The Update Application Assistant page is displayed.
b. Select Redeploy this application, and then click Finish.
The Summary of Deployments page stating that the deployment you selected
is updated is displayed.
13. Under Domain Structure, click Deployments, DbAdapter, Configuration, and
then Outbound Connection Pools.
Notice that the value of the xADataSource property that you entered in Step 9 is
displayed in the Connection Factory Interface tab.
2.5 Handling Deployment Plan When Working on a Remote Oracle SOA
Server
If the Adminserver is running on computer A and the Oracle SOA server is running on
computer B, then you must copy the deployment plan file to computer B before you
activate changes made on the Oracle SOA server. If you try to activate changes without
copying the deployment plan to the Oracle SOA Server computer, then a
NullPointerException is thrown.
2.6 Setting the Trace Level of Oracle JCA Adapters
Set the trace level as follows:
■ Oracle JCA Adapters and Oracle Adapter for Oracle Applications: Set the log level
to, for example, TRACE:32 in the logger oracle.soa.adapter.
For more information about setting trace levels for adapters, see Oracle Fusion
Middleware Administrator's Guide.
■ Packaged-application adapters: For outbound interactions, set the Loglevel
property for packaged-application adapters in the weblogic-ra.xml file.
■ Legacy adapters: The trace level for Oracle Connect, and the mainframe server can
be set by using Oracle Studio.
The following are the steps to set the trace level by using the Oracle Enterprise
Manager Console:
1. Navigate to http://servername:portnumber/em.
The Oracle Enterprise Manager Console home page is displayed.
2. Right-click soa-infra from the SOA Folder in the Navigator tree in the left pane.
A menu is displayed.
3. Select Logs, and the Log Configuration, as shown in Figure 2–1.
Note: If you are adding a new value for the outbound connection
pool, then you do not have to re-start the Managed server or the
Admin server. However, if you edit any property of an existing
connection pool, then you must re-start the server.

Setting the Trace Level of Oracle JCA Adapters
Figure 2–1 Navigating to the Log Configuration Page
The Log Configuration page is displayed.
4. Locate oracle.soa.adapter in the Logger Name list, and change the log level in the
Oracle Diagnostic Logging Level (Java Level) field. In this example, select Trace:32
(FINEST) from the list, as shown in Figure 2–2.
Figure 2–2 The Log Configuration Page
Note: To ensure that log levels persist across component restarts,
select Loggers With Persistent Log Level State from the View list. By
default, the log level is set for runtime loggers. Runtime loggers do
not persist across component restarts.

Using Header Properties for Oracle JCA Adapters
2.7 Viewing Adapter Logs
You can view the logs for Oracle JCA Adapters as follows:
■ Oracle JCA Adapters and Oracle Adapter for Oracle Applications: These adapters
implement the LogManager interface of JCA Binding Component, which redirects
log files in the Oracle Diagnostic Logging (ODL) format. For both outbound and
inbound interactions, the log files are redirected to the soa-diagnostic.log
file.
The log files for Oracle SOA Suite that is deployed to the server-soa managed
server are located in:
MW_HOME/user_projects/domains/domain_
name/servers/server-soa/logs/soa-diagnostic.log
For more information about searching and viewing log files, see Oracle Fusion
Middleware Administrator's Guide.
■ Packaged-application adapters: These adapters do not implement the
LogManager interface because it is not part of the J2CA 1.5 standard. Therefore,
for system components the log outputs are redirected to
ORACLE_INSTANCEdiagnosticslogscomponent_typecomponent_
name. For outbound interactions, the logs are directed to the same location. On the
other hand, for inbound interactions, logs are redirected to
soa-diagnostic.log.
■ Legacy adapters: In addition to the J2CA resource adapter, legacy adapters
consists of Oracle Connect, which consists of native adapters for communicating
with the mainframe application and data stores. Oracle Connect logs can be
viewed using Oracle Studio, which is the mainframe adapter design-time tool and
Oracle Connect management tool. Oracle Connect generates various types of logs,
such as the daemon log, workspace log, and server process log.
2.8 Using Header Properties for Oracle JCA Adapters
Oracle JCA Adapters expose the underlying back-end operation specific properties as
header elements and allow the manipulation of these elements within a business
process.
For more information about Oracle JCA Adapters, see Appendix A, "Oracle JCA
Adapter Properties."
Note that you can add, delete, or revert Oracle JCA Adapters properties from the
Oracle Enterprise Manager Console. Based on how the adapters behave when
properties are added, deleted, or updated from the Oracle Enterprise Manager
Console, they are classified as follows:
■ Section 2.8.1, "The InteractionSpec or ActivationSpec Properties"
■ Section 2.8.2, "Endpoint Properties"
2.8.1 The InteractionSpec or ActivationSpec Properties
These properties require the adapter endpoint to be recycled. For properties in this
group, you can change their values from the EM console. However, to change the
composition (add or remove) of these properties, you must use Oracle JDeveloper
because of property-dependency constraint validation.

Using Header Properties for Oracle JCA Adapters
The following sections list the InteractionSpec/ActivationSpec and endpoint
properties of Oracle JCA Adapters:
■ Section 2.8.1.1, "Oracle AQ Adapter Properties"
■ Section 2.8.1.2, "Oracle Database Adapter Properties"
■ Section 2.8.1.3, "Oracle File Adapter Properties"
■ Section 2.8.1.4, "Oracle FTP Adapter Properties"
■ Section 2.8.1.5, "Oracle JMS Adapter Properties"
■ Section 2.8.1.6, "Oracle MQ Series Adapter Properties"
■ Section 2.8.1.7, "Oracle Socket Adapter Properties"
2.8.1.1 Oracle AQ Adapter Properties
For more information about Oracle AQ Adapter properties, see chapter "Configuring
Service and Reference Binding Components" in the Oracle Fusion Middleware
Administrator's Guide for Oracle SOA Suite.
2.8.1.2 Oracle Database Adapter Properties
For more information about Oracle Database Adapter properties, see chapter
"Configuring Service and Reference Binding Components" in the Oracle Fusion
Middleware Administrator's Guide for Oracle SOA Suite.
2.8.1.3 Oracle File Adapter Properties
For more information about Oracle File Adapter properties, see chapter "Configuring
2.8.1.4 Oracle FTP Adapter Properties
For more information about Oracle FTP Adapter properties, see chapter "Configuring
2.8.1.5 Oracle JMS Adapter Properties
For more information about Oracle JMS Adapter properties, see chapter "Configuring
2.8.1.6 Oracle MQ Series Adapter Properties
For more information about Oracle MQ Series Adapter properties, see chapter
2.8.1.7 Oracle Socket Adapter Properties
For more information about Oracle Socket Adapter properties, see chapter

Error Handling
2.8.2 Endpoint Properties
Changes to these properties are notified to the adapter without restarting the endpoint.
You can add or remove properties that belong to this group. The endpoint properties
represent auxiliary tuning properties, which an adapter might want to expose. The
auxiliary tuning properties include values such as various time intervals, thresholds,
and intervals. These endpoint properties are not exposed through the
interactionspec or activationspec properties.
For more information about endpoint properties, see chapter "Configuring Service and
Reference Binding Components" in the Oracle Fusion Middleware Administrator's Guide
for Oracle SOA Suite.
2.9 Describing XML Data Structure
The record implementation for Oracle JCA Adapters is XMLRecord. All adapter
interactions are started with XMLRecord. Each JCA record must be an implementation
of oracle.tip.adapter.api.record.XMLRecord. Each instance of XMLRecord
contains the RecordElement. RecordElements payload that contains data. In
addition, each RecordElement contains one BLOB of data, which can either be a
UTF-8-encoded XML string or a binary opaque byte stream.
XMLRecord consists of the following methods:
■ getPayloadRecordElement: Retrieves the payload RecordElement.
■ setPayloadRecordElement: Sets the payload record element of the
XMLRecord.
2.10 Error Handling
The Oracle JCA Adapters provide error handling capabilities, as listed in the following
sections.
■ Section 2.10.1, "Handling Rejected Messages"
■ Section 2.10.2, "Handling Connection Errors"
■ Section 2.10.3, "Handling Message Errors"
2.10.1 Handling Rejected Messages
The messages that error out before being posted to the service infrastructure are
referred to as rejected messages. For example, Oracle File Adapter picks a file having
data in CSV format and tries to translate it to the XML format (using NXSD). Now, if
there is any error in the translation, then this message is rejected and will not be posted
to the target composite. Primarily, adapters and binding components are the ones
which generate rejected messages.
Errors or faults arising after the message is posted to Service Infrastructure layer are
not rejected. These faulted messages are handled by the Service Infrastructure
components and will not be considered as rejected messages.
Adapters and other binding components (for example, WS Binding Component) reject
messages which error out at the binding level, that is, before entering the Service
Infrastructure layer. All rejected messages are stored in the Database with payload.

Error Handling
■ Section 2.10.1.1, "Configuring Rejection Handlers"
■ Section 2.10.1.2, "Rejected Message Handlers"
■ Section 2.10.1.3, "Checking for Rejected Messages"
2.10.1.1 Configuring Rejection Handlers
In the 10.x release, rejection handlers were defined in the deployment descriptor
(bpel.xml) of an Oracle BPEL process. However, in the 11g release, you must define
rejection handlers by using fault policies.
Note that only one action handler can be specified for inbound rejection handlers.
You must create two files named fault-policies.xml and
fault-bindings.xml, and copy them to the SOA project directory in Oracle
JDeveloper, as described in the following steps:
1. You must define a fault policy for the rejected messages in the
fault-policies.xml file, which is stored along with composite.xml in the
Oracle JDeveloper project directory.
The following is an example of fault policy:
<?xml version="1.0" encoding="UTF-8"?>
<faultPolicies>
<faultPolicy version="2.0.1" id="RejectedMessages">
<Conditions> 
<faultName xmlns:rjm="http://schemas.oracle.com/sca/rejectedmessages"
name="rjm:<SERVICE_NAME>"> 
<condition>
<action ref="writeToFile"/> 
</condition>
</faultName>
</Conditions>
<Actions> 
<Action id="writeToFile">
<fileAction>
<location>/tmp/rej_msgs</location>
<fileName>emp_%ID%_%TIMESTAMP%.xml</fileName>
</fileAction>
</Action>
</Actions>
</faultPolicy>
</faultPolicies>
2. You must associate the fault policy with a service endpoint of the composite in
fault-bindings.xml, as shown in the following example:
<faultPolicyBindings version="2.0.1"
xmlns="http://schemas.oracle.com/bpel/faultpolicy"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...
<service faultPolicy="RejectedMessages">
<name>Read</name>
</service>
...
</faultPolicyBindings>

Error Handling
3. Copy the fault-policies.xml and the fault-bindings.xml files to your
SOA Composite project directory.
4. Deploy the SOA Composite project.
2.10.1.2 Rejected Message Handlers
The following are the rejected message handlers:
■ Available Action Handlers
The following are the system defined error handlers, which you can configure in
fault policies:
1. Web Service Handler
– Predefined WSDL interface has to be implemented by the target service.
– SOAP bindings will be used for the Web service invocation.
– Native payloads can be passed as WS-attachments, as shown in the
following example:
<Action id="ora-ws">
<invokeWS uri="WebServiceURI"/>

</Action>
– WSDL Interface Details
This must have only one port type, only input operation, and a schema for
input message, as shown in the following example:
<?xml version="1.0"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://xmlns.oracle.com/pcbpel/errorHandling"
xmlns:tns="http://xmlns.oracle.com/pcbpel/errorHandling"
elementFormDefault="qualified">
<element name="RejectedMessage" type="tns:RejectedMessageType">
<complexType name="RejectedMessageType"/>
<sequence>
<element name="MessageHeader" type="string"/>

<element name="MessagePayload" type="string"/>

<element name="RejectionReason" type="string"/>
</sequence>
<attribute name="RejectionId" type="string"/>
</complexType>
</schema>
2. Custom Java Handler
Note: If you do not configure rejection handlers as mentioned in
Section 2.10.1.1, "Configuring Rejection Handlers", then a default
file-based rejection handler will kick in and the rejected messages will
be directed to <domain_home>/rejmsgs/<wls_server_
name>/<composite_name>.
Also, note that you can configure rejected messages with a Mediator
Component in the same fault policy as that of Oracle BPEL Process
Manager.

Error Handling
– A predefined Java interface has to be implemented by the target class, as
shown in the following example:
<Action id="ora-custom">
<javaAction className="mypackage.myClass"
defaultAction="ora-terminate">
<returnValue value="SUCCESS" ref="ora-file"/>
<returnValue value="FAILED" ref="ora-ws"/>
</javaAction>
</Action>
– Java Interface Details
The following code snippet is an example:
package oracle.integration.platform.faultpolicy;
public interface IFaultRecoveryJavaClass
{
public void handleRetrySuccess( IFaultRecoveryContext ctx);
public String handleFault( IFaultRecoveryContext ctx);
}
3. Queue
The rejected message is enqueued to a queue as a JMS message with the
appropriate context and payload, as shown in Example 1: Using a Standalone
Database and Example 2: Using an RAC Database.
Example 1: Using a Standalone Database
<Action id="ora-queue">
<enqueue uri="QueueURI"/> 
</Action>
Example 2: Using an RAC Database
<Action id="ora-queue">
<enqueue uri="QueueURI"/> 
</Action>
4. File
The rejected message is stored in the file system with the proper context and
payload, as shown in the following example. Payload file will be created at the
configured location.
<Action id="ora-file">
<fileAction>
<location>FOLDER_LOCATION</location>
<fileName>FILE_NAME</fileName>

</fileAction>
</Action>
Only the File action handler creates a metadata file that contains all the properties
of the rejected message. For example, for Oracle File Adapter, this metadata file
would include information, such as the inbound direction, and filename. The

Error Handling
location of metadata file is same as the payload file and the naming pattern is
<FILE_NAME>_metadata.
■ Payload Persistence
For resubmitting rejected messages, payload persistence is imperative. Payloads
are stored in the Database and a facility to view the payloads is available through
the Oracle Enterprise Manager Console. Error handlers, invoked during automatic
error handling will also get the payload during their invocation.
Error payload persistence in Database is available by default.
2.10.1.3 Checking for Rejected Messages
Rejected messages are stored in the rejected_message table. You can check for rejected
messages by using either of the following steps:
■ Checking from the Database
■ Checking from the Oracle Enterprise Manager Console
Checking from the Database
You must connect to the database as soainfra schema, and run the following SQL
command:
select * from rejected_message
Checking from the Oracle Enterprise Manager Console
You can view the rejected messages in the Recent Faults and Rejected Messages
section of the Dashboard tab or in the Faults and Rejected Messages tab.
For more information about using the Oracle Enterprise Manager Console for
checking for rejected messages, see Section 17.2, "Monitoring Recent Faults and
Rejected Messages for an Inbound Adapter" and Section 17.3, "Monitoring Faults and
Rejected Messages for an Inbound Adapter" in the Oracle Fusion Middleware
2.10.2 Handling Connection Errors
Oracle JCA Adapters and Oracle Adapter for Oracle Applications handle connection
errors for the following interactions:
■ Section 2.10.2.1, "Outbound Interaction"
■ Section 2.10.2.2, "Inbound Interaction"
2.10.2.1 Outbound Interaction
Oracle JCA Adapters and Oracle Adapter for Oracle Applications raise the
oracle.tip.adapter.api.exception.PCRetriableResourceException
exception for transient connection errors, which are recoverable connection errors. For
example, a database listener may not have started and this might be giving connection
errors.
Note: Rejected Messages cannot be submitted from the Oracle
Enterprise Manager Console.

Error Handling
There are two types of rejection handlers, the retryable exception and the non-retryable
exception:
■ Section 2.10.2.1.1, "Retryable Exceptions for Outbound Interaction"
■ Section 2.10.2.1.2, "Nonretryable Exceptions for Outbound Interaction"
2.10.2.1.1 Retryable Exceptions for Outbound Interaction
In the case of retryable exceptions, you must set the value of jca.retry.count to
the number of times that you want the retry to be carried out. For example, if you set
the value of jca.retry.count to 10, then the retry occurs 10 times. However, if you
have not set any value for jca.retry.count, then the retry is carried out by the
fault policy, if you have included it as part of the composite
The following code snippet is an example of setting values in the composite.xml file
for retryable exceptions for outbound interactions:
<reference name="Outbound">
<interface.wsdl interface="http://xmlns...#wsdl.interface(Outbound_PortType)"/>
<binding.jca config="Outbound_jms.jca">
<property name="jca.retry.count">5</property>
<property name="jca.retry.interval">1</property>
<property name="jca.retry.backoff">2</property>
<property name="jca.retry.maxInterval">6</property>
<property name="jca.retry.maxPeriod">30</property>
</binding.jca>
</reference>
Note that reply activity failure retries is one less than the jca.retry.count value
that you specify. For example, if the jca.retry.count is 5, then you would expect
the adapter to retry six times ((1 try plus 5 retries). However, it retries only four times,
and you see only 5 instances in the Oracle Enterprise Manager Console.
2.10.2.1.2 Nonretryable Exceptions for Outbound Interaction
You can handle nonretryable exceptions for outbound interactions, by defining the
maximum number of reconnection attempts that can be made through the
fault-policy.xml file. In this file specify the parameters for reconnection attempts,
as shown in the following example:
<faultName xmlns:bpelx="http://schemas.oracle.com/bpel/extension"
name="bpelx:bindingFault">
<condition>
<action ref="ora-retry"/>
</condition>
</faultName>
<Actions>
<Action id="ora-retry">
<retry>
<retryCount>10</retryCount>
<retryInterval>2</retryInterval>
<exponentialBackoff>2</exponentialBackoff>
</retry>
</Action>
</Actions>
A fault policy must be associated with a reference end point of the composite in
fault-bindings.xml file, as shown in the following example:
<faultPolicyBindings version="2.0.1"

Error Handling
xmlns="http://schemas.oracle.com/bpel/faultpolicy"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<reference faultPolicy="ConnectionFaults">
<name>writeMessageToQueue</name>
</reference>
</faultPolicyBindings>
In this example, the reconnection parameter settings specify the JCA Binding
Component run time to retry 10 times and the retry interval exponentially increases by
multiples of 2 starting with 2 seconds.
After the configured number of retries is reached, the Service Infrastructure Invocation
exception is thrown. All time measurements are specified in seconds.
The propagation of the type of the Service Infrastructure Invocation exception is
important in order to allow inbound adapters to respond to errors reported by
outbound adapters. Figure 2–3 shows the fault propagation in the case of when an
adapter calls Oracle BPEL Process Manager synchronously and then the Oracle BPEL
Process Manager calls a down-stream adapter. In Figure 2–3, a Service Infrastructure
Invocation exception propagates from the down-stream adapter, through Oracle BPEL
Process Manager, and to the caller adapter.
Figure 2–3 Fault Propagation
2.10.2.2 Inbound Interaction
All Oracle JCA Adapters (except for Oracle Socket Adapter) as well as legacy adapters
support a pull model for connecting to the back-end application for receiving events.
The packaged-application adapters (except for Oracle Adapter for Oracle
Applications), however, support a push model for receiving events from EISs
(Enterprise Information System). Connection-related issues are considered recoverable
Note: Fault policy does not work for the outbound adapters in XA
mode. For example, if you want the Fault policy to retry when the
outbound adapter fails, then it does not retry and any outbound
adapter that has been successful before this failure occurred does not
rollback.
Adapter
Adapter
Service
Infrastructure
BPEL
Service
Infrastructure
Service Infrastructure Invocation Exception
Service Infrastructure Invocation Exception

Error Handling
and most inbound adapters keep retrying until the adapters are able to establish
connection with the EIS. However, if the inbound adapter encounters an irrecoverable
error, for example, then if the inbound adapter is unable to delete from the EIS after a
message has been published, then it deactivates the endpoint to prevent poisoned
messages.
The packaged-application adapters (besides Oracle EBS Adapter) support a push
model for receiving events from the back-end application. Hence, the concept of a
connection does not apply. The inbound endpoints are usually an HTTP listener,
TCP/IP listener, FTP listener, MQSeries listener and so on and their onMessage
method is triggered whenever an event arrives.
There are two types of rejection handlers: the retryable exception and the non-retryable
exception.
■ Section 2.10.2.2.1, "Retryable Exceptions for Inbound Interaction"
■ Section 2.10.2.2.2, "Nonretryable Exceptions for Inbound Interaction"
2.10.2.2.1 Retryable Exceptions for Inbound Interaction
In the case of retryable exceptions, you must set the value of jca.retry.count to
the number of times that you want the retry to be carried out. For example, if you set
the value of jca.retry.count to 10, then the retry occurs 10 times. However, if you
have not set any value for jca.retry.count, then the retry is carried out
indefinitely.
The following code snippet is an example of setting values for retryable exceptions for
inbound interactions:
<service name="Inbound">
<interface.wsdl interface="http://xmlns...#wsdl.interface(Inbound_PortType)"/>
<binding.jca config="Inbound_db.jca">
</binding.jca>
</service>
Note that reply activity failure retries is one less than the jca.retry.count value
that you specify. For example, if the jca.retry.count is 5, then you would expect
the adapter to retry six times ((1 try plus 5 retries). However, it retries only four times,
and you see only 5 instances in the Oracle Enterprise Manager Console.
2.10.2.2.2 Nonretryable Exceptions for Inbound Interaction
The following properties are supported inbound:
■ jca.retry.count
Specifies the maximum number of retries before rejection.
Note: Infinite retries by inbound adapters for errors results in
creating multiple composite instances because for every retry a
separate composite instance is created. For example, consider an
inbound adapter that is enqueueing a message. This data is inserted
into two tables A and B. If for some reason the insert operation for
table B fails, then instead of rolling back the inbound adapter retries to
insert data to table B infinitely.

Error Handling
■ jca.retry.interval
Specifies the time interval between retries (measured in seconds.)
■ jca.retry.backoff
Specifies the retry interval growth factor (positive integer.)
■ jca.retry.maxInterval
Specifies the maximum value of retry interval, that is, a cap if backoff > 1
■ jca.retry.all
If this property is set to true, then even non-retriable exceptions are retried based
on the value specified in the jca.retry.count property.
The preceding list of properties are specified in the composite.xml file in Oracle
JDeveloper, as shown in the following example:
<interface.wsdl interface="http://xmlns...#wsdl.interface(Inbound_PortType)"/>
<binding.jca config="Inbound_db.jca">
</binding.jca>
</service>
2.10.3 Handling Message Errors
This section describes how to handle message errors by means of a sample scenario.
Consider an example, where there are two composites, Composite 1 and Composite 2
each having an Oracle BPEL process and there is a mix of local as well as XA
resources, as shown in Figure 2–4.
Figure 2–4 Sample Scenario: Handling Message Errors
In a positive scenario, that is, when the message is successfully delivered to all the
queues (Q1, Q2 and Q3) the transaction commits successfully.
If the message cannot be delivered to Q1 (or to any one of the queues) whereas the
message is delivered to queues Q2 and Q3, then the transaction must roll back all the
three messages because all are XA resources and there is an exception in one of its
Composite2 (Called Composite) : (Synchronous BPEL Process)
Composite1 (Caller Composite): (Synchronous BPEL Process)
Web Service Oracle BPEL Process Q1 (XA)
Web Service Oracle BPEL Process
Q3 (XA)
Service1 (Composite2)
Q2 (XA)

How Oracle JCA Adapters Ensure No Message Loss
units. The rollback exception is thrown only for the second composite where Q1 failed,
and the transactions commits Q2 and Q3 instead of rolling back the messages for all
the three queues.
In order that the transaction rolls back all the queues even if only one fails, and the
other two have messages successfully delivered to them, you must make the following
change in the composite.xml file of the called composite (Composite2):
Changes in composite.xml of Composite2
<component name="BPELProcess1">
<implementation.bpel src="BPELProcess1.bpel"/>
<property name="bpel.config.transaction">required</property>
</component>
Note that if you set bpel.config.transaction="required", then the Oracle
BPEL engine effectively processes the synchronous request without creating a new
transaction, rather, it uses the caller's transaction. Therefore, if at any point the
transaction gets rolled back, nothing done in that transaction will commit.
2.11 How Oracle JCA Adapters Ensure No Message Loss
This section describes how adapters ensure no message loss.
Transactional adapters allow the Enterprise Information System (EIS) to participate in
one-phase or two-phase commits (local transactions or global/distributed
transactions). These commits are controlled either by the adapter (inbound) or by the
Oracle User Messaging Service (UMS) (outbound). Non-transactional adapters
implement their own schemes to ensure delivery, without the use of transactional
semantics.
2.11.1 Local Transactions and Global (XA) Transactions
Local transaction allows the Oracle WebLogic Server to manage resources, which are
local to the resource adapter. The adapter defines the type of transaction support by
specifying the transaction-support element in the weblogic-ra.xml file. When an
application component requests for an EIS connection, the Oracle WebLogic Server
starts a local transaction based on the current transaction context. When the
application component closes that connection, the Oracle WebLogic Server commits
the local transaction. The Oracle WebLogic Server also cleans up the EIS connection
once the transaction has completed.
In the case of local transactions, fault policies are executed if the JTA transaction is
detected to still be active and if a policy has been bound to the partnerlink that has
thrown the exception. The JTA check allows the BPEL engine to catch manipulation of
the transaction by a third party before proceeding with work that may be dehydrated.
Adapters support global transactions in the JCA 1.5 XA contracts that leverage the
underlying application server transaction manager. This includes Oracle Adapter for
Oracle Applications, Database, Advanced Queuing, JMS and MQSeries.
Non-transactional adapters include Oracle File Adapter and Oracle FTP Adapter.
In the case of a global transaction, you cannot do anything to stop a rollback. This fault
type indicates that the JTA transaction must be retried (for example when a RAC node
goes down, the transaction must be retried by restarting the transaction). In this case,
fault policy gets executed. However, it is not advisable to use fault policy when XA
behavior is desired, because fault policy runs in its own transaction and does not
participate in the Global Transaction.

Streaming Large Payload
Specifically, the Fault Policy commits any existing JTA transaction before it starts
executing a particular Reference (for example, in Oracle BPEL Process Manager it is an
Invoke activity). The prexisting JTA transaction is not suspended and then resumed.
2.11.2 Inbound Transactions
For an asynchronous SCA service entry point, a transactional adapter initiates a global
JTA transaction before sending an inbound message to a composite. When control
returns to the adapter, it will commit the JTA transaction, thus executing the following
set of actions as an atomic unit of work:
1. Commit the removal of the message from the inbound adapter endpoint (for
example, table and queue).
2. Commit the execution of the composite instance.
If anything fails during this, then both the actions 1 and 2 will be rolled back.
For a synchronous process, the global transaction initiated by the adapter will span
message delivery and composite execution.
2.11.3 Outbound Transactions
For transactional adapters, outbound JCA interactions (the Invoke activities) are
scoped with the global BPEL JTA (EJB) transaction. This means that all composite
activities, including Oracle JCA adapter invocations will be part of a global
transaction, and as such either all activities are committed or rolled back, if an error
occurs.
For example, a BPEL process can insert data into several tables (on different databases)
through different invoke activities (invoking the Database adapter). When the BPEL
instance is about to finish, the JTA transaction is committed. Only at that point will the
database insert operations be committed. If any errors occur during the BPEL instance
execution, all activities (and thus database operations) will be rolled back to the last
dehydration point.
2.12 Streaming Large Payload
Oracle JCA Adapters support large payload processing for both inbound and
outbound processing. However, only the following adapters support the streaming
feature explicitly:
■ Oracle File Adapter
For more information, see Oracle File Adapter Scalable DOM.
■ Oracle AQ Adapter
For more information, see Stream Payload Support.
■ Oracle JMS Adapter
For more information, see Supports Streaming Large Payload.
■ Oracle Database Adapter
For more information, see Streaming Large Payload.
The other adapters do not have explicit support for both.

Composite Availability and Inbound Adapters
2.13 Composite Availability and Inbound Adapters
The Oracle WebLogic Server migration is used on WebLogic platform so that if a
managed server or machine fails, then it automatically restarts on the same or another
machine and inbound adapters to a composite on the failed server will then resume
functioning. Meanwhile, inbound adapters in other cluster members continue working
servicing messages.
For more information about composite availability and inbound adapters, see the
Oracle Fusion Middleware High Availability Guide.
2.14 Manually Deploying an Adapter RAR File
This section describes how to manually deploy any adapter RAR file that does not
have a jar file associated with it.
If you deploy any adapter RAR file that only contains META-INF/ra.xml and
META-INF/weblogic-ra.xml and does not contain the jar file adapter required for
creating JNDIs, then while deploying, you must change the deployment order to a
higher value (say 500) so that the Oracle WebLogic Server can deploy this RAR file
after the jar file of this adapter is loaded.
For example, to deploy the DBAdapter_NewJndis.rar file that contains only
META-INF/ra.xml and META-INF /weblogic-ra.xml and does not contain the jar file
adapter (DbAdapter.jar) required while instantiating the new JNDIs. In this case, after
deploying the DBAdapter_NewJndis.rar file, you must change the deployment
order to a higher value. This ensures that the Oracle WebLogic Server deploys the
DBAdapter_NewJndi.rar file correctly even if you restart the Oracle WebLogic Server.
The following are the steps to manually deploy an adapter RAR file that does not have
a jar file associated with it:
1. Navigate to the Oracle WebLogic Server Administration Console:
http://servername:portnumber/console.
displayed.
3. Select Deployments in the Domain Structure pane.
The Oracle WebLogic Server Administration Console Summary of Deployments
page is displayed.
4. Click Install.
The Install Application Assistant page is displayed.
5. Enter the path of the application directory or file in the Path field, and then click
Next.
6. Select the servers to which you want to deploy this application, and then click
Next.
The Optional Settings page is displayed.
7. Modify these settings or accept the defaults, and then click Next.
The Review your choices and click Finish page is displayed.
8. Click Finish to complete the deployment.

Defining Adapter Interface by Importing an Existing WSDL
9. After you deploy the RAR file, under Summary of Deployments, click the name
of the RAR file that you deployed.
The Settings page is displayed.
10. Change the value of Deployment Order field to a value that is higher than the
default value. For example, 500.
This ensures that the newly deployed RAR file is always loaded after the
supporting classes are loaded by the Oracle WebLogic Server.
2.15 Defining Adapter Interface by Importing an Existing WSDL
You can define an adapter interface in the Adapter Configuration Wizard Adapter
Interface page, as shown in Figure 2–5, by using either of the following methods:
■ Using a WSDL that is generated using the operation name and schema that you
specify in the Adapter Configuration Wizard in the pages that appear subsequent
to the Adapter Configuration Wizard Adapter Interface page.
■ Importing an existing WSDL.
Figure 2–5 Adapter Configuration Wizard Adapter Interface Page
This section describes how to define an adapter interface by importing an existing
WSDL. You can use this feature to create an adapter service or reference by using
existing WSDLs. The option to choose an existing WSDL is supported for the
following adapters only:
■ Oracle AQ Adapter
■ Oracle File Adapter
■ Oracle FTP Adapter
■ Oracle JMS Adapter
■ Oracle MQ Series Adapter

Defining Adapter Interface by Importing an Existing WSDL
■ Oracle Socket Adapter
If you select the option of defining the adapter interface by importing an existing
WSDL, then some functionalities on subsequent wizard pages are disabled. For
example, since the WSDL defines the operation name and the message schema, the
subsequent operation name and schema element fields are automatically filled in and
you cannot modify it, as shown in Figure 2–6. However, if you do not choose to use an
existing WSDL, then the adapter wizards will behave exactly as before.
Figure 2–6 Operation Page for Oracle AQ Adapter with Fields Automatically Populated
Note that the Adapter Configuration Wizard for Oracle MQ Series Adapter, Oracle
JMS Adapter, and the Oracle AQ Adapter appears a bit different from the other
adapters. It has the additional option to select a callback the port type and operation.
Subsequent options in the Adapter Configuration Wizard are enabled or disabled
depending on what port types and operations you select.
For example, while using the Adapter Configuration Wizard for defining Oracle MQ
Series Adapter, if a callback is selected, then only the Send Message to MQ and Get
Reply/Reports and the Get Message from MQ and Send Reply/Reports
Asynchronous options are enabled. If a callback is not selected, then only the Put
Message into MQ and Get Message from MQ options are enabled. If a WSDL
operation that has a synchronous reply is selected, then only the Get Message from
MQ and Send Reply/Reports Synchronous option is enabled.
Note that in all cases of using an existing WSDL, the options to use CICS or IMS
schemas are disabled.

Creating an Application Server Connection for Oracle JCA Adapters
2.16 Creating an Application Server Connection for Oracle JCA Adapters
You must establish connectivity between the design-time environment and the server
you want to deploy it to. To establish such connectivity, you must create an application
server connection.
The following are the steps to create an application server connection:
1. In the File menu, click New.
The New Gallery page is displayed, as shown in Figure 2–7.
Figure 2–7 The New Gallery Page
2. In the All Technologies tab, under General categories, select Connections.
A list of the different connections that you can make is displayed in the Items pane
on the right side of the New Gallery page.
3. Select Application Server Connection, and then click OK.
The Create Application Server Connection page is displayed, as shown in
Figure 2–8.
Note: The most common approach to importing an existing WSDL is
to first create an Oracle BPEL process or a Mediator, and then define
their WSDL files from schemas (or NXSD). After this is done, adapter
services are created, and the WSDL file generated for the BPEL
process or the Mediator component is imported as the existing WSDL
file.
However, you must keep in mind that this feature works only for
those messages, which use schema element. Simple and complex
types are not supported.

Figure 2–8 The Create Application Server Connection Name & Type Page
4. Enter a connection name in the Connection Name field. For example,
AppsServerConnection1.
5. Select WebLogic 10.3. for Connection Type and click Next.
The Authentication page is displayed, as shown in Figure 2–9.
Figure 2–9 The Create Application Server Connection Authentication Page
6. Enter the user name and password, and then click Next.
The Create Application Server Connection Configuration page is displayed, as
shown in Figure 2–10.

Figure 2–10 The Create Application Server Connection Configuration Page
7. Enter the host name, the port details, and the domain server name in the
Configuration page.
8. Click Next.
The Create Application Server Connection Test page is displayed, as shown in
Figure 2–11.
Figure 2–11 The Create Application Server Connection Test Page
9. Click Test Connection. A success message is displayed in the Status pane.
10. Click Finish.

Deploying Oracle JCA Adapter Applications from Oracle JDeveloper
You have created a server connection.
2.17 Deploying Oracle JCA Adapter Applications from Oracle JDeveloper
You deploy an SOA composite application from Oracle JDeveloper.
Oracle JDeveloper requires the use of profiles for SOA projects and applications to be
deployed. This section describes how to create and deploy profiles with Oracle
JDeveloper.
This section describes how you deploy an application profile for the SOA project and
the application.
To deploy the application, you must perform the following steps:
1. Right-click the project that you want to deploy, and select Deploy > project_name,
to Application_Server_Connection_Name, as shown in Figure 2–12.
The SOA Deployment Configuration dialog is displayed.
Figure 2–12 Application Profile Deployment
2. Use the default settings, as shown in Figure 2–13.

Testing Applications
Figure 2–13 The SOA Deployment Configuration Dialog
3. Click OK.
The Authorization request dialog is displayed.
4. Enter the user name and password, and then click OK.
The project is compiled and deployed to the Managed Server. You can view the
deployment log clicking the Deployment tab in the design area.
If you want to redeploy the same version of a SOA composite application, you
cannot change the composite name. You can deploy with the same revision
number if you selected the Overwrite any existing composites with the same
revision ID check box on the SOA Deployment Configuration dialog. However, if
you do not do so, then the following error message is deployed in the deployment
log:
pr 29, 2009 1:55:57 AM
oracle.integration.platform.blocks.deploy.servlet.CompositeDeployerMessages
severeSendError
SEVERE: Sending back error message:
Error during composite deployment:
oracle.fabric.common.FabricDeploymentException:
Composite with same revision ID already exists:
default/<application name>!<revision id>.
Please set the overwrite flag or use different revision ID.
Abort deployment...
2.18 Testing Applications
You can run and test instances of deployed SOA composite applications from Oracle
Enterprise Manager Grid Control Console. This enables you to:

Batching and Debatching Support
■ Manage a composite application.
■ Initiate an instance of a composite.
■ Track an instance of a composite.
■ View detailed component instance audit trails.
For more information about testing applications, see Oracle Fusion Middleware
2.19 Batching and Debatching Support
The batching and debatching functionality is supported only by Oracle JCA Adapter
for Files and Oracle JCA Adapter for FTP, and Oracle JCA Adapter for Databases.
Oracle JCA Adapter for File and Oracle JCA Adapter for FTP consist of a Reader to
debatch a single huge file into several batches. You need to specify the batch size
during the design-time configuration. In addition, the adapter includes a Writer to
batch a set of messages into a single file.
Oracle JCA Adapter for Databases consists of a Publish component to poll a set of
tables to detect events. This component can raise events to the BPEL process one
record at a time or multiple records at a time.
2.20 Migrating Repositories
All the JCA files generated by the Adapter Configuration Wizard have a reference to
the JNDI name. The reference is defined in the weblogic-ra.xml file, which is the
adapter's deployment descriptor. The JNDI name is the key when you want to migrate
from a development environment to a test environment to a production environment.
You should update the weblogic-ra.xml file to have the same JNDI name in all
three environments: development, testing, and production. You should specify values
for deployment time properties, such as retry interval and retry count, and then
redeploy to testing environment or production environment. The weblogic-ra.xml
will identify the end point as a development EIS or testing EIS or production EIS. For
example, consider that when running through the Database Adapter Service Wizard,
you specify eis/DB/custStore as the JNDI name for the createCustomer service.
After modeling the composite by using this adapter service, you should deploy it to
the development, test, or production environments without making any changes. But
before you do this, ensure that you have a corresponding JNDI entry for
eis/DB/custStore in each of your various environments pointing to the right EIS
instance.
2.21 Recommended Setting for Data Sources Used by Oracle JCA
Adapters
This section describes the recommended setting for non-XA and XA data sources used
by Oracle JCA Adapters.
The following are the recommended settings for multi data sources:
■ test-frequency-seconds should be 5
■ algorithm-type should be Load-Balancing
■ data-source-list should point to a list of comma-separated child data
sources. For example, ("JDBC Data Source-0,JDBC Data Source-1")

Recommended Setting for Data Sources Used by Oracle JCA Adapters
Note that if your endpoint property resides in a RAC database, then it is
recommended that you use multi data sources.
Table 2–1 lists the recommended setting for XA and non-XA data sources used by
Oracle JCA Adapters.
In addition to applying the settings mentioned in Table 2–1, you must perform the
steps documented in the Programming WebLogic JTA guide available in the following
link:
Table 2–1 Recommended Setting For XA and Non-XA Data Sources
XA Data Sources Non-XA Data Sources
The driver used is
oracle.jdbc.xa.client.OracleXADataSource.
The driver used is oracle.jdbc.OracleDriver.
The JDBC URL should be in the following format:
jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=
TCP)(HOST=host-vip)(PORT=152
1))(CONNECT_DATA=(SERVICE_NAME=service_
name)(INSTANCE_NAME=inst1)))
Same as that of XA data source.
You must set the following property
<property>
<name>oracle.net.CONNECT_TIMEOUT</name>
<value>10000</value>
</property>
The value of initial-capacity must be 0 Same as that of XA data source.
The value of
connection-creation-retry-frequency-seconds
must be 10
The value of test-frequency-seconds must be 300. Same as that of XA data source.
The value of test-connections-on-reserve must be
TRUE.
The value of test-table-name must be SQL SELECT
1 FROM DUAL
The value of
seconds-to-trust-an-idle-pool-connection
must be 0
The value of global-transactions-protocol must
be TwoPhaseCommit
The value for global-transactions-protocol
must be None.
The value of keep-xa-conn-till-tx-complete must
be TRUE.
NA
The value of xa-retry-duration-seconds must be
300.
NA
The value of xa-retry-interval-seconds must be
60.
NA
Note: The settings mentioned in Table 2–1 are applicable to both
types of database, single instance and RAC database. In case of a RAC
database, these settings have to be used for constituent data sources
for multi data sources created for endpoints.

Recommended Setting for Data Sources Used by Oracle JCA Adapters
http://download.oracle.com/docs/cd/E12840_
01/wls/docs103/jta/thirdpartytx.html#wp1084836
These steps are required for data sources using XA driver. After performing the steps
mentioned in the preceding link, you must run the following SQL statements to enable
WLS JTA recovery to work:
grant select on sys.dba_pending_transactions to public
GRANT FORCE ANY TRANSACTION TO public
grant execute on sys.dbms_xa to public

3
Adapter Integration with Oracle Application Server Components 3-1
3Adapter Integration with Oracle Application
Server Components
Oracle Application Server adapters can be integrated with various components of
Oracle WebLogic Server and Oracle Fusion Middleware. This chapter discusses how to
integrate adapters with Oracle WebLogic Server and Oracle Fusion Middleware.
This chapter includes the following topics:
■ Section 3.1, "Adapter Integration with Oracle WebLogic Server"
■ Section 3.2, "Adapter Integration with Oracle Fusion Middleware"
3.1 Adapter Integration with Oracle WebLogic Server
Oracle JCA Adapters are based on the J2CA 1.5 specification and are deployed to the
Oracle WebLogic Server. The resource adapter is used within the address space of the
Oracle Fusion Middleware. This section provides an overview of the Oracle WebLogic
Server and design-time and run-time integration with an adapter.
■ Section 3.1.1, "Oracle WebLogic Server Overview"
■ Section 3.1.2, "Oracle WebLogic Server Integration with Adapters"
3.1.1 Oracle WebLogic Server Overview
Oracle WebLogic Server is the core J2EE run-time component of Oracle Application
Server. Oracle WebLogic Server is a scalable, enterprise-ready Java Platform,
Enterprise Edition (Java EE) application server. The WebLogic Server infrastructure
supports the deployment of many types of distributed applications. It is an ideal
foundation for building applications based on Service Oriented Architecture (SOA).
All client applications run within the Oracle WebLogic Server environment. To
integrate an Oracle WebLogic Server client application with a resource adapter, use the
common client interface (CCI). The Oracle WebLogic Server adapter clients include a
servlet, EJB, or Java application client that implements the CCI Application
Programming Interface (API). The CCI defines a standard client API for application
components to access the back-end application.
On the other hand, the contract between the Oracle WebLogic Server container and the
resource adapter is defined by the service provider interface (SPI). Contracts define a
standard between Oracle WebLogic Server and adapters. The system handles these
contracts automatically and hides them from the application developer. Figure 3–1
illustrates the CCI and SPI contracts:

Adapter Integration with Oracle WebLogic Server
Figure 3–1 Contracts Between Oracle WebLogic Server and Resource Adapter
The Oracle WebLogic Server architecture includes the following set of system-level
contracts:
■ Connection management: Enables application components to connect to a
back-end application and leverage any connection pooling support of the Oracle
WebLogic Server container. This leads to a scalable and efficient environment that
can support a large number of components requiring access to a back-end
application.
■ Transaction management: Enables an application server to use a transaction
manager to manage transactions across multiple resource managers. Most of the
adapters support only local transactions (single-phase commit) and not XA
transactions (two phase commit).
The following adapters support XA transactions:
– Oracle MQ Series Adapter
– Oracle JMS Adapter
– Oracle AQ Adapter
– Oracle Database Adapter
– Oracle EBS Adapter
The following adapters do not support XA transactions:
– Oracle File Adapter
– Oracle FTP Adapter
– Oracle Socket Adapter
Note that all Oracle JCA Adapters come preconfigured with the correct value for
transaction, and you must not change this configuration in the Oracle WebLogic
■ Security management: The WebLogic Server security architecture provides a
comprehensive, flexible security infrastructure designed to address the security
challenges of making applications available on the Web. WebLogic security can be
used standalone to secure WebLogic Server applications or as part of an
enterprise-wide security management system that represents a best-in-breed
security management solution.
Figure 3–2 shows the architecture of Oracle JCA Adapters.
Enterprise
Information
Systems
Application
Contract
(Client API:
CCI, specific)
System Contracts
(Quality of Service)
J2EE Application
Component Resource
Adapter
Oracle WebLogic
Server
Network

Adapter Integration with Oracle WebLogic Server
Figure 3–2 Oracle Adapter Architecture
3.1.2 Oracle WebLogic Server Integration with Adapters
Oracle JCA Adapters are based on the J2CA 1.5 specification and are deployed as the
J2CA resource adapter within the Oracle WebLogic Server container in this release.
The J2CA resource adapter is packaged into a Resource Adapter Archive (RAR) file
using the Java Archive (JAR) format. A RAR file contains a correctly formatted
deployment descriptor (/META-INF/ra.xml). In addition, it contains declarative
information about the contract between the Oracle WebLogic Server and resource
adapter.
Oracle WebLogic Server generates the corresponding weblogic-ra.xml file during
the deployment of the J2CA adapter. The weblogic-ra.xml file is the deployment
descriptor for a resource adapter. It contains deployment configurations for deploying
resource adapters to Oracle WebLogic Server, which includes the back-end application
connection information as specified in the deployment descriptor of the resource
adapter, Java Naming and Directory Interface (JNDI) name to be used, connection
pooling parameters, and resource principal mapping mechanism and configurations.
Design Time
Use the adapter design-time tool to generate XML Schema Definition (XSD) files for
the adapter request-response service. The Oracle WebLogic Server clients use these
XSD files during run time for calling the J2CA outbound interaction.
Packaged-application adapters use OracleAS Adapter Application Explorer
(Application Explorer), Legacy adapters use OracleAS Studio, and technology
adapters use Oracle JDeveloper.
JCA
Binding
Component
SCA
Run-Time
JDeveloper
SOA
Studio
JDeveloper Project File (.JPR)
.properties
Application Server
JCA
JNDI
EIS/JCA Adapter
Fabric
or_mappings.xml
· WSDL
· .JCA
· XSD
· Schemas
Deployment
weblogic-ra.xml
Oracle JCA
Adapters
composite.xml
Adapter
Configuration
Wizard
SOA
Artifacts Design Time
sessions.xml
EIS

Adapter Integration with Oracle Fusion Middleware
Run Time
Oracle JCA Adapters are based on the J2CA 1.5 specification but are deployed as the
J2CA 1.5 resource adapter within the Oracle WebLogic Server container in this release.
The J2CA 1.5 specification addresses the life-cycle management, message-inflow (for
Adapter Event publish), and work management contracts.
3.2 Adapter Integration with Oracle Fusion Middleware
Adapters integrate with the JCA Binding Component of the Oracle Fusion Middleware
platform, thereby seamlessly integrating with service engines, such as Oracle BPEL
Process Manager and Oracle Mediator.
This section includes the follows topics:
■ Section 3.2.1, "Oracle BPEL Process Manager Overview"
■ Section 3.2.2, "Oracle Mediator Overview"
■ Section 3.2.3, "Oracle Fusion Middleware Integration with Adapters"
■ Section 3.2.4, "Oracle SOA Composite Integration with Adapters"
3.2.1 Oracle BPEL Process Manager Overview
Oracle BPEL Process Manager is a comprehensive solution for creating, deploying,
and managing Oracle BPEL Process Manager business processes. Oracle BPEL Process
Manager is based on the Service Oriented Architecture (SOA) to provide flexibility,
interoperability, reusability, extensibility, and rapid implementation. Oracle BPEL
Process Manager reduces the overall cost of management, modification, extension, and
redeployment of existing business processes. Each business activity is a self-contained,
self-describing, modular application with an interface that is defined by a WSDL file
and the business process that is modeled as a Web service.
The following section discusses how technology adapters gather and publish statistics
for every message they process, either inbound or outbound in Oracle BPEL Process
Manager 11g.
The Adapter Configuration Wizard generates a WSDL and a JCA properties file, which
contain the binding information for that service.
3.2.2 Oracle Mediator Overview
Oracle Mediator provides a lightweight framework to mediate between various
producers and consumers of services and events. In most business environments,
customer data resides in disparate sources including business partners, legacy
applications, enterprise applications, databases, and custom applications. The
challenge of integrating this data can be met by using Oracle Mediator to deliver
appropriate real-time data access to all applications that update or have a common
interest in the same data. For example, a Mediator can accept data contained in a text
file from an application or service, transform it to a format appropriate for updating a
database that serves as a customer repository, and then route and deliver the data to
that database.
3.2.3 Oracle Fusion Middleware Integration with Adapters
The JCA Binding Component is used for the bidirectional integration of the J2CA 1.5
resource adapters with Oracle BPEL Process Manager and Oracle Mediator. Oracle

JCA Adapters generate a WSDL file and a JCA binding, and expose the underlying
interactions as Web Services.
The interface (input/output XML elements) to an adapter service is described through
a WSDL file. However, in the 11g release, the binding element has been removed,
making the WSDL file abstract. Instead the binding information, that the JCA Binding
Component (referred to as adapter framework in the previous releases) and adapters
need to invoke for a particular call on a particular EIS, is stored in a separate
binding.jca file.
Design Time
While integrating adapters with Oracle BPEL Process Manager and Oracle Mediator,
the underlying adapter services are exposed as WSDL files with the J2CA extension.
The following table lists the design-time tools used for generating WSDL and JCA files
for various types of adapters.
WSDL files are created for both request-response and event-notification services of an
adapter. The J2CA extension contains J2CA elements that are required by JCA Binding
Component during run time to convert Web service messages to J2CA Interactions and
back. The J2CA WSDL extension elements contain the metadata for JCA Binding
Component to call any request-response service and activate any inbound J2CA 1.5
endpoint to receive inbound events. The J2CA extension elements for the
request-response service contains the JNDI location and InteractionSpec details
for calling an outbound interaction. The J2CA extension elements for the
event-notification service contains the resource adapter class name and
ActivationSpec parameters for publishing an adapter event through the J2CA
inbound interaction.
Figure 3–3 illustrates the design-time tool, Oracle JDeveloper, used by Oracle JCA
Adapters.
Figure 3–3 Design Time Configuration of Technology Adapters
Adapter Tool
Oracle Technology Adapters and Oracle
Adapter for Oracle Applications
Oracle JDeveloper
Packaged application Application Explorer
Legacy Oracle Studio
JDeveloper
SOA
Studio
.properties
or_mappings.xml
· WSDL
· _db.JCA
· XSD
Deployment
composite.xml
Adapter
Configuration
Wizard
SOA

Figure 3–4 illustrates the design-time tool for configuring packaged-application
adapters. In this figure, the design-time tools are used to expose adapter metadata as
WSDL files. The WSDL files are consumed by BPEL Process Manager during run time.
Figure 3–4 Configuring Packaged-Application Adapters
Run Time
Oracle Application Server adapters are based on the J2CA 1.5 specification, and BPEL
is deployed on the 11g run-time on the Oracle WebLogic Server. A JCA Binding
Component acts as the glue layer that integrates the standard J2CA 1.5 resource
adapter with the Oracle BPEL Process Manager and Oracle Mediator during run time.
The JCA Binding Component acts as a pseudo J2CA 1.5 container.
The Web service invocation launched by the BPEL Invoke activity is converted to a
J2CA CCI outbound interaction, and the J2CA response is converted back to a Web
service response. This end-to-end invocation is synchronous.
End-to-End Testing
You could also wrap up your custom adapter as a Web Service, and expose this to
BPEL Process Manager. This is a loose coupling strategy and does not need an Adapter
SDK. Both these approaches (JCA/Web service) are suitable for outbound invoke
operations referred to as reference. Only the JCA 1.5 integration allows the BPEL PM
to receive inbound events (from EIS to J2EE/BPEL PM). The Oracle BPEL Process
Manager acts as a pseudo JCA 1.5 container and implements the JCA 1.5-specific
System Contracts.
You can use any custom design tool for the configuration of the adapter, but a WSDL
file must be generated at the end of the design-time phase for consumption by the
BPEL PM design-time (Oracle Jdeveloper). The WSDL file for the JCA interactions
have a JCA extension. The Adapter is a JCA 1.5 resource adapter deployed in the same
Oracle WebLogic Server container as that of the BPEL PM product. Note that the JCA
1.5 Resource Adapter and the BPEL PM instance must be deployed in the same Oracle
WebLogic Server container.
The JCA Binding Component is the glue layer that integrates the standard JCA 1.5
Resource Adapter seamlessly with the BPEL PM product at run time. The JCA Binding
Component has a JCA Provider for wrapping the JCA interactions as Web Services and
performs the translation between Web Service messages to JCA interaction messages
based on the WSDL files generated at design time.
Adapter
Clients
J2CA
Web
Services
Channel Port
Repository
Client
Adapter SDK
EIS Libraries OracleAS
Adapter
Repository
OracleAS Adapter
Application Explorer
(design-time tool)
EIS

Oracle BPEL Process Manager Integration with Outbound Interaction
The outbound interaction with Oracle Mediator is the same as that of Oracle BPEL
Process Manager.
The following is a snippet of the composite.xml file for an outbound invoke
(referred to as reference in the 11g release):
<reference name="insert" ui:wsdlLocation="insert.wsdl">
<interface.wsdl
interface="http://xmlns.oracle.com/pcbpel/adapter/db/DBRetriesApplication/
XARollback/insert%2F#wsdl.interface(insert_ptt)"
(http://xmlns.oracle.com/pcbpel/adapter/db/DBRetriesApplication/XARollback/insert%
2F#wsdl.interface%28insert_ptt%29)/>
<binding.jca config="insert_db.jca"/>
</reference>
■ During design time, adapter services are exposed as WSDL files and consumed
during configuration of the PartnerLink activity of the BPEL process.
■ The .jca file contains the JNDI address of the resource adapter, InteractionSpec
class name, InteractionSpec parameters.
■ During run time, the Invoke activity of the BPEL Process Manager is used to call
the PartnerLink activity, which is a J2CA Resource Adapter outbound
interaction.
■ The components are wired into a composite application.
■ The JCA Binding Component translates the event to a Web service response for
consumption by the BPEL PM instance.
■ The outbound JCA adapter communicates with the EIS through CCI interaction.
Oracle BPEL Process Manager Integration with Inbound Interaction
BPEL Process Manager receives events from the J2CA 1.5 resource adapter through the
JCA Binding Component, which is the pseudo J2CA 1.5 container and implements the
message inflow contracts for receiving events from the adapter. The J2CA inbound
interaction is captured in a WSDL file during design time. The J2CA inbound WSDL
binding section contains the J2CA 1.5 ActivationSpec parameter. The
ActivationSpec parameter captures the inbound connectivity and inbound
interaction details (according to J2CA 1.5 specification). The J2CA Inbound WSDL
Service section contains the J2CA 1.5 ResourceAdapter class name. In addition, the
Service section can optionally contain a JNDI location. The following list summarizes
the process of BPEL Process Manager integration with the inbound interaction:
■ The ResourceAdapter class name and the ActivationSpec parameter are
captured in the WSDL extension section of the J2CA inbound interaction WSDL
during design time and made available to BPEL Process Manager and the JCA
Binding Component during run time.
■ An instance of the J2CA 1.5 ResourceAdapter class is created, and the Start
method of the J2CA ResourceAdapter class is called.
■ Each inbound interaction operation referenced by the BPEL Process Manager
processes results in invoking the EndPointActivation method of the J2CA 1.5
ResourceAdapter instance. The JCA Binding Component creates the
ActivationSpec class (Java bean) based on the ActivationSpec details
present in the WSDL extension section of the J2CA inbound interaction and
activates the endpoint of the J2CA 1.5 resource adapter.

■ The JCA Binding Component MessageEndpoint implementation implements
the javax.resource.cci.MessageListener interface. The J2CA 1.5 resource
adapter calls the onMessage() method in this MessageEndpoint when it
receives a back-end application event. The J2CA 1.5 resource adapter creates an
instance of the MessageEndpoint implementation through
MessageEndpointFactory provided to the resource adapter during
endpointActivation.
■ The JCA Binding Component receives the event through the MessageListener
class and forwards it to the Receive activity of the BPEL Process Manager instance.
■ When the BPEL process is stopped, all associated inbound end points are
deactivated through the endPointDeactivation method implemented by the
resource adapter.
In the case of J2CA adapters, particularly the JDBC based ones, such as Oracle
Database Adapter and Oracle AQ Adapter two kinds of connection management at
play, one for inbound (endpoint) activations (BPEL Receive) and one for outbound
interactions (BPEL Invoke).
In the case of inbound activations, the J2CA adapter is fully in charge of connection
creation and recovery. The JCA Binding Component can only be requested to lookup
and provide a J2CA ConnectionFactory handle to the adapter through its
ActivationSpec. This is possible only if it implements a certain interface, which it
can use to create connections, thereby going through the Application Server
connection manager. Whenever a managed (JDBC) connection goes bad, the adapter
must close the J2CA connection handle (and subsequently the managed connection if
destroy() is called by the Application Server), enter a temporary recovery loop, and
then try to reestablish a new connection.
In the case of outbound interactions (J2CA), each port caches tuples of the following:
■ ConnectionFactory
■ ConnectionSpec
■ Connection
■ Interaction
■ InteractionSpec
As the BPEL engine typically invokes the port concurrently with any number of
threads, the size of the cache will typically reflect the highest concurrency level at any
given time. The cache can be tuned to automatically expire unused tuples after a
configured idle period (interactions and connection handles are then closed).The cache
greatly improves performance in high load environments, for example, Retek (8
million transactions every hour).
If just one JCA adapter interaction using the cache throws a ResourceException,
then all members of the cache are closed and released immediately (purged), so new
interactions will have to re-create (fresh) members to the cache. The BPEL engine has a
feature known as PartnerLink retry which can be configured for each invoke. Thus, any
JCA adapter invoke or interaction which throws a ResourceException exception
marked as Retryable will make the engine retry the Invoke (Database update) which
will then repopulate the port cache (if the Database has become available again:
typically immediately the case with RAC).
For non-transactional adapters
(adapterMetadata.supportsLocalTransactionDemarcation() == false),
such as File adapter, the J2CA connection cache contains only one member. Thus all
threads coming through will multiplex over the same CCI Connection handle.

The JCA connection cache can be enabled or configured explicitly by using the
following bpel.xml partnerlink properties:
<property name="useJCAConnectionPool">true</property>
Generally, this property is derived from the declared transactional support of the
adapter. For example, the File adapter does not use this connection pool because it is
multi thread safe, but that can be overridden through the following property:
<property name="maxSizeJCAConnectionPool">500</property>
If the property mentioned in the preceding example is not specified, then the size of
the connection pool is assumed to be unbounded. This applies for each partnerlink.
<property name="lruConnectionMaxIdleAge">50000</property>
The maximum age of idle connections in the pool is important because some type of
connections hold on to expensive external resources, for example DB shadow
processes which is measured in ms, as shown in the following example:
property name="lruConnectionCheckInterval">10000</property>
Finally, the property mentioned in the preceding example determines how frequently
the connection pool should be scanned for idle connections, also measured in ms.
The following is a code snippet of the composite.xml file for an inbound polling
receive operation (referred to as service in the 11g release):
<service name="poll" ui:wsdlLocation="poll.wsdl">
<interface.wsdl
interface="http://xmlns.oracle.com/pcbpel/adapter/db/DBRetriesApplication/
XARollback/poll%2F#wsdl.interface(poll_ptt)"
(http://xmlns.oracle.com/pcbpel/adapter/db/DBRetriesApplication/XARollback/poll%2F
#wsdl.interface%28poll_ptt%29)/>
<binding.jca config="poll_db.jca"/>
</service>
Note how the composite.xml file links together the WSDL interface (the
interface.wsdl file), the name of the component which is handling the request (the
binding.jca file), and the binding information required to invoke a particular call
(the config file). Hence the JCA Binding Component is registered in SCA as the
implementation of the binding.jca file (others include binding.ejb and
binding.java), while in the 10.1.3 release it was registered as a WSIF provider.
In the current release the <binding.jca> element is in the composite.xml file, which
explicitly indicates that the JCA Binding Component is handling the invoke activity.
Whereas in the 10.1.3 release you had to look at the concrete binding in the WSDL to
see whether it was an adapter invoke or not, as shown in the following example:
<binding name="invokeService_binding" type="tns:invokeService_ptt">
<jca:binding />
<operation name="merge">
<jca:operation>
Use Case: Integration with Oracle BPEL Process Manager
From the Partner Link dialog in Oracle BPEL Process Manager, shown in Figure 3–5,
you can access the adapters that are provided with Oracle BPEL Process Manager.

Figure 3–5 Partner Link dialog box
Click the Define Service icon, shown in Figure 3–6, to access the Configure Service or
Adapter dialog.
Figure 3–6 Defining an Adapter
This dialog enables you to configure the types of adapters shown in Figure 3–7 for use
with Oracle BPEL processes.
Figure 3–7 Adapter Types
When you select an adapter type (Oracle AQ Adapter in this example), and then click
OK, the Adapter Configuration Wizard - Welcome page appears, as shown in
Figure 3–8.

Figure 3–8 The Adapter Configuration Wizard- Welcome Page
Click Next, and the Service Name page appears, as shown in Figure 3–9. You are
prompted to enter a name for the service.
For this example, AQ Adapter is selected, as shown in Figure 3–7. When the wizard
completes, a WSDL file by this service name appears in the Applications Navigator
for the BPEL process (for this example, named DequeueDemo.wsdl). This file
includes the adapter configuration settings you specify with this wizard. Other
configuration files (such as header properties and files specific to the adapter) are also
created and displayed in the Applications Navigator.

Figure 3–9 The Adapter Configuration Wizard- Service Name Page
The Adapter Configuration Wizard windows that appear after the Service Name
window are based on the adapter type you selected. These configuration windows and
the information you must provide are described in later chapters of this guide.
3.2.4 Oracle SOA Composite Integration with Adapters
Oracle JCA Adapters can be integrated with Oracle SOA Suite.
This section includes the following:
■ Section 3.2.4.1, "Oracle SOA Composite Overview"
■ Section 3.2.4.2, "Adapters Integration With Oracle SOA Composite"
3.2.4.1 Oracle SOA Composite Overview
An SOA composite application is an assembly of services, service components,
references, and wires designed and deployed together to meet a business need.
SOA provides an enterprise architecture that supports building connected enterprise
applications. SOA facilitates the development of enterprise applications as modular
business Web services that can be easily integrated and reused, creating a truly
flexible, adaptable IT infrastructure.
3.2.4.2 Adapters Integration With Oracle SOA Composite
A composite is an assembly of services, service components, wires, and references
designed and deployed together in a single application. The composite processes the
information described in the messages.
For example, a composite includes an inbound service binding component (an
inbound adapter), a BPEL process service component, and an outbound reference
binding component (an outbound adapter). The details of this composite are stored in
the composite.xml file.
An Oracle SOA composite typically comprises the following parts:

■ Binding Components
The binding component establishes the connectivity between a SOA composite
and the external world. There are two types of binding components:
– Service Binding Components
Provide the outside world with an entry point to the SOA composite
application. The WSDL file of the service informs external applications of its
capabilities. These capabilities are used for contacting the SOA composite
application components. The binding connectivity of the service describes the
protocols that can communicate with the service, for example, Oracle JCA
adapter.
– Reference Binding Components
Enable messages to be sent from the SOA composite application to external
services in the outside world.
The Oracle SOA Suite provides Web Services, such as Oracle JCA adapters for
integrating services and references with technologies (for example, databases, file
systems, FTP servers, messaging: JMS, IBM WebSphere MQ, and so on) and
applications (Oracle E-Business Suite, PeopleSoft, and so on). This includes Oracle
AQ Adapter, Oracle Database Adapter, Oracle File Adapter, Oracle FTP Adapter,
Oracle JMS Adapter, Oracle MQ Series Adapter, and Oracle Socket Adapter.
■ Service Infrastructure
Provides internal message transport. For example, receives the message from an
inbound adapter and posts the message for processing to the BPEL process service
engine.
■ Service Engines (containers hosting service components)
Host the business logic or processing rules of the service components. Each service
component has its own service engine. For example, an Oracle BPEL process
engine or an Oracle Mediator Component.
For more information about adapter integration with Oracle BPEL Process
Manager and Oracle Mediator, see Section 3.2, "Adapter Integration with Oracle
Fusion Middleware."
■ UDDI and MDS
The MDS (Metadata Service) repository stores descriptions of available services.
The UDDI advertises these services and enables discovery as well as dynamic
binding at run time.
■ SOA Archive: Composite
The deployment unit that describes the composite application.
A composite is an assembly of services (for example, inbound adapters), service
components, wires, and references (for example, outbound adapters) designed and
deployed together in a single application. The composite processes the information
described in the messages. A composite.xml file is automatically created when you
create a SOA project. This file describes the entire composite assembly of services,
service components, references, and wires. The composite.xml file describes the entire
SOA composite.
The following is a sample composite.xml file:
Composite.xml (JCA Bindings)
<?xml version="1.0" encoding="UTF-8" ?>

Monitoring Oracle JCA Adapters

<composite name="MediatorFlatStructure"
revision="1.0"
label="2009-02-23_15-02-00_374"
mode="active"
state="on"
xmlns="http://xmlns.oracle.com/sca/1.0"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:orawsp="http://schemas.oracle.com/ws/2006/01/policy"
xmlns:ui="http://xmlns.oracle.com/soa/designer/">
<import
namespace="http://xmlns.oracle.com/pcbpel/adapter/file/SOA-FlatStructure/MediatorF
latStructure/MedFlatIn%2F" location="MedFlatIn.wsdl" importType="wsdl"/>
<import
namespace="http://xmlns.oracle.com/pcbpel/adapter/file/SOA-FlatStructure/MediatorF
latStructure/MedFlatOut%2F" location="MedFlatOut.wsdl" importType="wsdl"/>
<service name="MedFlatIn" ui:wsdlLocation="MedFlatIn.wsdl">
<interface.wsdl
interface="http://xmlns.oracle.com/pcbpel/adapter/file/SOA-FlatStructure/MediatorF
latStructure/MedFlatIn%2F#wsdl.interface(Read_ptt)"/>
<binding.jca config="MedFlatIn_file.jca"/>
</service>
<component name="MediatorFlat">
<implementation.mediator src="MediatorFlat.mplan"/>
</component>
<reference name="MedFlatOut" ui:wsdlLocation="MedFlatOut.wsdl">
<interface.wsdl
interface="http://xmlns.oracle.com/pcbpel/adapter/file/SOA-FlatStructure/MediatorF
latStructure/MedFlatOut%2F#wsdl.interface(Write_ptt)"/>
<binding.jca config="MedFlatOut_file.jca"/>
</reference>
<wire>
<source.uri>MedFlatIn</source.uri>
<target.uri>MediatorFlat/MediatorFlat</target.uri>
</wire>
<wire>
<source.uri>MediatorFlat/MedFlatOut</source.uri>
<target.uri>MedFlatOut</target.uri>
</wire>
</composite>
For more information about Oracle SOA Composite and its integration with various
service, see Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
3.3 Monitoring Oracle JCA Adapters
In Oracle BPEL Process Manager and Oracle Mediator, Oracle JCA adapters such as
File, JMS, and Database, gather and publish statistics for every message they process,
either inbound or outbound. The statistics are broken down into categories and
individual tasks. The following is an example of how statistics are broken down in an
outbound (reference) process:
■ Adapter Preprocessing
– Preparing InteractionSpec
■ Adapter Processing
– Setting up Callable Statement

– Invoking Database
– Parsing Result
■ Adapter Postprocessing
The adapter statistics can be viewed in the Oracle Enterprise Manager Console. The
following are the steps to view the adapter statistics:
2. In the SOA folder in the Target Navigation tree (in the extreme left pane), click
soa_infra.
The soa-infra page is displayed.
3. From the SOA Infrastructure menu in the soa-infra page, click Services and
References, as shown in Figure 3–10.
Figure 3–10 Viewing the Adapter Statistics in the Oracle Enterprise Manager Console
The SOA Infrastructure Home > Interfaces page is displayed, as shown in
Figure 3–11.
This page shows a list of all currently active inbound (services) and outbound
adapter interactions (references), and the average execution time for the various
steps each adapter performs.

Figure 3–11 The SOA Infrastructure Home > Interfaces Page

4
Oracle JCA Adapter for Files/FTP 4-1
4 Oracle JCA Adapter for Files/FTP
This chapter describes how to use the Oracle JCA Adapter for Files/FTP (Oracle File
and FTP Adapters), which work with Oracle BPEL Process Manager (BPEL PM) and
Oracle Mediator (Mediator). References to use cases for the Oracle File and FTP
Adapters are also provided.
■ Section 4.1, "Introduction to Oracle File and FTP Adapters"
■ Section 4.2, "Oracle File and FTP Adapters Features"
■ Section 4.3, "Oracle File and FTP Adapter Concepts"
■ Section 4.4, "Configuring Oracle File and FTP Adapters"
■ Section 4.5, "Oracle File and FTP Adapters Use Cases"
4.1 Introduction to Oracle File and FTP Adapters
BPEL PM and Mediator include the Oracle File and FTP Adapters. The Oracle File and
FTP Adapters enable a BPEL process or a Mediator to exchange (read and write) files
on local file systems and remote file systems (through use of the file transfer protocol
(FTP)). The file contents can be both XML and non-XML data formats.
■ Section 4.1.1, "Oracle File and FTP Adapters Architecture"
■ Section 4.1.2, "Oracle File and FTP Adapters Integration with BPEL PM"
■ Section 4.1.3, "Oracle File and FTP Adapters Integration with Mediator"
4.1.1 Oracle File and FTP Adapters Architecture
The Oracle File and FTP Adapters are based on JCA 1.5 architecture. JCA provides a
standard architecture for integrating heterogeneous enterprise information systems
(EIS). The JCA Binding Component of the Oracle File and FTP Adapters expose the
underlying JCA interactions as services (WSDL with JCA binding) for BPEL PM
integration. For details about Oracle JCA Adapter architecture, see Chapter 1,
"Introduction to Oracle JCA Adapters."
Note: The term Oracle JCA Adapter for Files/FTP is used for the Oracle
File and FTP Adapters, which are separate adapters with very similar
functionality.

Introduction to Oracle File and FTP Adapters
4.1.2 Oracle File and FTP Adapters Integration with BPEL PM
The Oracle File and FTP Adapters are automatically integrated with BPEL PM. When
you drag and drop File Adapter for FTP Adapter from the Component Palette of
JDeveloper BPEL Designer, the Adapter Configuration Wizard starts with a Welcome
page, as shown in Figure 4–1.
Figure 4–1 The Adapter Configuration Wizard - Welcome Page
This wizard enables you to select and configure the Oracle File and FTP Adapters. The
Adapter Configuration Wizard then prompts you to enter a service name, as shown in
Figure 3–9. When configuration is complete, a WSDL and JCA file pair is created in the
Application Navigator section of Oracle JDeveloper. This JCA file contains the
configuration information you specify in the Adapter Configuration Wizard.
The Operation Type page of the Adapter Configuration Wizard prompts you to select
an operation to perform. Based on your selection, different Adapter Configuration
Wizard pages appear and prompt you for configuration information. Table 4–1 lists the
available operations and provides references to sections that describe the configuration
information you must provide.
Table 4–1 Supported Operations for Oracle BPEL Process Manager
Operation Section
Oracle File Adapter -
■ Read File (inbound operation) Section 4.3.1, "Oracle File Adapter Read File
Concepts"
■ Write File (outbound operation) Section 4.3.2, "Oracle File Adapter Write File
Concepts"
■ Synchronous Read File (outbound
operation)
Section 4.3.3, "Oracle File Adapter Synchronous
Read Concepts"
■ List Files (outbound operation) Section 4.3.4, "Oracle File Adapter File Listing
Concepts"

Introduction to Oracle File and FTP Adapters
For more information about Oracle JCA Adapter integration with BPEL PM, see
Chapter 1, "Introduction to Oracle JCA Adapters."
4.1.3 Oracle File and FTP Adapters Integration with Mediator
The Oracle File and FTP Adapters are automatically integrated with Mediator. When
you create an Oracle File or FTP Adapter service in JDeveloper Designer, the Adapter
Configuration Wizard is started.
This wizard enables you to select and configure the Oracle File and FTP Adapters.
When configuration is complete, a WSDL, JCA file pair is created in the Application
Navigator section of Oracle JDeveloper. This JCA file contains the configuration
information you specify in the Adapter Configuration Wizard.
Wizard pages appear and prompt you for configuration information. Table 4–2 lists the
available operations and provides references to sections that describe the configuration
information you must provide.
Oracle FTP Adapter -
■ Get File (inbound operation) Section 4.3.5, "Oracle FTP Adapter Get File
Concepts"
■ Put File (outbound operation) Section 4.3.6, "Oracle FTP Adapter Put File
Concepts"
■ Synchronous Get File (outbound
operation)
Section 4.3.7, "Oracle FTP Adapter Synchronous Get
File Concepts"
■ List Files (outbound operation) Section 4.3.8, "Oracle FTP Adapter File Listing
Concepts"
Table 4–2 Supported Operations for Oracle Mediator
Operation Section
Oracle File Adapter -
■ Read File (inbound operation) Section 4.3.1, "Oracle File Adapter Read File
Concepts"
■ Write File (outbound operation) Section 4.3.2, "Oracle File Adapter Write File
Concepts"
■ Synchronous Read File (outbound
operation)
Section 4.3.3, "Oracle File Adapter Synchronous
Read Concepts"
■ List Files (outbound operation) Section 4.3.4, "Oracle File Adapter File Listing
Concepts"
Oracle FTP Adapter -
■ Get File (inbound operation) Section 4.3.5, "Oracle FTP Adapter Get File
Concepts"
■ Put File (outbound operation) Section 4.3.6, "Oracle FTP Adapter Put File
Concepts"
■ Synchronous Get File (outbound
operation)
Section 4.3.7, "Oracle FTP Adapter Synchronous Get
File Concepts"
Table 4–1 (Cont.) Supported Operations for Oracle BPEL Process Manager
Operation Section

Oracle File and FTP Adapters Features
For more information about Oracle JCA Adapter integration with Mediator, see
Chapter 1, "Introduction to Oracle JCA Adapters."
4.1.4 Oracle File and FTP Adapters Integration with SOA Composite
A composite is an assembly of services, service components (BPEL PM and Mediator),
wires, and references designed and deployed together in a single application. The
composite processes the information described in the messages. The details of the
composite are stored in the composite.xml file. For more information about integration
of the Oracle File and FTP Adapters with SOA composite, see Section 3.2.4, "Oracle
SOA Composite Integration with Adapters."
4.2 Oracle File and FTP Adapters Features
The Oracle File and FTP Adapters enable you to configure a BPEL process or a
Mediator to interact with local and remote file system directories. This section explains
the following features of the Oracle File and FTP Adapters:
■ File Formats
■ FTP Servers
■ Inbound and Outbound Interactions
■ File Debatching
■ File ChunkedRead
■ File Sorting
■ Dynamic Outbound Directory and File Name Specification
■ Security
■ Nontransactional
■ Proxy Support
■ No Payload Support
■ Large Payload Support
■ File-Based Triggers
■ Error Handling
■ Threading Model
■ Performance Tuning
■ High Availability
■ Multiple Directories
■ Append Mode
■ Recursive Processing of Files Within Directories in Oracle FTP Adapter
■ Securing Enterprise Information System Credentials
■ List Files (outbound operation) Section 4.3.8, "Oracle FTP Adapter File Listing
Concepts"
Table 4–2 (Cont.) Supported Operations for Oracle Mediator
Operation Section

4.2.1 File Formats
The Oracle File and FTP Adapters can read and write the following file formats and
use the adapter translator component at both design time and run time:
■ XML (both XSD- and DTD-based)
■ Delimited
■ Fixed positional
■ Binary data
■ COBOL Copybook data
The Oracle File and FTP Adapters can also treat file contents as an opaque object and
pass the contents in their original format (without performing translation). The opaque
option handles binary data such as JPGs and GIFs, whose structure cannot be captured
in an XSD or data you do not want to have translated.
The translator enables the Oracle File and FTP Adapters to convert native data in
various formats to XML. The native data can be simple (just a flat structure) or
complex (with parent-child relationships). The translator can handle both XML and
non-XML (native) formats of data.
4.2.2 FTP Servers
Oracle FTP Adapter supports most RFC 959 compliant FTP servers on all platforms. It
also provides a pluggable mechanism that enables Oracle FTP Adapter to support
additional FTP servers. In addition, Oracle FTP Adapter supports FTP over SSL (FTPS)
on Solaris and Linux. Oracle FTP Adapter also supports SFTP (Secure FTP) using SSH
transport.
4.2.3 Inbound and Outbound Interactions
The Oracle File and FTP Adapters exchange files in the inbound and outbound
directions. Based on the direction, the Oracle File and FTP Adapters perform different
sets of tasks.
For inbound files sent to BPEL PM or Mediator, the Oracle File and FTP Adapters
perform the following operations:
1. Poll the file system looking for matches.
2. Read and translate the file content based on the native schema (NXSD) defined at
design time.
3. Publish the translated content as an XML message.
Note: For composites with Oracle File and FTP Adapters, which are
designed to consume very large number of concurrent messages, you
must set the number of open files parameter for your operating
system to a larger value. For example, to set the number of open files
parameter to 8192 for Linux, use the ulimit -n 8192 command.
Note: Oracle FTP Adapter supports SFTP server version 4 or later.

This functionality of the Oracle File and FTP Adapters is referred to as the file read
operation, and the component that provides this function is the file reader. This
operation is known as a Java Connector Architecture (JCA) inbound activation.
For outbound files sent from BPEL PM or Mediator, the Oracle File and FTP Adapters
perform the following operations:
1. Receive messages from BPEL or Mediator.
2. Format the XML contents as specified at design time.
3. Produce output files. The output files can be created based on the following
criteria: time elapsed, file size, and number of messages. You can also specify a
combination of these criteria for output files.
This functionality of the Oracle File and FTP Adapters is referred to as the file write
operation. This operation is known as a JCA outbound interaction.
For the inbound and outbound directions, the Oracle File and FTP Adapters use a set
of configuration parameters. For example:
■ The inbound Oracle File and FTP Adapters have parameters for the inbound
directory where the input file appears and the frequency with which to poll the
directory.
■ The outbound Oracle File and FTP Adapters have parameters for the outbound
directory in which to write the file and the file naming convention to use.
The file reader supports polling conventions and offers several postprocessing options.
You can specify to delete, move, or leave the file as it is after processing the file. The
file reader can split the contents of a file and publish it in batches, instead of as a single
message. This feature can be used for performance tuning of the Oracle File and FTP
Adapters. The file reader guarantees once and once-only delivery.
See the following sections for details about the read and write functionality of the
Oracle File and FTP Adapters:
■ Section 4.3.1, "Oracle File Adapter Read File Concepts"
■ Section 4.3.2, "Oracle File Adapter Write File Concepts"
■ Section 4.3.5, "Oracle FTP Adapter Get File Concepts"
■ Section 4.3.6, "Oracle FTP Adapter Put File Concepts"
4.2.4 File Debatching
When a file contains multiple messages, you can choose to publish messages in a
specific number of batches. This is referred to as debatching. During debatching, the
file reader, on restart, proceeds from where it left off in the previous run, thereby
avoiding duplicate messages. File debatching is supported for files in XML and native
formats.
Note: You must use the Adapter Configuration Wizard to modify the
configuration parameters, such as publish size, number of messages,
and polling frequency.
You must not manually change the value of these parameters in JCA
files.

4.2.5 File ChunkedRead
This is a feature of Oracle File and FTP Adapters that uses an invoke activity within a
while loop to process the target file. This feature enables you to process arbitrarily
large files.
If an invalid payload is provided, then ChunkedRead scenarios do not throw an
exception. When a translation exception (bad record violating the NXSD specification)
is encountered, the return header is populated with the translation exception message
that includes details such as line and column where the error occurred. All translation
errors do not result in a fault. These errors are manifested as a value in the return
header. You must check the jca.file.IsMessageRejected and
jca.file.RejectionReason header values to ascertain whether an exception has
occurred. Additionally, you can also check the jca.file.NoDataFound header
value.
4.2.6 File Sorting
When files must be processed by Oracle File and FTP Adapters in a particular order,
you must configure the sorting parameters. For example, you can configure the sorting
parameters for Oracle File and FTP Adapters to process files in ascending or
descending order by time stamps.
You must meet the following prerequisites for sorting scenarios of Oracle File and FTP
Adapters:
■ Use a synchronous operation
■ Add the following property to the inbound JCA file:
<property name="ListSorter"
value="oracle.tip.adapter.file.inbound.listing.TimestampSorterAscending"/>
<property name="SingleThreadModel" value="true"/>
4.2.7 Dynamic Outbound Directory and File Name Specification
The Oracle File and FTP Adapters enable you to dynamically specify the logical or
physical name of the outbound file or outbound directory. For information about how
to specify dynamic outbound directory, see Section 4.3.2.2, "Outbound File Directory
Creation."
4.2.8 Security
The Oracle FTP Adapter supports FTP over SSL (FTPS) and Secure FTP (SFTP) to
enable secure file transfer over a network.
For more information, see Section 4.4.2, "Using Secure FTP with the Oracle FTP
Adapter" and Section 4.4.3, "Using SFTP with Oracle FTP Adapter."
4.2.9 Nontransactional
The Oracle File Adapter picks up a file from an inbound directory, processes the file,
and sends the processed file to an output directory. However, during this process if a
Note: You must not manually change the value of the publish size
parameter in JCA files. You must use Adapter Configuration Wizard
to modify this parameter.

failover occurs in the Oracle RAC backend or in an SOA managed server, then the file
is processed twice because of the nontransactional nature of Oracle File Adapter. As a
result, there can be duplicate files in the output directory.
4.2.10 Proxy Support
The proxy support feature of the Oracle FTP Adapter can be used to transfer and
retrieve data to and from the FTP servers that are located outside a firewall or can only
be accessed through a proxy server. A proxy server enables the hosts in an intranet to
indirectly connect to hosts on the Internet. Figure 4–2 shows how a proxy server
creates connections to simulate a direct connection between the client and the remote
FTP server.
Figure 4–2 Remote FTP Server Communication Through a Proxy Server
To use the HTTP proxy feature, your proxy server must support FTP traffic through
HTTP Connection. In addition, only passive data connections are supported with this
feature. For information about how to configure the Oracle FTP Adapter, see
Section 4.4.4, "Configuring Oracle FTP Adapter for HTTP Proxy."
4.2.11 No Payload Support
For BPEL PM and Mediator, the Oracle File and FTP Adapters provide support for
publishing only file metadata such as file name, directory, file size, and last modified
time to a BPEL process or Mediator and excludes the payload. The process can use this
metadata for subsequent processing. For example, the process can call another
reference and pass the file and directory name for further processing. So, the Oracle
File and FTP Adapters can be used as a notification service to notify a process
whenever a new file appears in the inbound directory. To use this feature, select the Do
not read file content check box in the JDeveloper wizard while configuring the "Read
operation."
4.2.12 Large Payload Support
For BPEL PM and Mediator, the Oracle File Adapter provides support for transferring
large files as attachments. To use this feature, select the Read File As Attachment
check box in the JDeveloper wizard while configuring the "Read operation." This
option opaquely transfers a large amount of data from one place to another as
attachments. For example, you can transfer large MS Word documents, images, and
PDFs without processing their content within the composite application. For
information about how to pass large payloads as attachments, see Section 4.5.6,
"Oracle File Adapter Read File As Attachments."
Client
Port 80
Port 21
Proxy Server
Data
Passive Port
Remote FTP Server
Control

4.2.13 File-Based Triggers
The Oracle File and FTP Adapters provide support for file-based triggers, which can
be used to control inbound adapter endpoint activation. For information about how to
use file-based triggers, see Section 4.3.1.4, "File Polling."
4.2.14 Error Handling
The Oracle File Adapter and Oracle FTP Adapter provide inbound error handling
capabilities, such as the uniqueMessageSeparator property.
In the case of debatching (multiple messages in a single file), messages from the first
bad message to the end of the file are rejected. If each message has a unique separator
and that separator is not part of any data, then rejection can be more fine grained. In
these cases, you can define a uniqueMessageSeparator property in the schema
element of the native schema to have the value of this unique message separator. This
property controls how the adapter translator works when parsing through multiple
records in one file (debatching). This property enables recovery even when detecting
bad messages inside a large batch file. When a bad record is detected, the adapter
translator skips to the next unique message separator boundary and continues from
there. If you do not set this property, then all records that follow the record with errors
are also rejected.
The following schema file provides an example of using the
uniqueMessageSeparator property:
<?xml version="1.0" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
targetNamespace="http://TargetNamespace.com/Reader"
xmlns:tns="http://TargetNamespace.com/Reader"
elementFormDefault="qualified" attributeFormDefault="unqualified"
nxsd:encoding="US-ASCII" nxsd:stream="chars"
nxsd:version="NXSD" nxsd:uniqueMessageSeparator="${eol}">
<xsd:element name="emp-listing">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="emp" minOccurs="1" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="GUID" type="xsd:string" nxsd:style="terminated"
nxsd:terminatedBy="," nxsd:quotedBy=""">
</xsd:element>
<xsd:element name="Designation" type="xsd:string"
nxsd:style="terminated" nxsd:terminatedBy=","
nxsd:quotedBy=""">
</xsd:element>
<xsd:element name="Car" type="xsd:string" nxsd:style="terminated"
</xsd:element>
<xsd:element name="Labtop" type="xsd:string"
nxsd:quotedBy=""">
</xsd:element>
<xsd:element name="Location" type="xsd:string"
Note: You must not pass large payloads as opaque schemas.

nxsd:quotedBy=""">
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>


For information about handling rejected messages, connection errors, and message
errors, see Section 2.10, "Error Handling."
4.2.15 Threading Model
This section describes the threading models that Oracle File and FTP Adapters
support. An understanding of the threading models is required to throttle or
de-throttle the Oracle File and FTP Adapters. The Oracle File and FTP Adapters use the
following threading models:
■ Default Threading Model
■ Modified Threading Model
4.2.15.1 Default Threading Model
In the default threading model, a poller is created for each inbound Oracle File or FTP
Adapter endpoint. The poller enqueues file metadata into an in-memory queue, which
is processed by a global pool of processor threads. Figure 4–3 shows a default
threading model.
Figure 4–3 Default Threading Model
The following steps highlight the functioning of the default threading model:
1. The poller periodically looks for files in the input directory. The interval at which
the poller looks for files is specified using the PollingFrequency parameter in
the inbound JCA file.
Poll File System
Enqueue
Process
EIS (File/FTP/SFTP/FTPS)
Only metadata is
enqueued e.g. filename
directory name etc
Poller In-memory Queue
Processor
By default, there are 4
processors. Can be
modified in pc.properties
1..n

2. For each new file that the poller detects in the configured inbound directory, the
poller enqueues information such as file name, file directory, modified time, and
file size into an internal in-memory queue.
3. A global pool of processor worker threads wait to process from the in-memory
queue.
4. Processor worker threads pick up files from the internal queue, and perform the
following actions:
a. Stream the file content to an appropriate translator (for example, a translator
for reading text, binary, XML, or opaque data.)
b. Publishes the XML result from the translator to the SCA infrastructure.
c. Performs the required postprocessing, such as deletion or archival after the file
is processed.
4.2.15.2 Modified Threading Model
You can modify the default threading behavior of Oracle File and FTP Adapters.
Modifying the threading model results in a modified throttling behavior of Oracle File
and FTP Adapters. The following sections describe the modified threading behavior of
the Oracle File and FTP Adapters:
■ Single Threaded Model
■ Partitioned Threaded Model
Single Threaded Model
The single threaded model is a modified threaded model that enables the poller to
assume the role of a processor. The poller thread processes the files in the same thread.
The global pool of processor threads is not used in this model. You can define the
property for a single threaded model in the inbound JCA file as follows:
<activation-spec className="oracle.tip.adapter.file.inbound.FileActivationSpec">
<property../>
<property name="SingleThreadModel" value="true"/>
<property../>
</activation-spec>
Partitioned Threaded Model
The partitioned threaded model is a modified threaded model in which the in-memory
queue is partitioned and each composite application receives its own in-memory
queue. The Oracle File and FTP Adapters are enabled to create their own processor
threads rather than depend on the global pool of processor worker threads for
processing the enqueued files. You can define the property for a partitioned model in
the inbound JCA file as follows:
<property../>
<property name="ThreadCount" value="4"/>
<property../>
</activation-spec>
In the preceding example for defining the property for a partitioned model:
Note: New files are files that are not already being processed.

■ If the ThreadCount property is set to 0, then the threading behavior is like that of
the single threaded model.
■ If the ThreadCount property is set to -1, then the global thread pool is used, as
in the default threading model.
■ The maximum value for the ThreadCount property is 40.
4.2.16 Performance Tuning
The Oracle File and FTP Adapters support the performance tuning feature by
providing knobs to throttle the inbound and outbound operations. The Oracle File and
FTP Adapters also provide knobs that can be used to tune the performance of
outbound operations.
For more information about performance tuning, see the chapter on "Oracle Adapters
Performance Tuning" in the Oracle Fusion Middleware Performance Guide.
4.2.17 High Availability
The Oracle File and FTP Adapters support the high availability feature for the
active-active topology with Oracle BPEL Process Manager and Mediator service
engines. It supports this feature for both inbound and outbound operations.
4.2.18 Multiple Directories
The Oracle File and FTP Adapters support polling multiple directories within a single
activation. You can specify multiple directories in JDeveloper as opposed to a single
directory. This is applicable to both physical and logical directories.
After selecting the inbound directory or directories, you can also specify whether the
subdirectories must be processed recursively. If you check the Process Files
Recursively option, then the directories would be processed recursively. By default,
this option is selected, in the File Directories page, as shown in Figure 4–4.
When you choose multiple directories, the generated JCA files use semicolon(;) as the
separator for these directories. However, if you want, you can change the separator to
something else. If you do so, manually add DirectorySeparator="chosen
separator" in the generated JCA file. For example, if you want to use comma (,) as
the separator, you must first change the separator to "," in the Physical directory and
then add <property name="DirectorySeparator" value=","/>, in the JCA
file.
Additionally, if you choose to process directories recursively and one or more
subdirectories do not have the appropriate permissions, then the inbound adapter
throws an exception during processing. If you want to ignore this exception, then you
must define a binding property with the name ignoreListingErrors in your
composite.xml as shown in the following example:
<service name="FlatStructureIn">
<interface.wsdl
Note: If the inbound Oracle File Adapter is configured for polling
multiple directories for incoming files, then all the top-level directories
(inbound directories where the input files appear) must exist before
the file reader starts polling these directories.

interface="http://xmlns.oracle.com/pcbpel/adapter/file/FlatStructureIn/#wsdl.inter
face(Read_ptt)"/>
<binding.jca config="FlatStructureIn_file.jca">
<property name="ignoreListingErrors" type="xs:string" many="false">true</property>
</binding.jca>
</service>
Figure 4–4 Adapter Configuration Wizard - File Directories Page
4.2.19 Append Mode
The Oracle File and FTP Adapters enable you to configure outbound interactions that
append to an existing file. The Append to Existing File option allows the outbound
invoke to write to the same file. There are two ways in which you can append to a file
name:
■ Statically - in the JCA file for the outbound Oracle File Adapter
■ Dynamically - using the header mechanism
When you select the Append to existing file option in the File Configuration page, the
batching options such as Number of Messages Equals, Elapsed Time Exceeds, File Size
Exceeds options are disabled. Figure 4–5 displays the Append to Existing File option.
Note: The append mode is not supported for SFTP scenarios, where
instead of appending to the existing file, the file is overwritten.

Figure 4–5 Adapter Configuration Wizard - File Configuration Page
Batching option is disabled if "Append" is chosen in the wizard. In addition, the
following error message is displayed if the user specifies a dynamic file naming
convention as opposed to a static file naming convention:
You can not choose to Append Files and use a dynamic file naming convention at the
same time
If you are using the "Append" functionality in Oracle FTP Adapter, ensure that the FTP
server supports the "APPE" command.
4.2.20 Recursive Processing of Files Within Directories in Oracle FTP Adapter
In earlier versions of the Oracle SOA Suite, the inbound Oracle FTP Adapter used the
NLST (Name List) FTP command to read a list of file names from the FTP server.
However, the NLST command does not return directory names and therefore does not
allow recursive processing within directories. In the 11g release, the Oracle FTP
Adapter uses the LIST command, instead.
However, the response from the LIST command is different for different FTP servers.
To incorporate the subtle differences in results from the LIST command in a standard
manner, the following parameters are added to the deployment descriptor for Oracle
FTP Adapter:
■ defaultDateFormat: This parameter specifies the default date format value. On the
FTP server, this is the value for files that are older. The default value for this
parameter is MMM d yyyy as most UNIX-type FTP servers return the last
modified time stamp for older files in the MMM d yyyy format. For example, Jan
31 2006.
You can find the default date format for your FTP server by using the ls -l
command by using a FTP command-line client. For example, ls -l on a vsftpd
server running on Linux returns the following:
-rw-r--r-- 1 500 500 377 Jan 22 2005 test.txt

For Microsoft Windows NT FTP servers, the defaultDateFormat is MM-dd-yy
hh:mma, for example, 03-24-09 08:06AM <DIR> oracle.
■ recentDateFormat: This parameter specifies the recent date format value. On the
FTP server, this is the value for files that were recently created.
The default value for this parameter is MMM d HH:mm as most UNIX-type FTP
servers return the last modified date for recently created files in MMM d HH:mm
format, for example, Jan 31 21:32.
You can find the default date format for your FTP server by using the ls -l
command from an FTP command-line client. For example, ls -l on a vsftpd
server running on Linux returns the following:
150 Here comes the directory listing.
-rw-r--r-- 1 500 500 377 Jan 30 21:32 address.txt
-rw-r--r-- 1 500 500 580 Jan 3121:32 container.txt
...............................................................................
......
For Microsoft Windows NT FTP servers, the recentDateFormat parameter is in the
MM-dd-yy hh:mma, format, for example, 03-24-09 08:06AM <DIR> oracle.
■ serverTimeZone: The server time zone, for example, America/Los_Angeles. If this
parameter is set to blank, then the default time zone of the server running the
Oracle FTP Adapter is used.
■ listParserKey: Directs the Oracle FTP Adapter on how it should parse the response
from the LIST command. The default value is UNIX, in which case the Oracle FTP
Adapter uses a generic parser for UNIX-like FTP servers. Apart from UNIX, the
other supported values are WIN and WINDOWS, which are specific to the Microsoft
Windows NT FTP server.
■ serverLocaleLanguage: This parameter specifies the locale construct for language.
■ serverLocaleCountry: This parameter specifies the locale construct for country.
■ serverLocaleVariant: This parameter specifies the locale construct for variant.
Configure the Parameters in the Deployment Descriptor
The standard date formats of an FTP server are usually configured when the FTP
server is installed. If your FTP server uses a format "MMM d yyyy" for
defaultDateFormat and "MMM d HH:mm" for recentDateFormat, then your Oracle
FTP Adapter must use the same formats in its corresponding deployment descriptor.
If you enter "ls -l" from a command-line FTP, then you can see the following:
200 PORT command successful. Consider using PASV.
150 Here comes the directory listing.
-rw-r--r-- 1 500 500 377 Jan 22 21:32 1.txt
-rw-r--r-- 1 500 500 580 Jan 22 21:32 2.txt
.................................................................................
Note: The locale language for the FTP server can be different from
the locale language for the operating system. Do not assume that the
locale for the FTP server is the same as the locale for the operating
system it is running on. You must set the serverLocaleLanguage,
serverLocaleCountry, and serverLocaleVariant parameters
in such cases.

This is the recentDateFormat parameter for your FTP server, for example MMM d
HH:mm (Jan 22 21:32). Similarly, if your server has an old file, then the server does not
show the hour and minute part and it shows the following:
-rw-r--r-- 1 500 500 377 Jan 22 2005 test.txt
This is the default date format, for example MMM d yyyy (Jan 22 2005).
Additionally, the serverTimeZone parameter is used to by the Oracle FTP Adapter to
parse time stamps for FTP server running in a specific time zone. The value for this is
either an abbreviation such as "PST" or a full name such as "America/Los_Angeles".
Additionally, the FTP server might be running on a different locale. The
serverLocaleLanguage, serverLocaleCountry, and serverLocaleVariant parameters are
used to construct a locale from language, country, variant where
■ language is a lowercase two-letter ISO-639 code, for example, en
■ country is an uppercase two-letter ISO-3166 code, for example, US
■ variant is a vendor and browser-specific code.
If these locale parameters are absent, then the Oracle FTP Adapter uses the system
locale to parse the time stamp.
Additionally, if the FTP server is running on a different system than the SOA suite,
then you must handle the time zone differences between them. You must convert the
time difference between the FTP server and the system running the Oracle FTP
Adapter to milliseconds and add the value as a binding property:"timestampOffset" in
the composite.xml.
For example, if the FTP server is six hours ahead of your local time, you must add the
following endpoint property to your service or reference:
<service name="FTPDebatchingIn">
<interface.wsdl
interface="http://xmlns.oracle.com/pcbpel/adapter/ftp/FTPDebatchingIn/#wsdl.interf
ace(Get_ptt)"/>
<binding.jca config="DebatchingIn_ftp.jca">
<property name=" timestampOffset" type="xs:string" many="false" source=""
override="may"> 21600000</property>
</binding.jca>
</service>.
Some FTP servers do not work well with the LIST command. In such cases, use the
NLST command for listing, but you cannot process directories recursively with NLST.
If you want to use the NLST command, then you must add the following property to
the JCA file, for example:
<adapter-config name="FTPDebatchingIn" adapter="Ftp Adapter"
xmlns="http://platform.integration.oracle/blocks/adapter/fw/metadata">
<connection-factory location="eis/Ftp/FtpAdapter" UIincludeWildcard="*.txt"
adapterRef=""/>
<activation-spec className="oracle.tip.adapter.ftp.inbound.FTPActivationSpec">
…………………………………………..
…………………………………………..
<property name="UseNlst" value="true"/>
</activation-spec>
</endpoint-activation>
</adapter-config>

4.2.21 Securing Enterprise Information System Credentials
When a resource adapter makes an outbound connection with an Enterprise
Information System (EIS), it must sign on with valid security credentials. In
accordance with the J2CA 1.5 specification, Oracle WebLogic Server supports both
container-managed and application-managed sign-on for outbound connections. At
runtime, Oracle WebLogic Server determines the chosen sign-on mechanism, based on
the information specified in either the invoking client component's deployment
descriptor or the res-auth element of the resource adapter deployment descriptor.
This section describes the procedure for securing the user name and password for
Oracle JCA Adapters by using Oracle WebLogic Server container-managed sign-on.
Both, Oracle WebLogic Server and EIS maintain independent security realms. A
container-managed sign-on enables you to sign on to Oracle WebLogic Server and also
be able to use applications that access EIS through a resource adapter without having
to sign on separately to the EIS. Container-managed sign-on in Oracle WebLogic
Server uses credential mappings. The credentials (user name/password pairs or
security tokens) of Oracle WebLogic security principals (authenticated individual
users or client applications) are mapped to the corresponding credentials required to
access EIS. You can configure credential mappings for applicable security principals
for any deployed resource adapter.
To configure credential mappings, you can specify the user names and passwords in
the weblogic-ra.xml file for the corresponding adapter or perform the following
procedure by accessing the Oracle WebLogic Server console:
1. Log in to the Oracle WebLogic Server console.
2. Click Deployments in the Domain Structure pane. The deployed applications and
adapters are displayed as shown in Figure 4–6.
Figure 4–6 The Oracle WebLogic Server Console - Summary of Deployments Page
3. Click the adapter for which you must create the security credentials. For example,
click FtpAdapter. The Settings for FtpAdapter page is displayed as shown in
Figure 4–7.

Figure 4–7 The Oracle WebLogic Server Console - Settings for FTPAdapter Page
4. Click the Security tab. The Settings for FTPAdapter page with the Stand-Alone
Resource Adapter Roles pane displayed as shown in Figure 4–8.
5. Click the Credential Mappings tab.
6. Click New in the Credential Mappings pane. The Create a New Security
Credential Mapping page is displayed as shown in Figure 4–9.

Figure 4–9 The Oracle WebLogic Server Console - Create a New Security Credential
Mapping Page
7. Select eis/Ftp/FtpAdapter (JNDI for Oracle FTP Adapter) to create a security
credential map entry for Oracle FTP Adapter as shown in Figure 4–10.
Mapping Page
8. Click Next. The Create a New Security Credential Mapping – WebLogic Server
User page is displayed as shown in Figure 4–11.

Mapping Page
9. Select Configured User Name and enter the Oracle WebLogic Server user name in
the WebLogic Server User Name field as shown in Figure 4–12. For example, enter
weblogic, which is the default user name.
Mapping Page
10. Click Next. The Create a New Security Credential Mapping – EIS User Name and
Password page is displayed.
Note: Credential mapping is not supported for the User for creating
initial connections and Unauthenticated WLS User options.

11. Enter the EIS user name in the EIS User Name field, the EIS password in the EIS
Password field, and then reenter the EIS password in the Confirm Password field
to confirm the password as shown in Figure 4–13.
Mapping Page
12. Click Finish. The new security credential mapping is created as shown in
Figure 4–14.

Oracle File and FTP Adapter Concepts
4.3 Oracle File and FTP Adapter Concepts
The Oracle File and FTP Adapters concepts are discussed in the following sections:
■ Section 4.3.1, "Oracle File Adapter Read File Concepts"
■ Section 4.3.2, "Oracle File Adapter Write File Concepts"
■ Section 4.3.3, "Oracle File Adapter Synchronous Read Concepts"
■ Section 4.3.4, "Oracle File Adapter File Listing Concepts"
■ Section 4.3.5, "Oracle FTP Adapter Get File Concepts"
■ Section 4.3.6, "Oracle FTP Adapter Put File Concepts"
■ Section 4.3.7, "Oracle FTP Adapter Synchronous Get File Concepts"
■ Section 4.3.8, "Oracle FTP Adapter File Listing Concepts"
4.3.1 Oracle File Adapter Read File Concepts
In the inbound direction, the Oracle File Adapter polls and reads files from a file
system for processing. This section provides an overview of the inbound file reading
capabilities of the Oracle File Adapter. You use the Adapter Configuration Wizard to
configure the Oracle File Adapter for use with a BPEL process or a Mediator.
Configuring the Oracle File Adapter creates an inbound WSDL and JCA file pair.
The following sections describe the Oracle File Adapter read file concepts:
■ Section 4.3.1.1, "Inbound Operation"
■ Section 4.3.1.2, "Inbound File Directory Specifications"
■ Section 4.3.1.3, "File Matching and Batch Processing"
■ Section 4.3.1.4, "File Polling"
■ Section 4.3.1.5, "Postprocessing"
■ Section 4.3.1.6, "Native Data Translation"
■ Section 4.3.1.7, "Inbound Service"
■ Section 4.3.1.8, "Inbound Headers"
4.3.1.1 Inbound Operation
For inbound operations with the Oracle File Adapter, select the Read File operation, as

Figure 4–15 Selecting the Read File Operation
4.3.1.2 Inbound File Directory Specifications
The File Directories page of the Adapter Configuration Wizard shown in Figure 4–16
enables you to specify information about the directory to use for reading inbound files
and the directories in which to place successfully processed files. You can choose to
process files recursively within directories. You can also specify multiple directories.
Figure 4–16 Adapter Configuration Wizard - Specifying Incoming Files
The following sections describe the file directory information to specify:

■ Section 4.3.1.2.1, "Specifying Inbound Physical or Logical Directory Paths in SOA
Composite"
■ Section 4.3.1.2.2, "Archiving Successfully Processed Files"
■ Section 4.3.1.2.3, "Deleting Files After Retrieval"
4.3.1.2.1 Specifying Inbound Physical or Logical Directory Paths in SOA Composite
You can specify inbound directory names as physical or logical paths in the composite
involving BPEL PM and Mediator. Physical paths are values such as c:inputDir.
In the composite, logical properties are specified in the inbound JCA file and their
logical-physical mapping is resolved by using binding properties. You specify the
logical parameters once at design time, and you can later modify the physical
directory name as needed.
For example, the generated inbound JCA file looks as follows for the logical input
directory name InputFileDir.
<adapter-config name="FlatStructureIn" adapter="File Adapter"
<connection-factory location="eis/FileAdapter" UIincludeWildcard="*.txt"
adapterRef=""/>
<endpoint-activation operation="Read">
<activation-spec
className="oracle.tip.adapter.file.inbound.FileActivationSpec">
<property name="UseHeaders" value="false"/>
<property name="LogicalDirectory" value="InputFileDir"/>
<property name="Recursive" value="true"/>
<property name="DeleteFile" value="true"/>
<property name="IncludeFiles" value=".*.txt"/>
<property name="PollingFrequency" value="10"/>
<property name="MinimumAge" value="0"/>
<property name="OpaqueSchema" value="false"/>
</activation-spec>
</adapter-config>
In the composite.xml file, you then provide the physical parameter values (in this
case, the directory path) of the corresponding logical ActivationSpec or
InteractionSpec. This resolves the mapping between the logical directory name
and actual physical directory name.
<service name="FlatStructureIn">
<interface.wsdl
interface="http://xmlns.oracle.com/pcbpel/adapter/file/FlatStructureIn/#wsdl.inter
face(Read_ptt)"/>
<property name=" InputFileDir" type="xs:string" many="false" source=""
Note: If the inbound Oracle File Adapter is configured for polling
multiple directories for incoming files, then all the top-level directories
(inbound directories where the input file appears) must exist before
the file reader starts polling these directories.

override="may"> /home/user/inputDir</property>
</binding.jca>
</service>
4.3.1.2.2 Archiving Successfully Processed Files
This option enables you to specify a directory in which to place successfully processed
files. You can also specify the archive directory as a logical name. In this case, you
must follow the logical-to-physical mappings described in Section 4.3.1.2.1,
"Specifying Inbound Physical or Logical Directory Paths in SOA Composite."
4.3.1.2.3 Deleting Files After Retrieval
This option enables you to specify whether to delete files after a successful retrieval. If
this check box is not selected, processed files remain in the inbound directory but are
ignored. Only files with modification dates more recent than the last processed file are
retrieved. If you place another file in the inbound directory with the same name as a
file that has been processed but the modification date remains the same, then that file
is not retrieved.
4.3.1.3 File Matching and Batch Processing
The File Filtering page of the Adapter Configuration Wizard shown in Figure 4–17
enables you to specify details about the files to retrieve or ignore.
The Oracle File Adapter acts as a file listener in the inbound direction. The Oracle File
Adapter polls the specified directory on a local or remote file system and looks for files
that match specified naming criteria.
Figure 4–17 Adapter Configuration Wizard-File Filtering Page
The following sections describe the file filtering information to specify:
■ Section 4.3.1.3.1, "Specifying a Naming Pattern"

■ Section 4.3.1.3.2, "Including and Excluding Files"
■ Section 4.3.1.3.3, "Debatching Multiple Inbound Messages"
4.3.1.3.1 Specifying a Naming Pattern
Specify the naming convention that the Oracle File Adapter uses to poll for inbound
files. You can also specify the naming convention for files you do not want to process.
Two naming conventions are available for selection. The Oracle File Adapter matches
the files that appear in the inbound directory.
■ File wildcards (po*.txt)
Retrieves all files that start with po and end with .txt. This convention conforms
to Windows operating system standards.
■ Regular expressions (po.*.txt)
Retrieves all files that start with po and end with .txt. This convention conforms
to Java Development Kit (JDK) regular expression (regex) constructs.
4.3.1.3.2 Including and Excluding Files
If you use regular expressions, the values you specify in the Include Files and Exclude
Files fields must conform to JDK regular expression (regex) constructs. For both fields,
different regex patterns must be provided separately. The Include Files and Exclude
Files fields correspond to the IncludeFiles and ExcludeFiles parameters,
respectively, of the inbound WSDL file.
If you want the inbound Oracle File Adapter to pick up all file names that start with
po and which have the extension txt, then you must specify the Include Files field as
po.*.txt when the name pattern is a regular expression. In this regex pattern
example:
Notes:
■ If you later select a different naming pattern, ensure that you also
change the naming conventions you specify in the Include Files
and Exclude Files fields. The Adapter Configuration Wizard does
not automatically make this change for you.
■ Do not specify *.* as the convention for retrieving files.
■ Be aware of any file length restrictions imposed by your operating
system. For example, Windows operating system file names
cannot be more than 256 characters in length (the file name, plus
the complete directory path). Some operating systems also have
restrictions on the use of specific characters in file names. For
example, Windows operating systems do not allow characters
such as backslash(), slash (/), colon (:), asterisk (*), left angle
bracket (<), right angle bracket (>), or vertical bar(|).
Note: The regex pattern complies with the JDK regex pattern.
According to the JDK regex pattern, the correct connotation for a
pattern of any characters with any number of occurrences is a period
followed by a plus sign (.+). An asterisk (*) in a JDK regex is not a
placeholder for a string of any characters with any number of
occurrences.

■ A period (.) indicates any character.
■ An asterisk (*) indicates any number of occurrences.
■ A backslash followed by a period (.) indicates the character period (.) as indicated
with the backslash escape character.
The Exclude Files field is constructed similarly.
If you have Include Files field and Exclude Files field expressions that have an overlap,
then the exclude files expression takes precedence. For example, if Include Files is set
to abc*.txt and Exclude Files is set to abcd*.txt, then you will not receive any
abcd*.txt files.
Table 4–3 lists details of Java regex constructs.
Note: You must enter a name pattern in the Include Files with Name
Pattern field and not leave it empty. Otherwise, the inbound adapter
service reads all the files present in the inbound directory, resulting in
incorrect results.
Note: Do not begin JDK regex pattern names with the following
characters: plus sign (+), question mark (?), or asterisk (*).
Table 4–3 Java Regular Expression Constructs
Matches Construct
Characters -
The character x x
The backslash character
The character with octal value 0n (0 <= n <= 7) 0n
The character with octal value 0nn (0 <= n <= 7) 0nn
The character with octal value 0mnn (0 <= m <= 3, 0
<= n <= 7)
0mnn
The character with hexadecimal value 0xhh xhh
The character with hexadecimal value 0xhhhh uhhhh
The tab character ('u0009') t
The new line (line feed) character ('u000A') n
The carriage-return character ('u000D') r
The form-feed character ('u000C') f
The alert (bell) character ('u0007') a
The escape character ('u001B') e
The control character corresponding to x cx
- -
Character classes -
a, b, or c (simple class) [abc]
Any character except a, b, or c (negation) [^abc]

For details about Java regex constructs, go to
http://java.sun.com/j2se/1.5.0/docs/api
4.3.1.3.3 Debatching Multiple Inbound Messages
You can select whether incoming files have multiple messages, and specify the number
of messages in one batch file to publish. When a file contains multiple messages and
this check box is selected, this is referred to as debatching. Nondebatching is applied
when the file contains only a single message and the check box is not selected.
Debatching is supported for native and XML files.
4.3.1.4 File Polling
The File Polling page of the Adapter Configuration Wizard shown in Figure 4–18
enables you to specify the following inbound polling parameters:
■ The frequency with which to poll the inbound directory for new files to retrieve.
■ The minimum file age of files to retrieve. For example, this polling parameter
enables a large file to be completely copied into the directory before it is retrieved
for processing. The age is determined by the last modified time stamp. For
example, if you know that it takes three to four minutes for a file to be written,
then set the minimum age to five minutes. If a file is detected in the input
a through z or A through Z, inclusive (range) [a-zA-Z]
a through d, or m through p: [a-dm-p] (union) [a-d[m-p]]
d, e, or f (intersection) [a-z&&[def]]
a through z, except for b and c: [ad-z] (subtraction) [a-z&&[^bc]]
a through z, and not m through p: [a-lq-z](subtraction) [a-z&&[^m-p]]
- -
Predefined character classes -
Any character (may or may not match line terminators) -
A digit: [0-9] d
A nondigit: [^0-9] D
A white space character: [ tnx0Bfr] s
A nonwhitespace character: [^s] S
A word character: [a-zA-Z_0-9] w
A nonword character: [^w] W
Greedy quantifiers -
X, once or not at all X?
X, zero or more times X*
X, one or more times X+
X, exactly n times X{n}
X, at least n times X{n,}
X, at least n, but not more than m times X{n,m}
Table 4–3 (Cont.) Java Regular Expression Constructs
Matches Construct

directory and its modification time is less than five minutes older than the current
time, then the file is not retrieved because it is still potentially being written to.
Figure 4–18 Adapter Configuration Wizard-File Polling Page
Using Trigger Files
By default, polling by inbound Oracle File and FTP Adapters start as soon as the
endpoint is activated. However, if you want more control over polling, then you can
use a file-based trigger. Once the Oracle File or FTP Adapter finds the specified trigger
file in a local or remote directory, it starts polling for the files in the inbound directory.
For example, a BPEL process is writing files to a directory and a second BPEL process
is polling the same directory for files. If you want the second process to start polling
the directory only after the first process has written all the files, then you can use a
trigger file. You can configure the first process to create a trigger file at the end. The
second process starts polling the inbound directory once it finds the trigger file.
The trigger file directory can be the same as the inbound polling directory or different
from the inbound polling directory. However, if your trigger file directory and the
inbound polling directory are the same, then you should ensure that the name of the
trigger file is not similar to the file filter specified in the Adapter Configuration page
The content of a trigger file is never read and therefore should not be used as payload
for an inbound receive activity.
Table 4–4 lists the parameters that you must specify in the inbound service JCA file:
Note: You must not manually change the value of polling parameters
in JCA files. You must use the Adapter Configuration Wizard to
modify this parameter.

The following is a sample JCA file for the inbound service:
Table 4–4 Trigger File Parameters
Parameter Description Example
TriggerFilePhysicalDi
rectory
or
TriggerFileLogicalDir
ectory
The physical or logical name
of the directory in which the
Oracle File and FTP
Adapters look for the
trigger file.
The
rectory and
ectory parameters are
optional. These parameters
must be used only if the
trigger file directory is
different from the inbound
polling directory. By default,
the Oracle File and FTP
Adapters looks for the
trigger file in the inbound
polling directory.
rectory="C:foo"
ectory=
"TriggerFileDir"
TriggerFile The name of the trigger file. TriggerFile="Purchase
order.trg"
TriggerFileStrategy Strategy that is used as the
triggering mechanism. The
value can be one of the
following:
EndpointActivation: The
adapter looks for the trigger
file every time the
composite is activated.
Note: The composite gets
activated every time you
start the container or
redeploy the application, or
retire or activate the
composite application from
Oracle Enterprise Manager.
Every time you restart the
container, the composite
application is not triggered
until it sees the trigger file in
the specified directory.
OnceOnly: The adapter
looks for the trigger file only
once in its lifetime. Once it
finds the trigger file, it
remember that across
restarts and redeployments.
EveryTime: The adapter
looks for the trigger file on
each polling cycle.The
default value for
TriggerFileStrategy is
EndpointActivation.
TriggerFileStrategy="
EndpointActivation "

adapterRef=""/>
<endpoint-activation operation="Read">
<property.../>
<property name="TriggerFilePhysicalDirectory" value="/tmp/flat/ArchiveDir"/>
</activation-spec>
</adapter-config>
4.3.1.5 Postprocessing
The Oracle File Adapter supports several postprocessing options. After processing the
file, files are deleted if specified in the File Polling page shown in Figure 4–18. Files can
also be moved to a completion (archive) directory if specified in the File Directories
page shown in Figure 4–16.
4.3.1.6 Native Data Translation
The next Adapter Configuration Wizard page that appears is the Messages page
shown in Figure 4–19. This page enables you to select the XSD schema file for
translation.
Figure 4–19 Specifying the Schema - Messages Page
If native format translation is not required (for example, a JPG or GIF image is being
processed), then select the Native format translation is not required check box. The
file is passed through in base-64 encoding.

XSD files are required for translation. If you want to define a new schema or convert
an existing data type definition (DTD) or COBOL Copybook, then select Define
Schema for Native Format. This starts the Native Format Builder Wizard. This wizard
guides you through the creation of a native schema file from file formats such as
comma-separated value (CSV), fixed-length, DTD, and COBOL Copybook. After the
native schema file is created, the Messages page is displayed, with the Schema File
URL and Schema Element fields filled in. For more information, see Section 6.1,
"Creating Native Schema Files with the Native Format Builder Wizard."
4.3.1.7 Inbound Service
When you finish configuring the Oracle File Adapter, a JCA file is generated for the
inbound service. The file is named after the service name you specified on the Service
Name page of the Adapter Configuration Wizard shown in Figure 3–8. You can rerun
the wizard later to change your operation definitions.
The ActivationSpec parameter holds the inbound configuration information. The
ActivationSpec and a set of inbound Oracle File Adapter properties are part of the
inbound JCA file.
Table 4–5 lists the properties of a sample inbound JCA file.
The ActivationSpec property values are specified in the Adapter Configuration
Wizard during design time and as shown in Table 4–5. The inbound Oracle File
Adapter uses the following configuration properties:
■ PollingFrequency
■ MinimumAge
■ PhysicalDirectory
■ LogicalDirectory
■ PublishSize
■ PhysicalArchiveDirectory
■ LogicalArchiveDirectory
■ IncludeFiles
Note: Ensure that the schema you specify includes a namespace. If
your schema does not have a namespace, then an error message is
displayed.
Table 4–5 Sample JCA Properties for Inbound Service
Property Sample Value
UseHeaders true
PhysicalDirectory /tmp/opaque/in
Recursive true
DeleteFile false
IncludeFiles .*.xml
PollingFrequency 1
MinimumAge 0

■ ExcludeFiles
■ UseHeaders
■ ListSorter
■ ThreadCount
■ Recursive
■ MaxRaiseSize
For a description of these configuration properties, see Section A–1, " Properties for
Oracle File and FTP Adapters."
4.3.1.8 Inbound Headers
Apart from the payload, Oracle File Adapter publishes the following header metadata,
from the inbound service, as shown in Figure 4–20:
■ jca.file.FileName: file name
■ jca.file.Directory: directory name
■ jca.file.Batch: a unique name for a batch in case of debatching
■ jca.file.BatchIndex: the batch index for each message within the batch for
debatching
■ jca.file.Size: the file size
■ jca.file.LastModifiedTime: the last modified time for the file
Figure 4–20 The Invoke Dialog
4.3.2 Oracle File Adapter Write File Concepts
In the outbound direction, the Oracle File Adapter receives messages from the service
engine and writes the messages to a file in a file system. This section provides an
overview of the outbound file writing capabilities of the Oracle File Adapter. You use
the Adapter Configuration Wizard to configure the Oracle File Adapter for use with a
BPEL process or a Mediator Service. This creates an outbound WSDL and a JCA file
pair.

■ Section 4.3.2.1, "Outbound Operation"
■ Section 4.3.2.2, "Outbound File Directory Creation"
■ Section 4.3.2.3, "Native Data Translation"
■ Section 4.3.2.4, "Outbound Service Files"
■ Section 4.3.2.5, "Outbound Headers"
4.3.2.1 Outbound Operation
For outbound operations with the Oracle File Adapter, select the Write File operation,
as shown in Figure 4–21.
Figure 4–21 Selecting the Write File Operation
4.3.2.2 Outbound File Directory Creation
For the outbound operation, you can specify the outbound directory, outbound file
naming convention to use, and, if necessary, the batch file conventions to use.
The File Configuration page of the Adapter Configuration Wizard shown in
Figure 4–22 enables you to specify the directory for outgoing files and the outbound
file naming convention.

Figure 4–22 Adapter Configuration Wizard-Parameters for Outgoing Files
The following sections describe the file configuration information to specify:
■ Section 4.3.2.2.1, "Specifying Outbound Physical or Logical Directory Paths in
BPEL PM"
■ Section 4.3.2.2.4, "Specifying the Outbound File Naming Convention"
■ Section 4.3.2.2.5, "Specifying a Dynamic Outbound File Name"
■ Section 4.3.2.2.6, "Batching Multiple Outbound Messages"
4.3.2.2.1 Specifying Outbound Physical or Logical Directory Paths in BPEL PM
You can specify outbound directory names as physical or logical paths. Physical paths
are values such as c:outputDir.
If you specify logical parameters, then the generated JCA file looks as follows for the
logical outbound directory name OutputFileDir.
<adapter-config name="FlatStructureOut" adapter="File Adapter"
<connection-factory location="eis/FileAdapter" adapterRef=""/>
<endpoint-interaction operation="Write">
<interaction-spec
className="oracle.tip.adapter.file.outbound.FileInteractionSpec">
<property name="LogicalDirectory" value="OutputFileDir"/>
<property name="FileNamingConvention" value="%yyMMddHHmmssSS%_%SEQ%_
%yyyyMMdd%_%SEQ%.out.%SEQ%"/>
<property name="Append" value="false"/>
<property name="NumberMessages" value="1"/>
<property name="OpaqueSchema" value="false"/>
</interaction-spec>
</endpoint-interaction>
</adapter-config>

Select the outbound adapter in the "External References" swim lane in JDeveloper
wizard (it is present in the composite.xml tab). Create a "Binding Property" in the
Property Inspector for the outbound adapter (you must scroll down to find it). Once
the Create Property box appears, enter OutputFileDir in the Name field and the
actual output dir name, example, C:outputDir in the Value field. The
composite.xml file appears as follows:
<reference name="FlatStructureOut">
<interface.wsdl
interface="http://xmlns.oracle.com/pcbpel/adapter/file/FlatStructureOut/#wsdl.inte
rface(Write_ptt)"/>
<binding.jca config="FlatStructureOut_file.jca">
<property name="OutputFileDir" type="xs:string" many="false"
override="may">C:outputDir</property>
</binding.jca>
</reference>
4.3.2.2.2 Specifying Outbound Physical or Logical Directory Paths in Mediator
You can specify outbound directory names as physical or logical paths in Mediator.
Physical paths are values such as c:inputDir.
You can specify the logical names at design time in the File Directories page shown in
Figure 4–16 and then provide logical-physical mapping by using the Endpoint
properties. For example, WriteFile is an outbound adapter service. You have
specified OutDir as the logical directory name at design time.
4.3.2.2.3 Specifying a Dynamic Outbound Directory Name
For outbound operation, you can specify a dynamic outbound directory name. You
can set variables to specify dynamic outbound directory names.
<adapter-config name="ReadAddressChunk" adapter="File Adapter"
<endpoint-interaction operation="ChunkedRead">
<interaction-spec
className="oracle.tip.adapter.file.outbound.ChunkedInteractionSpec">
<property name="PhysicalDirectory" value="C:foo"/>
<property name="FileName" value="dummy.txt"/>
<property name="ChunkSize" value="1"/>
</interaction-spec>
</adapter-config>
In the preceding example, in the JCA file, the physical directory is set to "C:foo" but
during run time it is dynamically changed to the assigned value. In this example, the
physical directory is dynamically changed to "C:out". You must perform the
following steps to specify the dynamic outbound directory name:
Note: Ensure that you limit the length of outbound file names (the
file name, plus the complete directory path) to 200 characters. This is
not an exact limit but rather a recommendation. When an outbound
file name is long (for example, 215 characters), a blank file with that
name is created in the outbound directory.

1. Double-click the invoke activity.
2. Click the Browse Variables icon.
3. In the Variable Chooser dialog, click the Create an Object icon.
4. Create a variable MyDir of type xsd:string as shown in Figure 4–23.
Figure 4–23 Create Variable Dialog
5. Drag and drop an Assign activity from the Component Palette in between the
Receive and Invoke activities in the design area.
6. Double-click the assign activity and click the Copy Operation tab.
7. Click Create and then Copy Operation. The Create Copy Operation dialog is
displayed.
8. In the Create Copy Operation dialog, select Expression from Type and specify the
directory name and path as shown in Figure 4–24. The output file is written to this
directory.

Figure 4–24 Create Copy Operation Dialog
9. Click OK in the Create Copy Operation dialog and then click OK in the Assign
dialog. The .bpel page is displayed.
10. Double-click the invoke activity. The Invoke dialog is displayed.
11. Click the Properties tab.
12. Select the jca.file.Directory property from the Properties column and set
the Value as MyDir (the directory that you created in Step 4.) Ensure that the Type
column is set to input, as shown in Figure 4–25.

4.3.2.2.4 Specifying the Outbound File Naming Convention
Specify the naming convention to use for outgoing files. You cannot enter completely
static names such as po.txt. This is to ensure the uniqueness in names of outgoing
files, which prevents files from being inadvertently overwritten. Instead, outgoing file
names must be a combination of static and dynamic portions.
The prefix and suffix portions of the file example shown in Figure 4–22 are static (for
example, po_ and .xml). The %SEQ% variable of the name is dynamic and can be a
sequence number or a time stamp (for example, po_%yyMMddHHmmss%.xml to create
a file with a time stamp).
If you choose a name starting with po_, followed by a sequence number and the
extension txt as the naming convention of the outgoing files, then you must specify
po_%SEQ%.txt.
If you choose a name starting with po_, followed by a time stamp with the pattern
yyyy.MM.dd and the extension txt as the naming convention of the outgoing file,
then you must specify po_%yyyy.MM.dd%.txt. For example, the outgoing file name
can be po_2004.11.29.txt.
Additionally, you can combine file naming conventions. For example, you can specify
the file naming convention as po_%SEQ%_%yyyy.MM.dd%_%SEQ%.txt.
Note: When using dynamic directories, ensure that parameters such
as NumberMessages, ElapsedTime, and FileSize are not defined
in the outbound adapter service WSDL file. These parameters are not
supported with dynamic directories.

You cannot use a regular expression for outbound synchronous reads. In these cases,
the exact file name must be known.
A time stamp is specified by date and time pattern strings. Within date and time
pattern strings, unquoted letters from 'A' to 'Z' and from 'a' to 'z' are interpreted
as pattern letters representing the components of a date or time string. Text can be
quoted using single quotation marks (') to avoid interpretation. The characters "''"
represent single quotation marks. All other characters are not interpreted.
The Java pattern letters are defined in Table 4–6.
Different presentations in the pattern are as follows:
Note: When you use the time stamp pattern, the same time stamp
may be generated on subsequent calls and you may lose messages.
The workaround is to combine the time-stamp pattern with a
sequence pattern. Alternatively, you can use a time-stamp pattern
closest to a millisecond, in which case the adapter handles the
uniqueness of the file names.
Table 4–6 Java Pattern Letters
Letter
Date or Time
Component Presentation Examples
G Era designator Text AD
y Year Year 1996; 96
M Month in year Month July; Jul; 07
w Week in year Number 27
W Week in month Number 2
D Day in year Number 189
d Day in month Number 10
F Day of week in month Number 2
E Day in week Text Tuesday; Tue
a AM/PM marker Text PM
H Hour in day (0-23) Number 0
k Hour in day (1-24) Number 24
K Hour in AM/PM
(0-11)
Number 0
h Hour in AM/PM
(1-12)
Number 12
m Minute in hour Number 30
s Second in minute Number 55
S Millisecond Number 978
z Time zone General Time Zone Pacific Standard
Time; PST;
GMT-08:00
Z Time zone RFC 822 Time Zone -0800

■ Text
For formatting, if the number of pattern letters is four or more, then the full form is
used; otherwise, a short or abbreviated form is used if available. For parsing, both
forms are accepted, independent of the number of pattern letters.
■ Number
For formatting, the number of pattern letters is the minimum number of digits,
and shorter numbers are zero-padded to this number. For parsing, the number of
pattern letters is ignored unless it is needed to separate two adjacent fields.
■ Year
For formatting, if the number of pattern letters is two, then the year is truncated to
two digits; otherwise, it is interpreted as a number.
For parsing, if the number of pattern letters is more than two, then the year is
interpreted literally, regardless of the number of digits. Using the pattern
MM/dd/yyyy, 01/11/12 parses to Jan 11, 12 A.D.
For parsing with the abbreviated year pattern (y or yy), the abbreviated year is
interpreted relative to some century. The date is adjusted to be within 80 years before
and 20 years after the time instance is created. For example, using a pattern of
MM/dd/yy and Jan 1, 1997 is created; the string 01/11/12 is interpreted as Jan
11, 2012, while the string 05/04/64 is interpreted as May 4, 1964. During
parsing, only strings consisting of exactly two digits are parsed into the default
century. Any other numeric string, such as a one-digit string, a three-or-more-digit
string, or a two-digit string that is not all digits (for example, -1), is interpreted
literally. So, 01/02/3 or 01/02/003 is parsed using the same pattern as Jan 2, 3
AD. Likewise, 01/02/-3 is parsed as Jan 2, 4 BC.
■ Month
If the number of pattern letters is 3 or more, then the month is interpreted as text;
otherwise, it is interpreted as a number.
■ General time zone
Time zones are interpreted as text if they have names. For time zones representing
a GMT offset value, the following syntax is used:
GMTOffsetTimeZone:
GMT Sign Hours : Minutes
Sign: one of
+ -
Hours:
Digit
Digit Digit
Minutes:
Digit Digit
Digit: one of
0 1 2 3 4 5 6 7 8 9
Hours must be between 0 and 23, and Minutes must be between 00 and 59. The
format is locale-independent and digits must be taken from the Basic Latin block of the
Unicode standard.
For parsing, RFC 822 time zones are also accepted.
For formatting, the RFC 822 4-digit time zone format is used:
RFC822TimeZone:
Sign TwoDigitHours Minutes

TwoDigitHours:
Digit Digit
TwoDigitHours must be between 00 and 23. Other definitions are the same as for
general time zones.
For parsing, general time zones are also accepted.
4.3.2.2.5 Specifying a Dynamic Outbound File Name
For outbound operation, you can specify a dynamic outbound file name. You can set
variables to specify dynamic outbound file names.
<endpoint-interaction operation="ChunkedRead">
<interaction-spec
<property name="PhysicalDirectory" value="C:foo"/>
</interaction-spec>
</adapter-config>
In the preceding example, in the JCA file, the physical directory is set to "C:foo" but
during run time it is dynamically changed to the assigned value. In this example, the
physical directory is dynamically changed to "C:out". You must perform the
following steps to specify the dynamic outbound directory name:
1. Double-click the invoke activity.
2. Click the Browse Variables icon.
3. In the Variable Chooser dialog, click the Create an Object icon.
4. Create a variable file of type xsd:string as shown in Figure 4–23.
6. Double-click the assign activity and click the Copy Operation tab.
7. Click Create and then Copy Operation. The Create Copy Operation dialog is
displayed.
8. In the Create Copy Operation dialog, select Expression from Type and specify the
file name as shown in Figure 4–24. The output file is written to this file.
9. Click OK till you exit the assign activity dialog.
10. Double-click the invoke activity. The Invoke dialog is displayed.
11. Click the Properties tab.
12. Select the jca.file.FileName property from the Properties column and set the
Value as file (the file that you created in Step 4.) Ensure that the Type column is
set to input, as shown in Figure 4–26.

4.3.2.2.6 Batching Multiple Outbound Messages
In the simplest scenario, you specify writing a single file to a single message. You can
also specify the outbound method for batch file writing. This method enables you to
specify the number of messages to publish in one batch file . The following batch file
settings are provided in the File Configuration page shown in Figure 4–22:
■ Number of Messages Equals
Specify a value which, when equaled, causes a new outgoing file to be created.
■ Elapsed Time Exceeds
Specify a time which, when exceeded, causes a new outgoing file to be created.
For example, if you specify that elapsed time exceeds 15 seconds, then the first
message that is received is not written out, even after 15 seconds, as batching
conditions are not valid. If a second message is received, then batching conditions
become valid for the first one, and an output file is created when the elapsed time
exceeds 15 seconds.
■ File Size Exceeds
Specify a file size which, when equaled, causes an outgoing file to be created. For
example, assume that you specify a value of 3 for the number of messages
received and a value of 1 MB for the file size. When you receive two messages that
when combined equal or exceed 1 MB, or three messages that are less than 1 MB,
an output file is created.
Note: When using dynamic files, ensure that parameters such as
NumberMessages, ElapsedTime, and FileSize are not defined in
the outbound adapter service WSDL file. These parameters are not
supported with dynamic files.
Note: The Elapsed Time Exceeds batching criteria is evaluated and a
new outgoing file is created, only when an invocation happens.

If the Oracle File Adapter encounters some problem during batching, then it starts
batching at the point at which it left off on recovery.
4.3.2.3 Native Data Translation
The next Adapter Configuration Wizard page that appears is the Messages page
shown in Figure 4–27. This page enables you to select the XSD schema file for
translation.
Figure 4–27 Specifying the Schema
As with specifying the schema for the inbound direction, you can perform the
following tasks in this page:
■ Specify whether native format translation is not required.
■ Select the XSD schema file for translation.
■ Start the Native Format Builder Wizard to create an XSD file from file formats such
as CSV, fixed-length, DTD, and COBOL Copybook.
For more information about Messages page, see Section 4.3.1.6, "Native Data
Translation."
4.3.2.4 Outbound Service Files
When you complete configuration of the Oracle File Adapter with the Adapter
Configuration Wizard, a WSDL and a JCA file pair is generated for the outbound
operation. The files are named after the service name you specified on the Service
Name page of the Adapter Configuration Wizard shown in Figure 3–7. You can rerun
the wizard later to change your operation definitions.
Note: You must not manually change the file configurations specified
in the preceding list in the JCA files. You must use the Adapter
Configuration Wizard to modify these configurations.

A sample outbound JCA file includes the information listed in Table 4–7:
The outbound Oracle File Adapter uses the following configuration parameters:
■ PhysicalDirectory
■ LogicalDirectory
■ NumberMessages
■ ElapsedTime
■ FileSize
■ FileNamingConvention
■ Append
For a description of these configuration properties, see Table A–1.
4.3.2.5 Outbound Headers
Apart from the payload, the Oracle File Adapter receives the following headers from
the component:
■ jca.file.FileName: file name
■ jca.file.Directory: directory name
4.3.3 Oracle File Adapter Synchronous Read Concepts
In the outbound direction, the Oracle File Adapter polls and reads the current contents
of files. This section provides an overview of the outbound synchronous file reading
capabilities of the Oracle File Adapter. For reading a file synchronously, you select
Synchronous Read File operation, as shown in Figure 4–28.
Table 4–7 Sample JCA Properties for Outbound Service
Property Sample Value
PhysicalDirectory /tmp/flat/OutputDir
FileNamingConvention address-csv%SEQ%.txt
Append true
NumberMessages 1
ConcurrentThreshold 0
OpaqueSchema false

Figure 4–28 Synchronous Read Operation Page
All the pages of the Adapter Configuration Wizard are similar to the Read File
operation except the File Name page. You can specify the name of the file to be read in
the File Name field, as shown in Figure 4–29.
Figure 4–29 File Directories Page
4.3.4 Oracle File Adapter File Listing Concepts
This feature of the Oracle File Adapter lets you use a BPEL activity to retrieve a list of
files from a target directory. This list of files is returned as an XML document and

contains information such as file name, directory name, file size, and last modified
time. This section provides an overview of the file listing capabilities of the Oracle File
Adapter. You use the Adapter Configuration Wizard to configure the Oracle File
Adapter for use with a BPEL process or a Mediator service. This creates an outbound
WSDL and JCA file pair.
■ Section 4.3.4.1, "Listing Operation"
■ Section 4.3.4.2, "File Directory Specifications"
■ Section 4.3.4.3, "File Matching"
4.3.4.1 Listing Operation
For listing files, you must select the List Files operation, as shown in Figure 4–30.
Figure 4–30 List Files Operation Page
Note: The file creation time property, creationTime, is not
supported because the standard Java APIs do not provide a
mechanism to retrieve the creation time. The value of the
creationTime property is always displayed as 0.
For example,
<creationTime
xmlns="http://xmlns.oracle.com/pcbpel/adapter/file/FAListFiles/FALi
stFilesTest/ReadS/">0</creationTime>

4.3.4.2 File Directory Specifications
The File Directories page of the Adapter Configuration Wizard shown in Figure 4–31
enables you to specify information about the directory to use for reading files names
for the list operation. You can choose to list files recursively within directories.
Figure 4–31 Adapter Configuration Wizard-Specifying Incoming Files
The following section describes the file directory information to specify:
4.3.4.2.1 Specifying Inbound Physical or Logical Directory Paths in SOA Composite
You can specify directory names as physical or logical paths for composites involving
BPEL PM and Mediator. Physical paths are values such as C:inputDir.
In the composite, logical properties are specified in the JCA file, and their
logical-physical mapping is resolved by using binding properties. You specify the
logical directory once at design time, and you can later modify the directory name as
needed.
For example, the generated JCA file looks as follows for the logical input directory
name C:inputDir:
<adapter-config name="ListFiles" adapter="File Adapter"
adapterRef=""/>
<endpoint-interaction portType="FileListing_ptt" operation="FileListing">
<interaction-spec
className="oracle.tip.adapter.file.outbound.FileListInteractionSpec">
<property name="PhysicalDirectory" value="C:inputDir"/>
<property name="Recursive" value="true"/>
<property name="IncludeFiles" value=".*.txt"/>
</interaction-spec>

</adapter-config>
4.3.4.3 File Matching
The File Filtering page of the Adapter Configuration Wizard shown in Figure 4–32
enables you to specify details about the files to retrieve or ignore.
The Oracle File Adapter acts as a file listener and polls the specified directory on a
local or remote file system and looks for files that match specified naming criteria.
Figure 4–32 Adapter Configuration Wizard - File Filtering
The following sections describe the file filtering information to specify:
■ Section 4.3.4.3.1, "Specifying a Naming Pattern"
■ Section 4.3.4.3.2, "Including and Excluding Files"
4.3.4.3.1 Specifying a Naming Pattern
Specify the naming convention that the Oracle File Adapter uses to poll for inbound
files. You can also specify the naming convention for files you do not want to process.
Two naming conventions are available for selection. The Oracle File Adapter matches
the files that appear in the inbound directory.
■ File wildcards (po*.txt)
Retrieve all files that start with po and end with .txt. This convention conforms
to operating system standards.
■ Regular expressions (po.*.txt)
Retrieve all files that start with po and end with .txt. This convention conforms
to Java Development Kit (JDK) regular expression (regex) constructs.

4.3.4.3.2 Including and Excluding Files
If you use regular expressions, the values you specify in the Include Files and Exclude
Files fields must conform to JDK regular expression (regex) constructs. For both fields,
different regex patterns must be provided separately. The Include Files and Exclude
Files fields correspond to the IncludeFiles and ExcludeFiles parameters,
respectively, of the inbound WSDL file.
If you want the inbound Oracle File Adapter to pick up all file names that start with
po and which have the extension txt, you must specify the Include Files field as
po.*.txt when the name pattern is a regular expression. In this regex pattern
example:
■ A period (.) indicates any character.
■ An asterisk (*) indicates any number of occurrences.
■ A backslash followed by a period (.) indicates the character period (.) as indicated
with the backslash escape character.
The Exclude Files field is constructed similarly.
If you have Include Files field and Exclude Files field expressions that have an overlap,
then the exclude files expression takes precedence. For example, if Include Files is set
to abc*.txt and Exclude Files is set to abcd*.txt, then you receive any files
prefixed with abcd*.
For details about Java regex constructs, go to
Notes:
■ If you later select a different naming pattern, ensure that you also
change the naming conventions you specify in the Include Files
and Exclude Files fields. The Adapter Configuration Wizard does
not automatically make this change for you.
■ Do not specify *.* as the convention for retrieving files.
■ Be aware of any file length restrictions imposed by your operating
system. For example, Windows operating system file names
cannot be more than 256 characters in length (the file name, plus
the complete directory path). Some operating systems also have
restrictions on the use of specific characters in file names. For
example, Windows operating systems do not allow characters
such as backslash(), slash (/), colon (:), asterisk (*), left angle
bracket (<), right angle bracket (>), or vertical bar(|).
Note: The regex pattern complies with the JDK regex pattern.
According to the JDK regex pattern, the correct connotation for a
pattern of any characters with any number of occurrences is a period
followed by a plus sign (.+). An asterisk (*) in a JDK regex is not a
placeholder for a string of any characters with any number of
occurrences.
Note: Do not begin JDK regex pattern names with the following
characters: plus sign (+), question mark (?), or asterisk (*).

http://java.sun.com/j2se/1.5.0/docs/api
4.3.5 Oracle FTP Adapter Get File Concepts
In the inbound direction, the Oracle FTP Adapter works the same way as the Read File
operations of the Oracle File Adapter in that it polls and gets files from a file system
for processing. The major difference is that the Oracle FTP Adapter is used for remote
file exchanges. To configure the FTP adapter for remote file exchanges, the Adapter
Configuration Wizard asks for connection information to an FTP server to be used
later, as shown in Figure 4–33.
Figure 4–33 Specifying FTP Server Connection Information
The default adapter instance JNDI name is eis/Ftp/FtpAdapter, or use a custom
name. This name connects to the FTP server during run time.
After logging in, you select the Get File (read) operation and the type of file to deliver.
Figure 4–34 shows this selection.
Note: Files are not read and therefore there is no native data
translation.
Note: The Oracle FTP Adapter does not support the FTP commands
RESTART and RECOVERY during the transfer of large files.

Figure 4–34 Selecting the Get File Operation
The serverType property in the deployment descriptor is used to determine line
separators when you transfer data. You can specify unix, win, or mac as property
values. These values represent the operating system on which the FTP server is
running. By default, the serverType property contains unix.
When you specify mac as the value, r is used as line separator. For unix, n is used
and for win, rn is used. You must note that this property is used by the NXSD
translator component to write the line separator during an outbound operation.
From this point onwards, pages of the Adapter Configuration Wizard for the Get File
operation are the same as those for the Read File operation of the file. Table 4–8 lists
the pages that are displayed and provides references to sections that describe their
functionality.
An additional Adapter Configuration Wizard page is also available for advanced
users. This page is shown in Figure 4–35 and appears only after you make either or
both of the following selections on the File Polling page shown in Figure 4–18:
■ Do not select the Delete Files After Successful Retrieval check box.
■ Set the value of the Minimum File Age field to a value greater than 0.
Table 4–8 Adapter Configuration Wizard Windows for Get File Operation
Page See Section...
File Directories (Figure 4–16) Section 4.3.1.2, "Inbound File Directory Specifications"
File Filtering (Figure 4–17) Section 4.3.1.3, "File Matching and Batch Processing"
File Polling (Figure 4–18) Section 4.3.1.4, "File Polling"
Messages (Figure 4–19) Section 4.3.1.6, "Native Data Translation"

Figure 4–35 File Modification Time
This page enables you to specify a method for obtaining the modification time of files
on the remote FTP server:
■ File System
This option enables you to obtain the date/time format of the file modification
time with the file system listing command. However, this option is rarely used and
is not supported by all FTP servers. See your FTP server documentation to
determine whether your server supports the file system listing command, which
command-line syntax to use, and how to interpret the output.
For example, if the file system listing command quote mdtm filename is
supported and returns the following information:
213 20050602102633
specify the start index, end index, and date/time format of the file modification
time in the Data/Time Format field as a single value separated by commas (for
example, 4,18,yyyyMMddHHmmss).
Note: The Oracle FTP Adapter uses the LIST command as opposed
to NLST for listing and retrieves the time stamps because of which you
need not specify the time formats. However, you must specify the
time formats as shown below if you do any of the following:
■ If you specify NLST as the listing command (either through the
mapping file or the UseNlst="true" parameter in the
inboundJCA file)
■ If you want to use the File Name Substring option
This note is not applicable if your case does not fall under neither of
these categories.

Where:
– 4 is the start index of the file modification time.
– 18 is the end index of the file modification time.
– yyyyMMddHHmmss is the data/time format of the file modification time
obtained with the quote mdtm filename command.
The resulting JCA file includes the following parameters and values:
<property name=" FileModificationTime " value=" FileSystem "/>
<property name=" ModificationTimeFormat" value=" 4,18,yyyyMMddHHmmss "/>
To handle the time zone issue, you must also be aware of the time stamp
difference. The time zone of the FTP server is determined by using the Windows
date/time properties (for example, by double-clicking the time being displayed in
the Windows task bar). You must then convert the time difference between the FTP
server and the system on which the Oracle FTP Adapter is running to milliseconds
and add the value as a binding property in the composite.xml file:
<property name="timestampOffset" source="" type="xs:string" many="false"
override="may">238488888</property-->
</binding.jca>
■ Directory Listing
This option enables you to obtain the date/time format from the file modification
time with the FTP directory listing command. For example, if the directory listing
command (ls -l) returns the following information:
12-27-04 07:44AM 2829 NativeData2.txt
specify the start index, end index, and date/time format of the file modification
time as a single value separated by commas in either the Old File Date/Time
Format field or the Recent File Date/Time Format field (for example, 0,17,
MM-dd-yy hh:mma).
Where:
– 0 is the start index of the file modification time.
– 17 is the end index of the file modification time.
– MM-dd-yy hh:mma is the date/time format of the file modification time
obtained with the ls -l command. For this example, the value is entered in
the Recent File Date/Time Format field. This field indicates that the format is
obtained from the most recent file adhering to the naming convention,
whereas the Old File Date/Time Format field obtains the format from the
oldest file.
<property name=" FileModificationTime " value=" DirListing"/>
<property name=" ModificationTimeFormat" value="0,17, MM-dd-yy hh:mma "/>
To handle the time zone issue, you must also be aware of the time stamp
difference. The time zone of the FTP server is determined by using the Windows
date/time properties (for example, by double-clicking the time being displayed in
the Windows task bar). You must then convert the time difference between the FTP
server and the system on which the Oracle FTP Adapter is running to milliseconds
and add the value as a binding property in the composite.xml file:

<property name="timestampOffset" source="" type="xs:string" many="false"
override="may">238488888</property-->
</binding.jca>
■ File Name Substring
This option enables you to obtain the modification time from the file name. For
example, if the name of the file is fixedLength_20050324.txt, you can specify
the following values:
– The start index in the Substring Begin Index field (for example, 12)
– The end index in the End Index field (for example, 20)
– The date and time format in the Date/Time Format field conforming to the
Java SimpleDateFormat to indicate the file modification time in the file
name (for example, yyyyMMdd)
<property name=" FileModificationTime " value=" Filename"/>
<property name=" FileNameSubstringBegin " value="12 "/>
<property name=" FileNameSubstringEnd " value="20"/>
<property name=" ModificationTimeFormat " value=" yyyyMMdd "/>
After the completion of Adapter Configuration Wizard, configuration files are created
in the Applications section of Oracle JDeveloper.
See Section 2.10, "Error Handling" for more information about error handling.
4.3.6 Oracle FTP Adapter Put File Concepts
In the outbound direction, the Oracle FTP Adapter works the same as the Write File
operations of the Oracle File Adapter. The Oracle FTP Adapter receives messages from
a BPEL process or a Mediator service and writes the messages in a file to a file system
(in this case, remote). Because the messages must be written to a remote system, the
Adapter Configuration Wizard prompts you to connect to the FTP server with the
adapter instance JNDI name, as shown in Figure 4–33.
After logging in, you select the Put File (write) operation and the type of file to deliver.
Figure 4–36 shows this selection.

Figure 4–36 Selecting the Put File Operation
From this point onwards, pages of the Adapter Configuration Wizard for the Put File
operation are the same as those for the Write File operation of the Oracle File Adapter.
Table 4–9 lists the pages that display and provide references to sections that describe
their functionality.
After the completion of the Adapter Configuration Wizard, configuration files are
created in the Applications section of Oracle JDeveloper.
4.3.7 Oracle FTP Adapter Synchronous Get File Concepts
In the outbound direction, the Oracle FTP Adapter works the same way as the
Synchronous Read File operations of the Oracle File Adapter in that it polls and gets
files from a file system and reads the current contents of the file. The major difference
is that the Oracle FTP Adapter is used for remote file exchanges. Because of this, the
Adapter Configuration Wizard asks for connection information to an FTP server to be
used later. For reading a file synchronously, you select Synchronous Get File operation,
Table 4–9 Adapter Configuration Wizard Pages for Put File Operation
Page See Section...
File Configuration (Figure 4–22) Section 4.3.2.2, "Outbound File Directory Creation"
Messages (Figure 4–27) Section 4.3.2.3, "Native Data Translation"

Figure 4–37 Selecting the Synchronous Get File Operation
4.3.8 Oracle FTP Adapter File Listing Concepts
The Oracle FTP Adapter file listing concepts are similar to the Oracle File Adapter file
listing concepts discussed in Section 4.3.4, "Oracle File Adapter File Listing Concepts."
The Oracle FTP Adapter polls for files in a target directory and lists files from the
target directory to specified FTP locations. The contents of the files are not read. This
feature of the Oracle FTP Adapter lets you use an invoke activity to retrieve a list of
files from a target directory. This list of files is returned as an XML document and
contains information such as file name, directory name, file size, and last modified
time.
You use the Adapter Configuration Wizard to configure the Oracle FTP Adapter for
use with a BPEL process or a Mediator service. This creates an outbound WSDL and
JCA file pair.
For listing files, you must select the List Files operation from the Operation Type
page of the Adapter Configuration Wizard. In the File Directories page of the Adapter
Configuration Wizard, you must specify information about the directory to use for
reading file names for the list operation. You can choose to list files recursively within
directories. The File Filtering page of the Adapter Configuration Wizard enables you
to specify details of the files to retrieve or ignore.
The Oracle FTP Adapter acts as a listener and polls the specified directory on a local or
remote file system and looks for files that match specified naming criteria.
Note: The file creation time property, creationTime, is not
supported for FTP because the standard Java APIs do not provide a
mechanism to retrieve the creation time. The value of the
creationTime property is always displayed as 0.
The creationTime property is supported for SFTP only.

Configuring Oracle File and FTP Adapters
4.4 Configuring Oracle File and FTP Adapters
Various configuration tasks for Oracle File and FTP Adapters are discussed in the
following sections:
■ Section 4.4.1, "Configuring Oracle File and FTP Adapters for High Availability"
■ Section 4.4.2, "Using Secure FTP with the Oracle FTP Adapter"
■ Section 4.4.3, "Using SFTP with Oracle FTP Adapter"
■ Section 4.4.4, "Configuring Oracle FTP Adapter for HTTP Proxy"
4.4.1 Configuring Oracle File and FTP Adapters for High Availability
The requirements and procedure to configure the Oracle File and FTP Adapters for
high availability for an active-active topology are discussed in the following sections:
■ Section 4.4.1.1, "Prerequisites for High Availability"
■ Section 4.4.1.2, "High Availability in Inbound Operations"
■ Section 4.4.1.3, "High Availability in Outbound Operations"
4.4.1.1 Prerequisites for High Availability
Before you configure the Oracle File or FTP Adapter for high availability, you must
ensure that the following prerequisites are met:
■ Clustered processes must use the same physical directory.
■ Connection-factories must specify the same shared directory as the control
directory, and their names must match. For example, if the deployment descriptor
for one connection factory has /shared/control_dir as the value for
controlDir, then the other deployment descriptor must also have the same
value.
■ Fault-policies and fault-bindings must be created for remote faults to ensure that
the adapter acts correctly. For more information on fault-policies and
fault-bindings, see Section 2.10, "Error Handling."
■ The MaxRaiseSize property must be set in the inbound JCA file. For more
information on the MaxRaiseSize property, see Table A–1, " Properties for Oracle
File and FTP Adapters".
Note: For large payloads, you must increase the transaction time-out
for the SOADataSource by adding the following:
<xa-set-transaction-timeout>true</xa-set-transaction-timeout>
<xa-transaction-timeout>1000</xa-transaction-timeout>
Note: For Windows platforms, you must ensure that the input and
output directories are canonicalized. For example, you must use
C:bpelinput instead of c:bpelinput. Note the use of
capitalized drive letter C: instead of c:.

4.4.1.2 High Availability in Inbound Operations
The Oracle File and FTP Adapters must ensure that only one node processes a
particular file in a distributed topology. You can use the database table as a coordinator
to ensure that Oracle File and FTP Adapters are highly available for inbound
operations.
Using Database Table as a Coordinator
You must use the following procedure to make an inbound Oracle File or FTP Adapter
service highly available by using database table as a coordinator:
1. Create Database Tables
You are not required to perform this step because the database schemas are
pre-created as a part of soainfra.
2. Modify Deployment Descriptor for Oracle File Adapter
Modify Oracle File Adapter deployment descriptor for the connection-instance
corresponding to eis/HAFileAdapter from the Oracle WebLogic Server
console:
a. Log in to your Oracle WebLogic Server console. To access the console, navigate
to http://servername:portnumber/console.
b. Click Deployments in the left pane for Domain Structure.
c. Click FileAdapter under Summary of Deployments on the right pane.
d. Click the Configuration tab.
e. Click the Outbound Connection Pools tab, and expand
javax.resource.cci.ConnectionFactory to see the configured connection
factories, as shown in Figure 4–38:
Note: You must increase global transaction timeouts if you use
database as a coordinator.

Figure 4–38 Oracle WebLogic Server Console - Settings for FileAdapter Page
f. Click eis/HAFileAdapter. The Outbound Connection Properties for the
connection factory corresponding to high availability is displayed.
g. Update the connection factory properties as shown in Figure 4–39.
Figure 4–39 Oracle WebLogic Server Console - Settings for
javax.resource.cci.ConnectionFactory Page
The new parameters in connection factory for Oracle File and FTP Adapters
are as follows:

controlDir - Set it to the directory structure where you want the control files
to be stored. You must set it to a shared location if multiple WebLogic Server
instances run in a cluster.
inboundDataSource - Set the value to jdbc/SOADataSource. This is the
data source, where the schemas corresponding to high availability are
pre-created. The pre-created schema file can be found under $BEA_
HOME/AS11gR1SOA/rcu/integration/soainfra/sql/adapter/creat
eschema_adapter_oracle.sql. If you want to create the schemas
elsewhere, use this script. You must set the inboundDataSource property
accordingly if you choose a different schema.
h. Configure BPEL Process or Mediator Scenario to use the connection factory as
<connection-factory location="eis/HAFileAdapter"
UIincludeWildcard="*.txt" adapterRef=""/>
<endpoint-activation portType="Read_ptt" operation="Read">
<activation-spec
className="oracle.tip.adapter.file.inbound.FileActivationSpec"../>
<property../>
<property../>
</activation-spec>
</adapter-config>
4.4.1.3 High Availability in Outbound Operations
The Oracle File and FTP Adapters must ensure that if multiple references write to the
same directory, then these do not overwrite each other. The following locking
capabilities can be used to make Oracle File and FTP Adapters highly available for
outbound operations:
■ Database mutex
■ User-defined mutex
Using a Database Mutex
You must use the following procedure to make an outbound Oracle File or FTP
Adapter service highly available by using database table as a coordinator:
1. Create Database Tables
You are not required to perform this step as the database schemas are precreated
as a part of soainfra.
2. Modify Deployment Descriptor for Oracle File Adapter
Note: The location attribute is set to eis/HAFileAdapter for the
connection factory.
Note: You must increase global transaction timeouts if you use the
database as a coordinator.

Modify Oracle File Adapter deployment descriptor for the connection-instance
corresponding to eis/HAFileAdapter from the Oracle WebLogic Server
console:
a. Log in to your Oracle WebLogic Server console. To access the console, navigate
to http://servername:portnumber/console.
b. Click Deployments in the left pane for Domain Structure.
c. Click FileAdapter under Summary of Deployments on the right pane.
d. Click the Configuration tab.
e. Click the Outbound Connection Pools tab, and expand
javax.resource.cci.ConnectionFactory to see the configured connection
factories, as shown in Figure 4–38.
f. Click eis/HAFileAdapter. The Outbound Connection Properties page is
displayed with the connection factory corresponding to high availability.
g. Update the connection factory properties as shown in Figure 4–40.
Figure 4–40 Oracle WebLogic Server Console - Settings for
javax.resource.cci.Connectionfactory Page
The new parameters in connection factory for Oracle File and FTP Adapters
are as follows:
controlDir - Set it to the directory structure where you want the control files
to be stored. You must set it to a shared location if multiple WebLogic Server
instances run in a cluster.
inboundDataSource - Set the value to jdbc/SOADataSource. This is the
data source, where the schemas corresponding to high availability are
pre-reated. The precreated schemas can be found under $BEA_
HOME/AS11gR1SOA/rcu/integration/soainfra/sql/adapter/creat
eschema_adapter_oracle.sql. If you want to create the schemas
elsewhere, then use this script. You must set the inboundDataSource property
accordingly if you choose a different schema.

outboundDataSource - Set the value to jdbc/SOADataSource. This is the
data source where the schemas corresponding to high availability are
precreated. The precreated schemas can be found under $BEA_
HOME/AS11gR1SOA/rcu/integration/soainfra/sql/adapter/createschema_
adapter_oracle.sql. If you want to create the schemas elsewhere, then use this
script. You must set the outboundDataSource property if you choose to do so.
outboundLockTypeForWrite - Set the value to oracle if you are using
Oracle Database. By default the Oracle File and FTP Adapters use an
in-memory mutex to lock outbound write operations. You must choose from
the following values for synchronizing write operations:
memory - The Oracle File and FTP Adapters use an in-memory mutex to
synchronize access to the file system.
oracle - The adapter uses the Oracle Database sequence.
db - The adapter uses a precreated database table (FILEADAPTER_MUTEX) as
the locking mechanism. You must use this option only if you are using a
schema other than the Oracle Database schema.
user-defined - The adapter uses a user-defined mutex. To configure the
user-defined mutex, you must implement the mutex interface
"oracle.tip.adapter.file.Mutex" and then configure a new
binding-property with the name "oracle.tip.adapter.file.mutex"
and value as the fully qualified class name for the mutex for the outbound
reference.
h. Configure BPEL Process or Mediator Scenario to use the connection factory as
<adapter-config name="FlatStructureOut" adapter="File Adapter"
<connection-factory location="eis/HAFileAdapter" adapterRef=""/>
<endpoint-interaction portType="Write_ptt" operation="Write">
<interaction-spec
className="oracle.tip.adapter.file.outbound.FileInteractionSpec">
<property../>
<property../>
</interaction-spec>
</adapter-config>
4.4.2 Using Secure FTP with the Oracle FTP Adapter
The Oracle FTP Adapter supports the use of the secure FTP feature on Solaris and
Linux. This section provides an overview of secure FTP functionality and describes
how to install and configure this feature.
This section includes the following tasks:
■ Secure FTP Overview
■ Installing and Configuring OpenSSL
■ Installing and Configuring vsftpd
■ Creating an Oracle Wallet
Note: The location attribute is set to eis/HAFileAdapter for the
connection factory.

■ Setting Up the Oracle FTP Adapter
4.4.2.1 Secure FTP Overview
In environments in which sensitive data is transferred to remote servers (for example,
sending credit card information to HTTP servers), the issue of security is very
important. Security in these cases primarily refers to two requirements:
■ Trust in the remote server with which you are exchanging data
■ Protection from third parties trying to intercept the data
Secure socket layer (SSL) certificates and encryption focus on satisfying these two
security requirements. When SSL is used for FTP, the resulting security mechanism is
known as FTPS (or FTP over SSL).
To gain the trust of clients in SSL environments, servers obtain certificates (typically,
X.509 certificates) from recognized certificate authorities. When you set up the FTP
server vsftpd in Section 4.4.2.3, "Installing and Configuring vsftpd", you use openSSL
to create a certificate for the server. Every client trusts a few parties, to begin with. If
the server is one of these trusted parties, or if the server's certificate was issued by one
of these parties, then you have established trust, even indirectly. For example, if the
server's certificate was issued by authority A, which has a certificate issued by
authority B, and the client trusts B, that is good enough. For the setup shown in
Figure 4–41, the server's certificate is directly imported into the client's certificate store
(or Oracle Wallet) as a trusted certificate.
Figure 4–41 Establishing Trust
You make the data being transferred immune to spying by encrypting it before
sending it and decrypting it after receiving it. Symmetric encryption (using the same
key to encrypt and decrypt data) is much faster for large amounts of data than the
public key and private key approach. Symmetric encryption is the approach used by
FTPS. However, before the client and server can use the same key to encrypt and
decrypt data, they must agree on a common key. This client typically does this by
performing the following tasks:
■ Generating a session key (to be used to encrypt and decrypt data)
Note: The Oracle FTP Adapter supports the secure FTP feature on
Solaris and Linux.
Trusted Store
3
At runtime, client
gets server
certificate
Certificate
4
Client checks for
server certificate
in its trusted store Server generates
certificate
1
Certificate
2
Client imports server
certificate in its
trusted store
Certificate

■ Encrypting this session key using the server's public key that is part of the server's
certificate
■ Sending the key to the server
The server decrypts this session key by using its private key and subsequently uses it
to encrypt file data before sending it to the client.
The remaining subsections describe how to install and configure secure FTP.
4.4.2.2 Installing and Configuring OpenSSL
OpenSSL is an open source implementation of the SSL protocol. OpenSSL implements
basic cryptographic functions and provides utility functions. Install and configure
OpenSSL on the Solaris or Linux host to be used as the FTP server.
1. Go to the following URL:
http://www.openssl.org/source
2. Locate openssl-0.9.7g.tar.gz in the list of available files. For example:
3132217 Apr 11 17:21:51 2005 openssl-0.9.7g.tar.gz (MD5) (PGP sign)
3. Download the following files:
■ openssl-0.9.7g.tar.gz
■ openssl-0.9.7g.tar.gz.md5 (under the MD5 link)
■ openssl-0.9.7g.tar.gz.asc (under the PGP sign link
4. Unzip the following file using gunzip.
gunzip openssl-0.9.7g.tar.gz
5. Untar the following file:
tar xvf openssl-0.9.7g.tar
6. Change directories to the following location:
cd openssl-0.9.7g
7. Run the following command:
./config --prefix=/usr --openssldir=/usr/local/openssl
8. Change to the Bourne shell (if you are not using it):
sh
9. Configure and export the PATH variable:
PATH=${PATH}:/usr/ccs/bin; export PATH
make
11. Exit the Bourne shell:
exit
make test

13. Log in as the super user:
msu
14. Enter the password when prompted.
make install
4.4.2.3 Installing and Configuring vsftpd
The vsftpd server is a secure and fast FTP server for UNIX systems. Install and
configure vsftpd on the Solaris or Linux host to be used as the FTP server.
1. Go to the following location:
ftp://vsftpd.beasts.org/users/cevans/
2. Download vsftpd-2.0.5 (You need the tar and signature file (.asc file)). For
example:
[BINARY] vsftpd-2.0.5.tar.gz. . . . . . . . . . . [Mar 19 21:26] 149K
[FILE] vsftpd-2.0.5.tar.gz.asc. . . . . . . . . [Mar 19 21:26] 189B
3. Unzip the following file using gunzip.
gunzip vsftpd-2.0.5.tar.gz
4. Unzip the tar file:
tar xvf vsftpd-2.0.5.tar
5. Change directories to the following location:
cd vsftpd-2.0.5
6. Make the following change in the builddefs.h file:
#undef VSF_BUILD_SSL
to
#define VSF_BUILD_SSL
7. Log in as the super user:
msu
8. Enter the password when prompted.
9. Create a file named vsftpd.conf with the following settings in the /etc
directory:
# Standalone mode
listen=YES
max_clients=200
max_per_ip=4
# Access rights
anonymous_enable=YES
#chroot_local_user=YES
#userlist_enable=YES
ftp_username=ftp
local_enable=YES

write_enable=YES
anon_upload_enable=YES
anon_mkdir_write_enable=YES
anon_other_write_enable=YES
chown_uploads=YES
chown_username=ftp
# Security
anon_world_readable_only=NO
allow_anon_ssl=YES
ssl_enable=YES
connect_from_port_20=YES
hide_ids=YES
pasv_min_port=50000
pasv_max_port=60000
# Features
ftpd_banner="Welcome to the FTP Service"
xferlog_enable=YES
ls_recurse_enable=NO
ascii_download_enable=NO
async_abor_enable=YES
# Performance
one_process_model=NO
idle_session_timeout=120
data_connection_timeout=300
accept_timeout=60
connect_timeout=60
anon_max_rate=50000
10. Run the following commands:
mkdir /var/ftp
useradd -d /var/ftp ftp
chown root /var/ftp
chmod og-w /var/ftp
mkdir /usr/share/empty
mkdir /usr/share/ssl
mkdir /usr/share/ssl/certs
openssl req -x509 -nodes -newkey rsa:1024 -keyout
/usr/share/ssl/certs/vsftpd.pem -out /usr/share/ssl/certs/vsftpd.pem
12. Run the vsftpd daemon from the vsftpd-2.0.5 directory:
./vsftpd
4.4.2.4 Creating an Oracle Wallet
Oracle Wallet Manager is an application for managing and editing security credentials
in Oracle wallets. A wallet is a password-protected container that stores authentication
and signing credentials, including private keys, certificates, and trusted certificates, all
of which are used by SSL for strong authentication.
Note: Copies of the vsftpd.conf file appear in several locations in
the vsftpd-2.0.5 directory structure. If you use one of those files to
create the vsftpd.conf file in the /etc directory, then ensure that it
only includes the parameters and settings described in Step 9.

1. Create a new wallet in Oracle Wallet Manager.
2. Import vsftpd.pem from Step 11 of Section 4.4.2.3, "Installing and Configuring
vsftpd" as a trusted certificate in this wallet.
3. Save this wallet in PKCS # 12 (.p12) format.
See Oracle Fusion Middleware Administrator's Guide for details about using Oracle Wallet
Manager.
4.4.2.5 Setting Up the Oracle FTP Adapter
Perform the following tasks to set up the Oracle FTP Adapter:
1. On your Solaris or Linux host, run the following commands:
mkdir /var/ftp/inDir
mkdir /var/ftp/outDir
chmod 777 /var/ftp/inDir /var/ftp/outDir
2. Specify the FTP connection parameters in the Oracle FTP Adapter deployment
descriptor from the Oracle WebLogic Server console.
You have now installed and configured secure FTP and are ready to use this
feature with the Oracle FTP Adapter.
4.4.3 Using SFTP with Oracle FTP Adapter
SSH file transfer protocol (SFTP) is a network protocol that enables secure file transfer
over a network. Oracle FTP Adapter supports the use of the SFTP feature on Windows
and Linux. This section provides an overview of the SFTP functionality and describes
how to install and configure this feature.
This section includes the following tasks:
Where... Is...
useFtps Set to True. This setting is required to use FTP over SSL. The default is
False.
walletLocation The location of the wallet created in Section 4.4.2.4, "Creating an Oracle
Wallet."
walletPassword The password of the wallet.
channelMask The type of channel: control channel or data channel. Possible values are
both, control, data, or none. The default is both.
securePort The port for FTP over SSL. The default is 990.
keyStoreProvid
erName
The keystore provider class. The default is
oracle.security.pki.OraclePKIProvider.
keystoreType The keystore type. The default is PKCS12.
keystoreAlgori
thm
The keystore algorithm. The default is OracleX509.
enableCipherSu
its
List of comma separated cipher suites. The default is blank, in which case
the default list of cipher suites are used. For most cases, you are not
required to change this.
pkiProvider The PKI provider name. The default is OraclePKI.
jsseProvider The JSSE provider name. The default is OracleJSSE.

■ SFTP Overview
■ Install and Configure OpenSSH for Windows
■ Set Up Oracle FTP Adapter for SFTP
4.4.3.1 SFTP Overview
FTP is the network protocol that enables clients to securely transfer files over the
underlying SSH transport. SFTP is not similar to FTP over SSH or File Transfer
Protocol (FTP). Figure 4–42 displays the communication process between an SSH client
and an SSH server. SFTP is supported in Windows and Linux.
Figure 4–42 SFTP Communication
SFTP has the following features:
■ Encryption
■ Authentication
■ Integrity
■ Data Compression
4.4.3.1.1 Encryption The SSH protocol uses public key cryptography for encryption.
This section explains how data is encrypted:
1. The SSH subsystem uses symmetric key ciphers such as Data Encryption Standard
(DES) or Blowfish to generate a session key. The SSH protocol currently uses the
Diffie-Hellman Key Exchange Algorithm to derive the symmetric key for the
session.
2. The data is encrypted using the session key.
3. The session key is encrypted by using the recipient's public key. Because the
recipient already has the private key, it can decrypt the message by using its
preferred PKI algorithm such as Rivest-Shamir-Adleman (RSA) or Digital
Signature Algorithm (DSA).
4.4.3.1.2 Authentication The SSH protocol inherently supports password authentication
by encrypting passwords or session keys as they are transferred over the network. In
addition, the SSH protocol uses a mechanism known as 'known hosts' to prevent
threats such as IP spoofing. When this mechanism is used, both the client and the
server have to prove their identity to each other before any kind of communication
exchange.
4.4.3.1.3 Integrity The SSH protocol uses widely trusted bulk hashing algorithms such
as Message Digest Algorithm 5 (MD5) or Secure Hash Algorithm (SHA-1) to prevent
insertion attacks. Implementation of data integrity checksum by using the algorithms
mentioned in Section 4.4.3.1.1, "Encryption" prevents deliberate tampering of data
during transmission.
SSH Client SSH Server
Integrity
Encryption
Authentication

4.4.3.1.4 Data Compression The SSH protocol supports zlib, an open-source
cross-platform algorithm for data compression. SSH uses zlib to compress in-flight
data to reduce network bandwidth.
4.4.3.2 Install and Configure OpenSSH for Windows
OpenSSH for Windows is the free implementation of the SSH protocol on Windows.
Perform the following steps to install and configure OpenSSH on Windows XP:
1. Log in as a user with Administrator privileges.
2. Download setup.exe from the following location:
http://www.cygwin.com
3. Run setup.exe. The Cygwin Net Release Setup window is displayed.
4. Click Next. The Choose Installation type window is displayed.
5. Select Install from Internet as the download source and click Next. The Choose
Installation Directory window is displayed.
6. Leave the root directory as C:cygwin. Also, keep the default options for the
Install For and the Default Text File Type fields.
7. Click Next. The Select Local Package Directory window is displayed.
8. Click Browse and select C:cygwin as the local package directory.
9. Click Next. The Select Connection Type window is displayed.
10. Select a setting for Internet connection and click Next. The Choose Download
Site(s) window is displayed.
11. Select a site from the Available Download Sites list and click Next. The Select
Packages window is displayed.
12. Click View to see the complete list of packages available for installation.
13. Select openssh if it is not the default value.
14. Select the Binaries box for openssh.
15. Click Next to start the installation.
16. On Windows XP desktop, right -click My Computer and select Properties.
17. Click the Advanced tab and click Environment Variables.
18. Click New and enter CYGWIN in the Variable Name field and ntsec in the
Variable Value field.
19. Add C:cygwinbin to the system path.
20. Open the cygwin window.
21. Type ssh-host-config.
22. You are prompted with the following questions:
a. Shall privilege separation be used? (yes/no)
Enter yes.
b. Shall this script create a local user 'sshd' on this
machine?
Enter yes.

c. Do you want to install sshd as service?
(Say "no" if it's already installed as service) (yes/no)
Enter yes.
d. Which value should the environment variable CYGWIN have
when sshd starts? It's recommended to set at least "ntsec"
to be able to change user context without password.
Default is "binmode ntsec tty".
Enter ntsec.
23. Type net start sshd to start the sshd service.
24. Run the following command in the cygwin window to replicate the Windows local
user accounts to cygwin:
mkpasswd --local > /etc/passwd
mkgroup --local > /etc/group
25. To test the setup, type ssh localhost in the cygwin window.
4.4.3.3 Set Up Oracle FTP Adapter for SFTP
To use the SFTP functionality, you must modify the deployment descriptor for Oracle
FTP Adapter.
Table 4–10 lists the properties for which you must specify a value in the deployment
descriptor. The values of these properties depend on the type of authentication and the
location of OpenSSH.
Table 4–10 SFTP Properties
Property Description
useSftp Specify true.
Mandatory: Yes
Default value: false
authenticationType Specify PASSWORD for password-based authentication or
PUBLICKEY for public key authentication.
For password-based authentication, the user name and
password specified in the weblogic-ra.xml file are used.
Ensure that there is a Windows user with the same name
and password as specified in the weblogic-ra.xml file. In
addition, the user should have administrative privileges.
For public key authentication, the privateKeyFile
parameter must be set to the location of the private key file.
Mandatory: Yes
preferredKey
ExchangeAlgorithm
Specify diffie-hellman-group1-sha1 or
diffie-hellman-group-exchange-sha1.
This is an optional parameter where the user can select the
default key exchange protocol for negotiating the session
key for encrypting the message.
Mandatory: No
Default value: diffie-hellman-group1-sha1

4.4.3.3.1 Configuring Oracle FTP Adapter for Password Authentication
preferred
CompressionAlgorithm
Specify none or zlib.
This parameter enables the user to choose whether in-flight
data should be compressed or not.
Mandatory: No
preferred
DataIntegrityAlgorithm
Specify hmac-md5 or hmac-sha1.
This parameter enables the user to select the bulk-hashing
algorithm for data integrity checks.
Mandatory: No
Default value: hmac-md5
preferredPKIAlgorithm Specify ssh-rsa or ssh-dsa.
This parameter enables the user to configure the asymmetric
cipher for the communication.
Mandatory: No
Default value: ssh-rsa
privateKeyFile Specify the path to the private key file. This is required if the
authenticationType parameter is set to PUBLICKEY.
Mandatory: No
preferredCipherSuite Specify a cipher from the following list:
■ twofish192-cbc
■ cast128-cbc
■ twofish256-cbc
■ aes128-cbc
■ twofish128-cbc
■ 3des-cbc
■ blowfish-cbc
■ aes256-cbc
■ aes192-cbc
Mandatory: No
Default value: blowfish-cbc
transportProvider Specify socket or HTTP.
Specify socket if the SSH server is inside a firewall. Specify
HTTP if the SSH server is outside the firewall or a server is
exposed through an HTTP server.
If you select HTTP, then you must provide values for the
following parameters:
■ proxyHost
■ proxyPort
■ proxyUser
■ proxyPassword
■ useProxy
Mandatory: Yes
Table 4–10 (Cont.) SFTP Properties

To set up the Oracle FTP Adapter for password authentication, the deployment
descriptor for Oracle FTP Adapter must specify the values of the properties listed in
Table 4–10. Ensure that the authenticationType property is set to password.
Specify the following properties and values listed in Table 4–11:
4.4.3.3.2 Configuring Oracle FTP Adapter for Public Key Authentication
For public key authentication, you must first configure OpenSSH and then set up the
Oracle FTP Adapter. The Oracle FTP Adapter setup depends on whether the OpenSSH
is running inside a firewall or outside a firewall. If OpenSSH is running inside the
firewall, then see the following sections:
■ Section 4.4.3.3.3, "Configuring OpenSSH for Public-Key Authentication"
■ Section 4.4.3.3.4, "Configuring Oracle FTP Adapter for Public Key Authentication
with OpenSSH Running Inside a Firewall"
If OpenSSH is running outside the firewall, then see the following sections:
■ Section 4.4.3.3.3, "Configuring OpenSSH for Public-Key Authentication"
■ Section 4.4.3.3.5, "Configuring Oracle FTP Adapter for Public Key Authentication
with OpenSSH Running Outside a Firewall"
4.4.3.3.3 Configuring OpenSSH for Public-Key Authentication
Perform the following steps:
1. Go to the C:cygwinetc directory. If required, configure the sshd_config file
to force public key authentication. For more information, see openssh help or
manual.
2. Go to the C:cygwinbin directory.
3. Run the following command to generate the key pair:
ssh-keygen -t rsa
4. Enter /etc/id_rsa when prompted for the file in which the key should be
saved.
5. Enter the passphrase.
Table 4–11 Sample SFTP Properties and Values
Property Value
useSftp true
authenticationType PASSWORD
preferredKey
ExchangeAlgorithm
diffie-hellman-group1-sha1
preferred
none
preferred
hmac-md5
preferredPKIAlgorithm ssh-rsa
privateKeyFile -
preferredCipherSuite blowfish-cbc
transportProvider socket

6. Enter the passphrase again.
7. Go to the /etc directory and verify that both the public key file (id_rsa.pub)
and the private key file (id_rsa) are generated.
8. Run the following command to create a copy of the public key file:
cp id_rsa.pub authorized_keys
9. Create a copy of the private key file in a secured location such as
C:my-secured-folder. The Oracle FTP Adapter configuration refers to this
private key file.
10. Restart the OpenSSH server by running the following commands:
net stop sshd
net start sshd
4.4.3.3.4 Configuring Oracle FTP Adapter for Public Key Authentication with OpenSSH Running
Inside a Firewall
To set up the Oracle FTP Adapter for public key authentication, you must specify the
values of the parameters listed in Table 4–10 in the deployment descriptor. Ensure that
the authenticationType parameter is set to publickey and the
transportProvider parameter is set to socket. The privateKeyFile
parameters should contain the location of the private key file.
A sample list of public key authentication properties and their values is shown in
Table 4–12.
4.4.3.3.5 Configuring Oracle FTP Adapter for Public Key Authentication with OpenSSH Running
Outside a Firewall
Perform the following steps to set up the Oracle FTP Adapter for public key
authentication when OpenSSH is running outside the firewall:
1. In the deployment descriptor for Oracle FTP Adapter, you must specify the values
of the properties listed in Table 4–10 in the deployment descriptor for Oracle FTP
Adapter. Ensure that the authenticationType property is set to publickey
Property Value
useSftp true
authenticationType publickey
preferredKey
ExchangeAlgorithm
preferred
none
preferred
hmac-md5
privateKeyFile C:my-secured-folderid_rsa
transportProvider socket

and the transportProvider property is set to HTTP. The privateKeyFile
property contains the location of the private key file.
2. In the deployment descriptor for Oracle FTP Adapter, also specify the following
proxy-related properties:
■ proxyHost: The name of the proxy host.
■ proxyPort: The port number of the proxy.
■ proxyUsername: The user name for the proxy.
■ proxyPassword: The password for the proxy.
■ useProxy: Specify true to use proxy.
A sample list with public key authentication properties and proxy properties is shown
in Table 4–13.
4.4.4 Configuring Oracle FTP Adapter for HTTP Proxy
The Oracle FTP Adapter provides proxy support for HTTP proxy only. The HTTP
proxy support is available in the following two modes, plain FTP mode and SFTP
mode. This section explains how to configure the Oracle FTP Adapter for running in
plain FTP mode and SFTP mode. It contains following sections:
■ Section 4.4.4.1, "Configuring for Plain FTP Mode"
■ Section 4.4.4.2, "Configuring for SFTP Mode"
Property Value
proxyHost proxy.host.com
proxyPort 80
proxyUsername anonymous
proxyPassword tiger@scott.com
useProxy true
useSftp true
authenticationType publickey
preferredKey
ExchangeAlgorithm
preferred
none
preferred
hmac-md5
privateKeyFile C:my-secured-folderid_rsa
transportProvider HTTP

4.4.4.1 Configuring for Plain FTP Mode
For running the Oracle FTP Adapter in plain FTP mode, you must specify the value of
certain parameters in the Oracle FTP Adapter deployment descriptor. Table 4–14 lists
the properties that you must modify.
A sample list of Oracle FTP Adapter descriptor properties and their values is shown in
Table 4–15.
4.4.4.1.1 Proxy Definition File You can specify all proxy-specific information in a proxy
definition file and configure the adapter to use this file with the
proxyDefinitionFile property of the Oracle FTP Adapter deployment descriptor
file. A proxy definition file is written in XML format and is based on XML schema. The
Table 4–14 Plain FTP Mode Properties
host The remote FTP server name.
port The FTP control port number.
username The FTP user name.
password The FTP password.
proxyHost The proxy host name.
proxyPort The proxy port number.
proxyUsername The proxy user name.
proxyPassword The proxy password.
proxyType The proxy type. Only HTTP proxy type is supported.
proxyDefinitionFile The absolute path of the proxy definition file.
This parameter is not mandatary.
See Section 4.4.4.1.1, "Proxy Definition File" for more
information.
useProxy Specify true to use proxy.
Table 4–15 Sample Plain FTP Mode Properties and Values
Property Value
host my.host.com
port 21
username user
password password
proxyPort 80
proxyPassword tiger@scott.com
proxyType http
proxyDefinitionFile c:proxydefinitions.xml
useProxy true

XML schema for the proxy definition file is shown in Example 4–1. Your proxy
definition file must be based on this XML schema.
Example 4–1 Proxy Definition File XML Schema
<?xml version = "1.0" encoding = "UTF-8"?>
<schema targetNamespace = "http://ns.oracle.com/ip/af/ftp/proxy" xmlns =
"http://www.w3.org/2001/XMLSchema"
xmlns:proxy="http://ns.oracle.com/ip/af/ftp/proxy">
<element name="ProxyDefinitions" type="proxy:ProxyDefinitionsType"/>
<complexType name="ProxyDefinitionsType">
<sequence>
<element name="Proxy" type="proxy:ProxyDefinition"
minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>
<complexType name="ProxyDefinition">
<sequence>
<element name="Step" type="proxy:StepType"
minOccurs="1" maxOccurs="unbounded"/>
</sequence>
<attribute name="key" type="ID" use="required"/>
<attribute name="description" type="string"
use="required"/>
<attribute name="type" type="proxy:Protocol"
use="optional"/>
</complexType>
<complexType name="StepType">
<simpleContent>
<extension base="string">
<attribute name="command" type="string" use="required"/>
<attribute name="args" type="string" use="required"/>
</extension>
</simpleContent>
</complexType>
<simpleType name="Protocol">
<restriction base="string">
<enumeration value="ftp" />
<enumeration value="http" />
</restriction>
</simpleType>
</schema>
A sample proxy definition file, based on the XML schema in Example 4–1, would look
as shown in Example 4–2:
Example 4–2 Proxy Definition File
<?xml version = '1.0' standalone = 'yes'?>
<proxy:ProxyDefinitions xmlns:proxy="http://ns.oracle.com/ip/af/ftp/proxy">
<Proxy key="http" description="http" type="http">
<Step command="USER" args="remote_username" />
<Step command="PASS" args="remote_password" />
</Proxy>
</proxy:ProxyDefinitions>

When you use the file in Example 4–2, the Oracle FTP Adapter sends the following
sequence of commands to log in:
1. USER remote_username
2. PASS remote_password
You can also direct the proxy definition file to pick values from the deployment
descriptor for Oracle FTP Adapter. You can use the following expressions for this:
■ $proxy.user: This corresponds to the value of the proxyUsername parameter
in the Oracle FTP Adapter deployment descriptor.
■ $proxy.pass: This corresponds to the value of the proxyPassword parameter
in the Oracle FTP Adapter deployment descriptor.
■ $remote.user: This corresponds to the value of the username parameter in the
Oracle FTP Adapter deployment descriptor.
■ $remote.pass: This corresponds to the value of the password parameter in the
■ $remote.host: This corresponds to the value of the host parameter in the
■ $remote.port: This corresponds to the value of the port parameter in the
A sample proxy definition file based on the XML schema in Example 4–2 and taking
values from the weblogic-ra.xml file is shown in Example 4–3:
Example 4–3 Proxy Definition File Taking Values from the Deployment Descriptor
<?xml version = '1.0' standalone = 'yes'?>
<proxy:ProxyDefinitions xmlns:proxy="http://ns.oracle.com/ip/af/ftp/proxy">
<Proxy key="http" description="http" type="http">
<Step command="USER" args="$remote.user" />
<Step command="PASS" args="$remote.pass" />
</Proxy>
</proxy:ProxyDefinitions>
4.4.4.2 Configuring for SFTP Mode
For running the Oracle FTP Adapter in SFTP mode, you must specify the value of
certain properties in the Oracle FTP Adapter deployment descriptor. Table 4–16 lists
the properties that you must modify.
Table 4–16 SFTP Mode Properties
host The remote FTP server name.
port The FTP control port number.
username The SFTP user name.
password The SFTP password.
proxyHost The proxy server host name.
proxyPort The proxy port number.
proxyUsername The proxy user name.
proxyPassword The proxy password.

Oracle File and FTP Adapters Use Cases
A sample list of deployment descriptor properties is shown in Table 4–17.
4.5 Oracle File and FTP Adapters Use Cases
This section includes the following Oracle File and FTP Adapters use cases:
■ Section 4.5.1, "Oracle File Adapter XML Debatching"
■ Section 4.5.2, "Flat Structure for BPEL PM"
■ Section 4.5.3, "Flat Structure for Mediator"
■ Section 4.5.4, "Oracle File Adapter Scalable DOM"
■ Section 4.5.5, "Oracle File Adapter ChunkedRead"
■ Section 4.5.6, "Oracle File Adapter Read File As Attachments"
■ Section 4.5.7, "Oracle File Adapter File Listing"
■ Section 4.5.8, "Oracle File Adapter Complex Structure"
■ Section 4.5.9, "Oracle FTP Adapter Debatching"
■ Section 4.5.10, "Oracle FTP Adapter Dynamic Synchronous Read"
■ Section 4.5.11, "Copying, Moving, and Deleting Files"
useSftp Specify true for SFTP mode. This value is required to use the SFTP
feature.
authenticationType Specify either PASSWORD or PUBLICKEY.PASSWORD
See Section 4.4.3.3, "Set Up Oracle FTP Adapter for SFTP"
transportProvider Specify http as value. Only HTTP transport provider is supported.
Table 4–17 Sample SFTP Mode Properties and Values
Property Value
host my.host.com
port 22
username user
password password
proxyPort 80
proxyPassword password
useSFTP true
authenticationType password
transportProvider http
Table 4–16 (Cont.) SFTP Mode Properties

4.5.1 Oracle File Adapter XML Debatching
This is an Oracle File Adapter feature that debatches large XML documents into
smaller individual XML fragments.
In this use case, the Debatching XML process uses the Oracle File Adapter to debatch
an XML file containing a batch of employees occurring in the XML file as repeating
nodes. These nodes are then processed and every individual node is written to
separate output files.
This use case includes the following sections:
■ Section 4.5.1.1, "Prerequisites"
■ Section 4.5.1.2, "Designing the SOA Composite"
■ Section 4.5.1.3, "Creating the Inbound Oracle File Adapter Service"
■ Section 4.5.1.4, "Creating the Outbound File Adapter Service"
■ Section 4.5.1.5, "Wiring Services and Activities"
■ Section 4.5.1.6, "Deploying with Oracle JDeveloper"
■ Section 4.5.1.7, "Monitoring Using Enterprise Manager Console"
4.5.1.1 Prerequisites
To perform debatching, you require the emps.xml file. This file can be copied from
the following location:
http://www.oracle.com/technology/sample_code/products/adapters
4.5.1.2 Designing the SOA Composite
You must create a JDeveloper application to contain the SOA composite. To create an
application and a project for the use case, perform the following:
1. In the Application Navigator of Oracle JDeveloper, click New Application. The
Create Generic Application - Name your application page is displayed.
2. Enter SOA-XMLDebatching in the Application Name field, as shown in
Figure 4–43, and click Next. The Create Generic Application - Name your project
page is displayed.

Figure 4–43 The Generic Create Application - Name your application Page
3. Enter XMLDebatching in the Project Name field.
4. In the Available list under the Project Technologies tab, double-click SOA to move
it to the Selected list, as shown in Figure 4–44.
Figure 4–44 The Create Generic Application - Name your project Page
5. Click Next. The Configure SOA settings dialog appears.
6. Select Composite With BPEL in the Composite Template box, as shown in
Figure 4–45, and click Finish. The Create BPEL Process - BPEL Process page is
displayed.

Figure 4–45 The Create Generic Application - Configure SOA settings Page
7. Enter BPELXMLDebatching in the Name field, select Define Service Later from
the Template box, as shown in Figure 4–46.
Figure 4–46 The Create BPEL Process - BPEL Process Page
8. Click OK. The SOA-XMLDebatching application and the XMLDebatching project
appear in the design area, as shown in Figure 4–47.

Figure 4–47 The Oracle JDeveloper - Composite.xml
9. Copy the employees.xsd file from
(http://www.oracle.com/technology/sample_
code/products/adapters) to the xsd directory in your project.
4.5.1.3 Creating the Inbound Oracle File Adapter Service
Perform the following steps to create an inbound Oracle File Adapter service to read
the file from a local directory:
1. Drag and drop the Oracle File Adapter from the Component Palette to the
Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is
displayed.
2. Click Next. The Service Name page is displayed.
3. Enter XMLDebatchingIn in the Service Name field and, as shown in Figure 4–48.

Figure 4–48 The Adapter Configuration Wizard - Service Name Page
4. Click Next. The Adapter Interface page is displayed.
5. Select Define from operation and schema (specified later), and click Next. The
Operation page is displayed.
6. Select Read File, as shown in Figure 4–49, and click Next. The File Directories page
is displayed.
Figure 4–49 The Adapter Configuration Wizard Operation Page
7. Enter the physical path for the input directory, as shown in Figure 4–50. The File
Filtering page is displayed.

Figure 4–50 The Adapter Configuration Wizard - File Directories Page
8. Enter *.xml in the Include Files With Name Pattern field, select Files Contain
Multiple Messages check box, specify 1 as the value for Publish Messages in
Batches Of box, as shown in Figure 4–51.
Figure 4–51 The Adapter Configuration Wizard File Filtering Page
9. Click Next. The File Polling page is displayed.
10. Click Next. The Messages page is displayed.
11. Click Browse For Schema File that appears at the end of the URL field. The Type
Chooser dialog is displayed.
12. Click Project Schema Files, employees.xsd, and employees, as shown in
Figure 4–52.

Figure 4–52 The Type Chooser Dialog
13. Click OK. The URL field in the Messages page is populated with the
employees.xsd file, as shown in Figure 4–53.
Figure 4–53 The Adapter Configuration Wizard File Messages Page
14. Click Next. The Finish page is displayed.
15. Click Finish. The inbound Oracle File Adapter is now configured and
composite.xml appears, as shown in Figure 4–54.

4.5.1.4 Creating the Outbound File Adapter Service
Perform the following steps to create an outbound file adapter service to write the file
from a local directory to the FTP server:
1. Drag and drop the File Adapter from the Component Palette to the External
References swim lane. The Adapter Configuration Wizard Welcome page is
displayed.
3. Enter XMLOut in the Service Name field.
6. Select Write File, and click Next. The File Configuration page is displayed.
7. Enter the physical path for the output directory and enter emp_%SEQ%.xml in the
File Naming Convention (po_%SEQ%.txt) field, as shown in Figure 4–55.
8. Select Number of Messages Equals option, if not already selected. The default
value is 1.

Figure 4–55 The Adapter Configuration Wizard - File Configuration Page
11. Click Project Schema Files, employees.xsd, and employee, as shown in
Figure 4–56.
employees.xsd file, as shown in Figure 4–53.

14. Click Finish. The outbound Oracle File Adapter is now configured and
4.5.1.5 Wiring Services and Activities
You have to assemble or wire the three components that you have created: Inbound
adapter service, BPEL process, Outbound adapter reference. Perform the following
steps to wire the components:
1. Drag the small triangle in the XMLDebatchingIn in the Exposed Services area to
the drop zone that appears as a green triangle in the BPEL process in the
Components area.
2. Drag the small triangle in the BPEL process in the Components area to the drop
zone that appears as a green triangle in the XMLOut in the External References
area.
The Oracle JDeveloper Composite.xml appears, as shown in Figure 4–58.

3. Click File, Save All.
Add a Receive Activity
4. Double-click BPELXMLDebatching. The BPELXMLDebatching.bpel page is
displayed.
5. Drag and drop a Receive activity from the Component Palette to the design area.
6. Double-click the Receive activity. The Receive dialog is displayed.
7. Enter ReceiveEmployee in the Name field, as shown in Figure 4–59.

Figure 4–59 The Oracle JDeveloper - BPELXMLDebatching.bpel
8. Click Browse Partner Links at the end of the Partner Link field. The Partner Link
9. Select XMLDebatchingIn, as shown in Figure 4–60, and click OK.
Figure 4–60 The Partner Link Chooser Dialog
10. Click the Auto-Create Variable icon to the right of the Variable field in the Receive
dialog, as shown in Figure 4–61. The Create Variable dialog is displayed.

Figure 4–61 The Receive Dialog
11. Select the default variable name and click OK. The Variable field is populated with
the default variable name.
12. Check Create Instance, and click OK. The Oracle JDeveloper
BPELXMLDebatching.bpel page appears, as shown in Figure 4–62.

Add an Invoke Activity
13. Drag and drop an Invoke activity from the Component Palette to the design area.
14. Double-click the Invoke activity. The Invoke dialog is displayed.
15. Enter WriteEmployee in the Name field, as shown in Figure 4–63.
17. Select XMLOut, as shown in Figure 4–64, and click OK.
18. Click the Automatically Create Input Variable icon to the right of the Input
variable field in the Invoke dialog. The Create Variable dialog is displayed.

the default variable name. The Invoke dialog is displayed, as shown in
Figure 4–65.
20. Click OK. The Oracle JDeveloper BPELXMLDebatching.bpel page appears, as
Add a Transform Activity
21. Drag and drop a Transform activity from the Component Palette in between the
22. Double-click the Transform activity. The Transform dialog is displayed.

23. Enter TransformPayload in the Name field, as shown in Figure 4–67.
Figure 4–67 The Transform Dialog
24. Click the Transformation tab. The Transform dialog is displayed, as shown in
Figure 4–68.
Figure 4–68 The Transform Dialog - Transformation Tab
25. Click the Create... icon. The Source Variable dialog is displayed.
26. Select ReceiveEmployee_Read_InputVariable in the Source Variable box, and
select employees in the Source Part box, and then click OK. The Transform dialog
is displayed with the Source and Part selected.
27. Select WriteEmployee_Write_InputVariable in the Target Variable list, select
employee in the Target Part, as shown in Figure 4–69.

Figure 4–69 The Transform Dialog
28. Click the Create Mapping icon. The XSL Editor page is displayed.
29. Drag employees from sources to employee in the target, as shown in Figure 4–70.
The Auto Map Preferences dialog is displayed.
Figure 4–70 The Oracle JDeveloper - Transformation_2.xsl

30. Click OK.
32. Close the XSL Editor page. The BPELXMLDebatching.bpel page is displayed, as
Figure 4–71 The Oracle JDeveloper - XML Debatching Complete
4.5.1.6 Deploying with Oracle JDeveloper
You must deploy the application profile for the SOA project and the application you
created in the preceding steps. To deploy the application profile using Oracle
JDeveloper, perform the following steps:
1. Create an application server connection. For more information, see Section 2.16,
"Creating an Application Server Connection for Oracle JCA Adapters."
2. Deploy the application. For more information, see Section 2.17, "Deploying Oracle
JCA Adapter Applications from Oracle JDeveloper."
4.5.1.7 Monitoring Using Enterprise Manager Console
You can monitor the deployed SOA Composite using the Enterprise Manager Console.
1. Navigate to http://servername:portnumber/em. The composite you
deployed appears in the application navigation tree.
2. Copy the emps.xml file to the input directory and ensure it gets processed. Check
the output directory to ensure that an output file has been created.
3. Click the SOA composite that you deployed. The Dashboard is displayed.
Note your Instance ID in the Recent Instances area.

4. Click the Instances tab. The Instance IDs of the SOA composite are listed.
5. Click the Instance ID that you noted in Step 3. The Flow Trace page is displayed.
6. Click your BPEL process instance. The Audit Trail of the BPEL process instance is
displayed.
7. Expand a payload node to view payload details.
8. Click the Flow tab to view the process flow.
9. Click an activity to display the activity details.
4.5.2 Flat Structure for BPEL PM
This use case demonstrates how a flat structure business process uses the Oracle File
Adapter to process address book entries from a Comma Separated Value (CSV) file.
This is then transformed and written to another file in a Fixed Length format.
■ Section 4.5.2.4, "Creating the Outbound Oracle File Adapter Service"
■ Section 4.5.2.7, "Monitoring Using Oracle Enterprise Manager Console"
To perform the flat structure business process, you require the address-csv.txt
file. This file can be copied from the following location:
2. Enter SOA-FlatStructure in the Application Name field, and click OK. The
Create Generic Application - Name your project page is displayed.
3. Enter FlatStructure in the Project Name.
it to the Selected list.
6. Select Composite With BPEL in the Composite Template box, and click Finish.
The Create BPEL Process - BPEL Process page is displayed.
7. Enter BPELFlatStructure in the Name field, select Define Service Later from
the Template box.

8. Click OK. The SOA-FlatStructure application and the FlatStructure project appear
in the design area, as shown in Figure 4–72.
9. Copy the address-csv.xsd and address-fixedLength.xsd files from
code/products/adapters) to the schema directory in your project.
10. Copy addr1Toaddr2.xsl from
code/products/adapters) into the xsl directory of your project.
1. Drag and drop File Adapter from the Component Palette to the Exposed Services
swim lane. The Adapter Configuration Wizard Welcome page is displayed.
3. Enter FlatStructureIn in the Service Name field.
5. Click Next. The Operation page is displayed.
6. Select Read File, and click Next. The File Directories page is displayed.
7. Enter the physical path for the input directory. Check Archive Processed Files.
8. Enter the physical path for the archive directory for processed files.
9. Click Next. The File Filtering page is displayed.
10. Enter *.txt in the Include Files With Name Pattern field, click Next. The File
Polling page is displayed.

13. Click Project Schema Files, address-csv.xsd, and Root-Element.
address-csv.xsd file.
4.5.2.4 Creating the Outbound Oracle File Adapter Service
Perform the following steps to create an outbound Oracle File Adapter service to write
the file from a local directory to the FTP server:
1. Drag and drop File Adapter from the Component Palette to the External
displayed.
3. Enter FlatStructureOut in the Service Name field.

7. Enter the physical path for the output directory and enter address_%SEQ%.data
in the File Naming Convention(po_%SEQ%.txt) field.
10. Click Project Schema Files, address-fixedLength.xsd, and Root-Element.
address-fixedLength.xsd file.
1. Drag the small triangle in the FlatStructureIn in the Exposed Services area to the
drop zone that appears as a green triangle in the BPEL process in the Components
area.
zone that appears as a green triangle in the FlatStructureOut in the External
References area.

4. Double-click BPELFlatStructure. The BPELFlatStructure.bpel page is displayed.
7. Enter ReceiveCSV in the Name field.
9. Select FlatStructureIn, and click OK.
dialog. The Create Variable dialog is displayed.
BPELFlatStructure.bpel page appears, as shown in Figure 4–76.

Figure 4–76 The Oracle JDeveloper - BPELFlatStructure.bpel
15. Enter InvokeWrite in the Name field.
17. Select FlatStructureOut, and click OK.
20. Click OK. The Oracle JDeveloper BPELFlatStructure.bpel page appears, as shown
in Figure 4–77.

23. Enter TransformPayload in the Name field.
24. Click the Transformation tab. The Transform dialog is displayed.
26. Select ReceiveCSV_Read_InputVariable in the Source Variable box, and select
body in the Source Part box, and then click OK. The Transform dialog is displayed
with the Source and Part selected.
27. Select InvokeWrite_Write_InputVariable in the Target Variable list, select body in
the Target Part.
28. Click the Browse button at the end of the Mapper File field and select
addr1Toaddr2.xsl file from the xsl directory in your project.
29. Click OK.
30. Click File, Save All. The BPELFlatStructure.bpel page is displayed, as shown in
Figure 4–78.

4.5.2.7 Monitoring Using Oracle Enterprise Manager Console
You can monitor the deployed SOA Composite using Enterprise Manager Console.
2. Copy the address-csv.txt file to the input directory and ensure it gets processed.
Check the output directory to ensure that an output file has been created.
displayed.

8. Click the Flow tab to view the process flow. Additionally, click an activity (such as
invoke, receive) to view the details of an activity.
9. Click ReceiveCSV to display the activity details.
4.5.3 Flat Structure for Mediator
In this use case, Mediator receives the customer data from a file system as a text file,
through an inbound Oracle File Adapter service named ReadFile. The ReadFile
adapter service sends the message to a routing service named ReadFile_RS. The
ReadFile_RS sends the message to the outbound adapter service WriteFTP. The
WriteFTP service delivers the message to its associated external application.
■ Section 4.5.3.2, "Creating a Mediator Application and Project"
■ Section 4.5.3.3, "Importing the Schema Definition (.XSD) Files"
■ Section 4.5.3.5, "Creating the Outbound Oracle FTP Adapter Service"
■ Section 4.5.3.6, "Wiring Services"
■ Section 4.5.3.7, "Creating the Routing Rule"
■ Section 4.5.3.9, "Run-Time Task"
This example assumes that you are familiar with basic Mediator constructs, such as
services, routing service, and Oracle JDeveloper environment for creating and
deploying Mediator services.
To define the schema of the messages, you require an address-csv.xsd file. This file
can be copied from the following location:
4.5.3.2 Creating a Mediator Application and Project
To create an application and a project for the use case, follow these steps:
2. Enter FileFTP_RW in the Application Name field and click Next. The Create
Generic Application - Name your project page is displayed.
3. Enter FileRead_FTPWrite in the Project Name field.
4. In the Available list in the Project Technologies tab, double-click SOA to move it to
the Selected list.
5. Click Next. The Create Generic Application - Configure SOA settings page is
displayed.
6. Select Composite With Mediator in the Composite Template box.
7. Click Finish. The Create Mediator - Mediator Component page is displayed.
8. Enter FileRead_RS in the Name field.

9. Select Define Interface Later in the Template list, and then click OK. The
FileFTP_RW application and the FileRead_FTPWrite project appear in the
design area.
4.5.3.3 Importing the Schema Definition (.XSD) Files
Perform the following steps to import the XSD files that define the structure of the
messages:
1. Create a Schema directory and copy the address-csv.xsd file to this directory.
2. In the Application Navigator, select FileRead_FTPWrite.
3. From the File menu, select Import. The Import dialog is displayed.
4. From the Select What You Want to Import list, select Web Source, and then click
OK. The Web Source dialog is displayed.
5. To the right of the Copy From field, click Browse. The Choose Directory dialog is
displayed.
6. Navigate to the Schema directory and click Select. The Web Source dialog with
the directory is displayed.
7. Click OK.
the file from a local directory
1. Drag a File Adapter service from Components Palette to the design area. The
Adapter Configuration Wizard Welcome page is displayed.
3. Enter ReadFile in the Service Name field.
6. Select Read File and click Next. The File Directories page is displayed.
7. Select Physical Path option, and click Browse and select a polling directory.
9. Enter *.txt in the Include Files with Name Pattern field and click Next. The File
11. Click the Browse For Schema File button at the end of the URL field. The Type
12. Select Project Schema Files, address-csv.xsd, and then Root-Element.
13. Click OK.
14. Click Next in the Messages page. The Finish page is displayed.
15. Click Finish. A ReadFile adapter service is created.
4.5.3.5 Creating the Outbound Oracle FTP Adapter Service
Perform the following steps to create an outbound Oracle FTP Adapter service to write
the file to an FTP server:

1. Drag an FTP Adapter service from Components Palette to the design area. The
Adapter Configuration Wizard Welcome page is displayed.
3. Enter WriteFTP in the Service Name field.
FTP Server Connection page is displayed.
6. Specify the JNDI Name of the FTP Server in the FTP Server JNDI Name field and
click Next. The Operation page is displayed.
7. Select Ascii option as File Type.
8. Select Put File option as the Operation Type and click Next. The File
Configuration page is displayed.
9. Specify the directory to which file must be written in the Directory for Outgoing
Files (physical path) field.
10. Specify the naming convention for the output file name in the File Naming
Convention field. For example, po_%SEQ%.txt.
12. Click the Browse For Schema File button at the end of the URL field. The Type
13. Select Project Schema Files, address-csv.xsd, and then Root-Element.
14. Click OK.
15. Click Next in the Messages page. The Finish page is displayed.
16. Click Finish. A WriteFTP adapter service is created.
4.5.3.6 Wiring Services
Oracle File Adapter service, Mediator component, Outbound Oracle FTP Adapter
reference. Perform the following steps to wire the components:
1. Drag the small triangle in the ReadFile in the Exposed Services area to the drop
zone that appears as a green triangle in the Mediator component in the
Components area.
2. Drag the small triangle in the Mediator component in the Components area to the
drop zone that appears as a green triangle in the WriteFTP in the External
References area. The Oracle JDeveloper composite.xml appears as shown in
Figure 4–79.

4.5.3.7 Creating the Routing Rule
Perform the following steps to create a routing service:
1. Double-click the ReadFile_RS routing service. The Read operation is listed in the
Operations pane, as shown in Figure 4–80.

Figure 4–80 The Oracle JDeveloper - ReadFile_RS Routing Service Page
2. Click the + sign to the left of <<Filter Expression>>to expand the routing rule.
3. Click the icon that appears at the end of the Transform Using field. The Request
Transformation Map dialog is displayed, as shown in Figure 4–81.
Figure 4–81 The Request Transformation Map Dialog
4. Select Create New Mapper File and click OK.
A Root-Element_To_Root-Element.xsl tab is added to Oracle JDeveloper. This tab
enables you to graphically create a document transformation file to convert the
structure of the file data to a canonical data structure.
5. Drag and drop the imp1:Address source element to the imp1:Address target
element. The Auto Map Preferences dialog is displayed.
6. From the During Auto Map options, deselect Match Elements Considering their
Ancestor Names.
7. Click OK.
8. From the File menu, click Save.

4.5.3.9 Run-Time Task
At run time, copy a text file to the polling directory. Once the Oracle File Adapter picks
the file, the file is written to the directory that you specified at design time.
4.5.4 Oracle File Adapter Scalable DOM
This use case demonstrates how a scalable DOM process uses the streaming feature to
copy/move huge files from one directory to another.
To perform the streaming large payload process, you require the address-csv.xsd
file. This file can be copied from the following location:
2. Enter SOA-ScalableDOM in the Application Name field, and click Next. The
3. Enter ScalableDOM in the Project Name field.
The SOA-ScalableDOM application and ScalableDOM project appears in the

Application Navigator and the Create BPEL Process - BPEL Process page is
displayed.
7. Enter BPELScalableDOM in the Name field, select Define Service Later from the
Template box.
8. Click OK. The SOA-ScalableDOM application and the ScalableDOM project
appears in the design area.
9. Copy the address-csv.xsd file from
3. Enter ScalableDOMIn in the Service Name field.
6. Select Read File, and check Use File Streaming, and click Next. The File
Directories page is displayed.
7. Enter the physical path for the input directory. The File Filtering page is displayed.
11. Click Project Schema Files, address-csv.xsd, and Root-Element, as shown in
Figure 4–82.

displayed.
3. Enter ScalableDOMOut in the Service Name field.
7. Enter the physical path for the output directory and enter address-csv_
%SEQ%.xml in the File Naming Convention (po_%SEQ%.txt) field.

1. Drag the small triangle in the ScalableDOMIn in the Exposed Services area to the
area.
zone that appears as a green triangle in the ScalableDOMOut in the External
References area.
The Oracle JDeveloper composite.xml appears, as shown in Figure 4–85.

4. Double-click BPELScalableDOM. The BPELScalableDOM.bpel page is displayed.
7. Enter ReceiveFile in the Name field.
9. Select ScalableDOMIn, as shown in Figure 4–86, and click OK.

12. Check Create Instance, and click OK. The Oracle JDeveloper composite.xml page
appears, as shown in Figure 4–87.

Figure 4–87 The Oracle JDeveloper - BPELScalableDOM.bpel
15. Enter WriteFile in the Name field.
17. Select ScalableDOMOut, and click OK.
19. Select the default variable name and click OK. The Input variable field is
populated with the default variable name. The Invoke dialog is displayed.
20. Click OK. The Oracle JDeveloper BPELScalableDOM.bpel page appears, as shown
in Figure 4–88.

Figure 4–88 The Oracle JDeveloper - BPELScalableDOM.bpel Page
Add an Assign Activity
22. Double-click the Assign activity. The Assign dialog is displayed.
23. Enter AssignPayload in the Name field.
24. Click the Copy Operation tab. The Assign dialog is displayed, as shown in
Figure 4–89.
Figure 4–89 The Assign Dialog - Copy Operation Tab

25. Select Copy Operation. The Create Copy Operation dialog is displayed.
26. Expand the variables in the From and To panes, as shown in Figure 4–90.
Figure 4–90 The Create Copy Operation Dialog
27. Click OK. The Assign dialog is displayed, as shown in Figure 4–91.
Figure 4–91 The Assign Dialog
28. Click OK, the Oracle JDeveloper BPELScalableDOM.bpel page is displayed, as

2. Copy the address-csv-large.txt file to the input directory and ensure it gets
processed. Check the output directory to ensure that an output file has been
created.

displayed.
8. Click the Flow tab to view the process flow. Additionally, click an activity to view
the details of an activity.
4.5.5 Oracle File Adapter ChunkedRead
This is an Oracle File Adapter feature that uses an invoke activity within a while loop
to process the target file. This feature enables you to process arbitrarily large files.
To perform Oracle File Adapter ChunkRead, you require the address-csv.txt file. This
file can be copied from the following location:
2. Enter SOA-ChunkedRead in the Application Name field, and click Next. The
3. Enter ChunkedRead in the Project Name field.
7. Enter BPELChunkedRead in the Name field, select Define Service Later from the
Template box.
8. Click OK. The SOA-ChunkedRead application and the ChunkedRead project
appears in the design area, as shown in Figure 4–93.

9. Copy the address-csv.xsd and address-fixedLength.xsd files from
10. Copy addr1Toaddr2.xsl from
3. Enter FileInNoPayloadIn in the Service Name field.
6. Select Read File, check Do Not Read File Content box, and then click Next. The
File Directories page is displayed.
7. Enter the physical path for the input directory. Check Process Files Recursively.

displayed.
3. Enter ReadAddressChunk in the Service Name field.
6. Select Synchronous Read File, enter ChunkedRead in the Operation Name field,
and then click Next. The File Directories page is displayed.
7. Enter the physical path for the output directory and select Delete Files After
Successful Retrieval.
8. Click Next. The File Name page is displayed.
9. Enter dummy.txt in the File Name field.

16. Manually edit the metadata to incorporate the chunked read feature. Open
ReadAddressChunk_file.jca file and modify the metadata as shown below:
<endpoint-interaction portType="ChunkedRead_ptt" operation="ChunkedRead">
<interaction-spec
<property name="PhysicalDirectory" value="/tmp/chunked/in"/>
</interaction-spec>
</adapter-config>

Add Another Outbound Oracle File Adapter Service
displayed.
3. Enter AppendChunk in the Service Name field.
6. Select Write File, enter Write in the Operation Name field, and then click Next.
The File Configuration page is displayed.
7. Enter the physical path for the output directory, enter dummy.txt in the File
Naming Convention (po_%SEQ%.txt) and select Append to Existing File.

adapter service, BPEL process, two Outbound adapter reference. Perform the
following steps to wire the components:
1. Drag the small triangle in the FileInNoPayloadIn in the Exposed Services area to
the drop zone that appears as a green triangle in the BPEL process in the
Components area.
zone that appears as a green triangle in the ReadAddressChunk in the External
References area and also to the green triangle in the AppendChunk in the External
References area.
4. Double-click BPELChunkedRead. The BPELChunkedRead.bpel page is displayed.
5. Click the Variables... icon represented by (x). The Variables dialog is displayed.
6. Click the Create... icon. The Create Variable dialog is displayed.
7. Create the following variables, as shown in Figure 4–98. You will use these
variables later:
<variable name="dir" type="xsd:string"/>
<variable name="file" type="xsd:string"/>
<variable name="outIsEOF" type="xsd:string"/>
<variable name="outLineNumber" type="xsd:string"/>
<variable name="outColumnNumber" type="xsd:string"/>

<variable name="returnIsEOF" type="xsd:string"/>
<variable name="returnLineNumber" type="xsd:string"/>
<variable name="returnColumnNumber" type="xsd:string"/>
<variable name="returnIsMessageRejected" type="xsd:string"/>
<variable name="returnRejectionReason" type="xsd:string"/>
<variable name="returnNoDataFound" type="xsd:string"/>
Figure 4–98 The Variables Dialog
10. Enter ReceiveFileDetails in the Name field.
12. Select FileInNoPayloadIn, and click OK.
15. Check Create Instance.
16. Click the Properties tab. The properties and the corresponding value column is
displayed.
17. Select jca.file.Directory property. Double-click in the corresponding value column.
The Adapter Property value dialog is displayed.
18. Click the Browse Variables icon. The Variable XPath Builder dialog is displayed.
19. Expand Variables, select dir, and then click OK. The value of the
jca.file.Directory is set to dir.
20. Repeat the same for jca.file.FileName property and set the value to file. The
Receive dialog is displayed as shown in Figure 4–99.
Note: All variables are Simple Types of type xsd:string.

Figure 4–99 The Receive Dialog - Adapters Tab
21. Click OK. The Oracle JDeveloper BPELChunkedRead.bpel page appears, as
shown in Figure 4–100
Figure 4–100 The Oracle JDeveloper - BPELChunkedRead.bpel
22. Drag and drop an Assign activity from the Component Palette after the Receive
activity in the design area.
24. Enter AssignChunkedRead in the Name field.

Figure 4–89.
27. Set the default values for the headers, as shown in Figure 4–101.
28. Click OK, the Oracle JDeveloper BPELChunkedRead.bpel page is displayed, as

30. Drag and drop an Invoke activity below the Assign Activity from the Component
Palette to the design area.
32. Enter InvokeReadAddress in the Name field.
34. Select ReadAddressChunk, and click OK.
the default variable name. The Invoke dialog is displayed with input variable
populated.
37. Repeat the same to select the output variable. The Invoke dialog is displayed, as
38. Click OK. The Oracle JDeveloper BPELChunkedRead.bpel page appears, as

39. Click the Source tab for the BPELChunkedRead.bpel page, and add the following
properties for the invoke activity that you just created:
<bpelx:inputProperty name="jca.file.Directory" variable="dir"/>
<bpelx:inputProperty name="jca.file.FileName" variable="file"/>
<bpelx:inputProperty name="jca.file.LineNumber" ="outLineNumber"/>
<bpelx:inputProperty name="jca.file.ColumnNumber" variable="outColumnNumber"/>
<bpelx:inputProperty name="jca.file.IsEOF" variable="outIsEOF"/>
<bpelx:outputProperty name="jca.file.LineNumber" variable="returnLineNumber"/>
<bpelx:outputProperty name="jca.file.ColumnNumber"
variable="returnColumnNumber"/>
<bpelx:outputProperty name="jca.file.IsEOF" variable="returnIsEOF"/>
<bpelx:outputProperty name="jca.file.IsMessageRejected"
variable="returnIsMessageRejected"/>
<bpelx:outputProperty name="jca.file.RejectionReason"
variable="returnRejectionReason"/>
<bpelx:outputProperty name="jca.file.NoDataFound"
variable="returnNoDataFound"/>
The invoke activity appears as follows:
<invoke name="InvokeReadAddress"
inputVariable="InvokeReadAddress_SynchRead_InputVariable"
outputVariable="InvokeReadAddress_SynchRead_OutputVariable"
partnerLink="ReadAddressChunk" portType="ns3:SynchRead_ptt"
operation="SynchRead">
<bpelx:inputProperty name="jca.file.Directory" variable="dir"/>
<bpelx:inputProperty name="jca.file.FileName" variable="file"/>
<bpelx:inputProperty name="jca.file.LineNumber" variable="outLineNumber"/>
<bpelx:inputProperty name="jca.file.ColumnNumber" variable="outColumnNumber"/>
<bpelx:inputProperty name="jca.file.IsEOF" variable="outIsEOF"/>
<bpelx:outputProperty name="jca.file.LineNumber" variable="returnLineNumber"/>
<bpelx:outputProperty name="jca.file.ColumnNumber"

variable="returnColumnNumber"/>
<bpelx:outputProperty name="jca.file.IsEOF" variable="returnIsEOF"/>
<bpelx:outputProperty name="jca.file.IsMessageRejected"
variable="returnIsMessageRejected"/>
<bpelx:outputProperty name="jca.file.RejectionReason"
variable="returnRejectionReason"/>
<bpelx:outputProperty name="jca.file.NoDataFound"
variable="returnNoDataFound"/>
</invoke>
40. Add an assign activity called CopyHeaders, as given in Add an Assign Activity,
to copy the return parameters from the invoke activity. The Assign dialog is
displayed, as shown in Figure 4–105.
41. Click OK. The JDeveloper BPELChunkedRead.bpel page is displayed, as shown in
Figure 4–106.

Add a Switch Activity
1. Drag and drop a Switch activity below the CopyHeaders Assign activity.
2. Double-click <case> in the Switch activity. The Switch Case dialog is displayed.
3. Enter DATA FOUND in the Name field and select the returnNoDataFound
expression in the Expression box. The Switch Case dialog is displayed, as shown
in Figure 4–107.

Figure 4–107 The Switch Case Dialog
4. Drag and drop an Invoke activity in the <Case DATA FOUND> for Switch
Activity.
6. Enter InvokeAppend in the Name field.
7. Select AppendChunk in the Partner Link field.
populated.
10. Click the Properties tab and select file variable, as shown in Figure 4–108.
11. Click OK.

1. Drag and drop a Transform activity in the <case DATA FOUND> section just
before the InvokeAppend activity.
2. Double-click the Transform activity.
4. Click the Transformation tab.
6. Select InvokeReadAddress_SyncRead_InputVariable, and click OK.
7. Select InvokeAppend_Write_InputVariable from the Target Variable list.
8. Click Browse at the end of the Mapper File field, and select the addr1Toaddr2.xsl
file.
9. Click OK.
10. Drag and drop an Empty activity in the <otherwise> section in the Switch activity.
The BPELChunkedRead.bpel page is displayed, as shown in Figure 4–109.

2. Copy the address-csv.txt file to the input directory and ensure it gets
created.
displayed.
4.5.6 Oracle File Adapter Read File As Attachments
This is an Oracle File Adapter feature to opaquely copy or move large amount of data,
from a source directory on your file system to a destination directory, as attachments.
For example, you can transfer large MS Word documents, images, and PDFs without
processing their content within the composite application. The read file as attachment
feature is available only when the Read File option is chosen.
This use case demonstrates the ability of the Oracle File Adapter to process a large
*.doc file as an attachment. This feature of reading files as attachments is very similar
to Opaque translation. However, attachments can be of the order of gigabytes
depending on database limitations.

To perform Oracle File Adapter read file as attachments, you require a large MS Word
document (*.doc file).
2. Enter AttachmentApp in the Application Name field, and click Next. The Create
Generic Application - Name your project page is displayed.
3. Enter Attachment in the Project Name field.
7. Enter BPELAttachment in the Name field, select Define Service Later from the
Template list.
8. Click OK. The AttachmentApp application and the Attachment project appear
in the design area, as shown in Figure 4–110.

Perform the following steps to create an inbound Oracle File Adapter service to read a
large file from a local directory:
3. Enter AttachmentIn in the Service Name field.
6. Select Read File as the Operation Type and select Read File As Attachment, as
shown in Figure 4–111, and then click Next. The File Directories page is displayed.
7. Enter the physical path for the input directory, as shown in Figure 4–50 and click
Next. The File Filtering page is displayed.
8. Enter *.doc in the Include Files With Name Pattern field, as shown in
Figure 4–51.
Note: You must ignore Character Set, Encoding, and Content Type
fields. These fields must be populated with values only if you are
using third-party applications that must read this attachment. The
attachment in this use case is finally consumed by an outbound Oracle
File Adapter, hence these values are not required.

displayed.
3. Enter AttachmentOut in the Service Name field.
7. Enter the physical path for the output directory and enter attachment_
%SEQ%.doc in the File Naming Convention(po_%SEQ%.txt) field, as shown in
Figure 4–55.
10. Click Project WSDL Files, AttachmentIn.wsdl, Inline Schemas, and
attachmentElement, as shown in Figure 4–113.

11. Click OK. The URL field in the Messages page is populated with
AttachmentIn.wsdl.

1. Drag the small triangle in the AttachmentIn in the Exposed Services area to the
area.
zone that appears as a green triangle in the AttachmentOut in the External
References area.
4. Double-click BPELAttachment. The BPELAttachment.bpel page is displayed.
7. Enter ReceiveInput in the Name field.
9. Select AttachmentIn, as shown in Figure 4–116 and click OK.

BPELAttachment.bpel page appears, as shown in Figure 4–118.

15. Enter Write_Attachment in the Name field.
17. Select AttachmentOut, as shown in Figure 4–119, and click OK.

the default variable name. The Invoke dialog is displayed, as shown in
Figure 4–120.
20. Click OK. The Oracle JDeveloper BPELAttachment.bpel page appears, as shown
in Figure 4–121.

23. Enter AssignReference in the Name field.
Figure 4–122.

26. Expand the variables in the From and To panes, as shown in Figure 4–123.
27. Click OK. The Assign dialog is displayed, as shown in Figure 4–124.
28. Click OK, the Oracle JDeveloper BPELAttachment.bpel page is displayed, as
Note: In the case of variables defined by reference to an element,
both the source and the target must be the same element.

2. Copy the attachment.doc file to the input directory and ensure it gets
created.

displayed.
4.5.7 Oracle File Adapter File Listing
This is an Oracle File Adapter feature that lets you use an invoke activity to retrieve a
list of files from a target directory. This list of files is returned as an XML document
and contains information such as file name, directory name, file size, and last modified
time.
To perform Oracle File Adapter Listing, you require *.txt files. You must create and
save the *.txt files in the target directory.
2. Enter FileListingApp in the Application Name field, and click Next. The
3. Enter FileListing in the Project Name field.
7. Enter BPELFileListing in the Name field, select One Way BPEL Process from
the Template box.
8. Click OK. The FileListingApp application and the FileListing project appears in
the design area, as shown in Figure 4–126.

Perform the following steps to create an outbound Oracle File Adapter service to list
the file from a target directory:
displayed.
3. Enter ListFiles in the Service Name field.
6. Select List Files, enter FileListing in the Operation Name field, and then click
Next. The File Directories page is displayed.
7. Enter the physical path for the input directory, as shown in Figure 4–50.
9. Enter *.txt in the Include Files with Name Pattern field.

You have to assemble or wire the two components that you have created: BPEL
process, and the Outbound adapter reference. Perform the following steps to wire the
components:
zone that appears as a green triangle in ListFiles in the External References area.

Create a String Variable
3. Double-click BPELFileListing. The BPELFileListing.bpel page is displayed.
6. Create a variable, MyDir of type xsd:string as shown in Figure 4–129. You will
use these variables later.
7. Click OK. The Oracle JDeveloper BPELFileListing.bpel page appears, as shown in
Figure 4–130

Figure 4–130 The Oracle JDeveloper - BPELFileListing.bpel
8. Drag and drop an Invoke activity below the receive Activity from the Component
Palette to the design area.
10. Enter InvokeListFiles in the Name field.
12. Select ListFiles, and click OK.
populated.
15. Repeat the same to select the output variable. The Invoke dialog is displayed, as

displayed.
17. Select jca.file.Directory property. Double-click in the corresponding value column.
The Adapter Property Value dialog is displayed.
18. Click the Browse Variables icon. The Variable XPath Builder dialog is displayed.
19. Expand Variables, select MyDir, and then click OK. The value of the
jca.file.Directory is set to Mydir.
20. Click OK. The Oracle JDeveloper BPELFileListing.bpel page appears, as shown in
Figure 4–132.

Receive activities and the Invoke activity in the design area.
23. Enter AssignDirName in the Name field.
24. Click the Copy Operation tab. The Assign dialog is displayed.
26. Set the values for the headers, as shown in Figure 4–133.

27. Click OK, the Oracle JDeveloper BPELFileListing.bpel page is displayed, as shown
in Figure 4–134.

2. Copy the *.txt files to the input directory and ensure it gets processed. Check
the output directory to ensure that an output file has been created.
displayed.
4.5.8 Oracle File Adapter Complex Structure
This use case demonstrates the ability of the Oracle File Adapter to process native data
defined in a custom format. In this sample, the custom format represents an invoice
defined in invoice-nxsd.xsd. The Oracle File Adapter processes the invoice.txt file and
publishes this to the ComplexStructure BPEL process. This is then transformed to a
PurchaseOrder and written out as an xml file.
To perform the complex structure business process, you require the invoice.txt file.
This file can be copied from the following location:

2. Enter SOA-ComplexStructure in the Application Name field, and click Next.
The Create Generic Application - Name your project page is displayed.
3. Enter ComplexStructure in the Project Name field.
7. Enter BPEComplexStructure in the Name field, select Define Service Later
from the Template box.
8. Click OK. The SOA-ComplexStructure application and the ComplexStructure
project appears in the design area, as shown in Figure 4–135.
9. Copy the invoice-nxsd.xsd and po.xsd files from
code/products/adapters) to the schema directory in your project.
10. Copy InvToPo.xsl from (http://www.oracle.com/technology/sample_

3. Enter ComplexStructureIn in the Service Name field.
7. Enter the physical path for the input directory and click Next. The File Filtering
page is displayed.
11. Click Project Schema Files, invoice-nxsd.xsd, and invoice.
invoice-nxsd.xsd file.

External References swim lane. The Adapter Configuration Wizard Welcome page
is displayed.
3. Enter ComplexStructureOut in the Service Name field.
7. Enter the physical path for the output directory and enter invoice_%SEQ%.txt
in the File Naming Convention(po_%SEQ%.txt) field.
10. Click Project Schema Files, po.xsd, and po.
11. Click OK. The URL field in the Messages page is populated with the po.xsd file.

1. Drag the small triangle in the ComplexStructureIn service in the Exposed Services
area to the drop zone that appears as a green triangle in the BPEL process in the
Components area.
zone that appears as a green triangle in the ComplexStructureOut reference in the
External References area.

4. Double-click BPELComplexStructure. The BPELComplexStructure.bpel page is
displayed.
7. Enter ReceiveInvoice in the Name field.
9. Select ComplexStructureIn, and click OK.
BPELComplexStructure.bpel page appears.

17. Select ComplexStructureOut, and click OK.
19. Enter InvokeWrite_Write_OutputVariable in the variable name field and
click OK. The Invoke dialog is displayed.
20. Click OK. The Oracle JDeveloper BPELComplexStructure.bpel page appears.
26. Select ReceiveInvoice_Read_InputVariable in the Source Variable box, and select
body in the Source Part box, and then click OK. The Transform dialog is displayed
with the Source and Part selected.
27. Select InvokeWrite_Write_OutputVariable in the Target Variable list, select body
in the Target Part.
28. Click the Browse Mapping icon at the end of the Mapper File field and select
InvToPo.xsl file from the xsl directory in your project.
29. Click OK.
30. Click File, Save All. The BPELComplexStructure.bpel page is displayed, as shown
in Figure 4–139.

Figure 4–139 The Oracle JDeveloper - BPELComplexStructure.bpel
2. Copy the invoice.txt file to the input directory and ensure it gets processed.
displayed.

9. Click ReceiveInvoice to display the activity details
4.5.9 Oracle FTP Adapter Debatching
This is an Oracle FTP Adapter feature that debatches a large XML document into
smaller individual XML fragments. This use case demonstrates how the debatching
business process sample uses the Oracle FTP Adapter to process a file containing a
batch of business records such as one or more invoice and purchase orders. The
PurchaseOrders (POs) are then debatched and written to separate output files.
■ Section 4.5.9.3, "Creating the Inbound Oracle FTP Adapter Service"
To perform Oracle FTP Adapter debatching, you require the container.txt file. This file
can be copied from the following location:
2. Enter SOA-FTPDebatching in the Application Name field, and click OK. The
3. Enter FTPDebatching in the Project Name.
7. Enter BPELFTPDebatching in the Name field, select Define Service Later from
the Template box.
8. Click OK. The SOA-FTPDebatching application and the FTPDebatching project
appears in the design area, as shown in Figure 4–140.

9. Copy the container.xsd and po.xsd files from
code/products/adapters) into the xsd directory of your project.
10. Copy the InvToPo.xsl and PoToPo.xsl files from
4.5.9.3 Creating the Inbound Oracle FTP Adapter Service
Perform the following steps to create an inbound Oracle FTP Adapter service to read
1. Drag and drop the Oracle FTP Adapter from the Component Palette to the
Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is
displayed.
3. Enter FTPDebatchingIn in the Service Name field.
FTP Server Connection page is displayed, as shown in Figure 4–141.
Note: Ensure that you have configured the jndi-name in the
deployment descriptor for Oracle FTP Adapter before deploying this
application.

Figure 4–141 The Adapter Configuration Wizard FTP Server Connection Page
7. Select Get File, as shown in Figure 4–142, and click Next. The File Directories page
is displayed.
8. Enter the physical path for the input directory, and click Next. The File Filtering
page is displayed.

9. Enter *.txt in the Include Files With Name Pattern field, select Files Contain
Multiple Messages check box, specify 1 as the value for Publish Messages in
Batches Of box.
13. Click Project Schema Files, container.xsd, and container.
14. Click OK. The URL field in the Messages page is populated with the container.xsd
file.
1. Drag and drop the FTP Adapter from the Component Palette to the External
displayed.
3. Enter PurchaseOrderOut in the Service Name field.

7. Select Put File, and click Next. The File Configuration page is displayed.
8. Enter the physical path for the output directory and enter po_%SEQ%.txt in the
File Naming Convention(po_%SEQ%.txt) field.
9. Select Number of Messages Equals option, if not already selected. The default
value is 1.
12. Click Project Schema Files, po.xsd, and po.
13. Click OK. The URL field in the Messages page is populated with the po.xsd file.

1. Drag the small triangle in the FTPDebatchingIn service in the Exposed Services
area to the drop zone that appears as a green triangle in the BPEL process in the
Components area.
zone that appears as a green triangle in the PurchaseOrderOut reference in the
4. Double-click BPELFTPDebatching. The BPELFTPDebatching.bpel page is
displayed.
7. Enter Receive in the Name field.
9. Select FTPDebatchingIn, and click OK.

BPELFTPDebatching.bpel page appears with the Receive activity added.
15. Enter Write in the Name field.
17. Select PurchaseOrderOut, and click OK.
variable field in the Receive dialog. The Create Variable dialog is displayed.
19. Enter Write_Put_OutputVariable in the Variable field and click OK. The
Invoke dialog is displayed.
20. Click OK. The Oracle JDeveloper BPELFTPDebatching.bpel page appears with the
invoke activity added.
Add a Switch Activity
21. Drag and drop a Switch activity from the Component Palette in between the
22. Expand the Switch activity. This displays a screen to enter the values for <case>
and <otherwise>.
23. In the <case> section, click the View Condition Expression icon, as shown in
Figure 4–146. The Condition Expression pop-up window is displayed.
Figure 4–146 BPELFTPDebatching.bpel Page

24. Click the Xpath Expression Builder icon in the pop-up window. The Expression
Builder dialog is displayed.
25. Enter starts-with(local-name(ora:getNodes('receive_Get_
InputVariable','body','/ns3:container/child::*[position()=1]'
)),'invoice') as the expression, as shown in Figure 4–147, and click OK. The
screen returns to the Condition Expression pop-up window.
Figure 4–147 The Expression Builder Dialog
26. Add two transformation activities, one each for <case> and <otherwise> sections.
a. Drag and drop a Transform activity in the <case> section.
b. Double-click the Transform activity.
c. Enter InvToPo in the Name field.
d. Click the Transformation tab.
e. Click the Create... icon. The Source Variable dialog is displayed.
f. Accept the defaults and click OK.
g. Select Write_Put_OutputVariable in the Target Variable list.
h. Click the Browse Mappings icon at the end of the Mapper File field, and select
the InvToPo.xsl file.
i. Click OK.
j. Repeat the same process for the second transformation. Select PoToPo.xsl as
the Mapper File for this transform activity.
The BPELFTPDebatching.bpel page is displayed, as shown in Figure 4–148.

Figure 4–148 The BPELFTPDebatching.bpel Page
2. Copy the container.txt file to the input directory and ensure it gets processed.
displayed.

4.5.10 Oracle FTP Adapter Dynamic Synchronous Read
This use case demonstrates the ability of the Oracle FTP Adapter to perform a
mid-process synchronous read operation using an Invoke activity. This use case
illustrates the following adapter functionality:
■ Oracle File Adapter (Read Operation)
■ Oracle FTP Adapter (Synchronous Read operation)
Ability to specify the file name to be read during run-time
■ Oracle File Adapter (Write Operation)
The process is initiated by the presence of a trigger file appearing in a local directory
monitored by the inbound Oracle File Adapter. The trigger file contains the name of
the file to be read by the synchronous read operation. This file name is passed through
headers to the adapter. This can be done using the Properties tab for the Invoke
activity. This synchronous read file operation is performed against a remote directory
on a FTP server. The result of the read is then transformed and written out to a local
directory through the outbound Oracle File Adapter. This section includes the
following topics:
To perform FTP Dynamic Synchoronous Read, you require the address-csv.txt file. This
file can be copied from the following location:
You also need the trigger.trg file. This file can be copied from the following location:
2. Enter SOA-FTPDynamicSynchronousRead in the Application Name field, and
click OK. The Create Generic Application - Name your project page is displayed.
3. Enter FTPDynamicSynchronousRead in the Project Name.

7. Enter BPELDynamicSynchronousRead in the Name field, select Define Service
Later from the Template box.
8. Click OK. The SOA-FTPDynamicSynchronousRead application and
FTPDynamicSynchronousRead project appears in the design area, as shown in
Figure 4–149.
9. Copy the address-csv.xsd, address-fixedLength.xsd, and trigger.xsd files from
code/products/adapters) to the xsd directory of your project.
10. Copy the addr1Toaddr2.xsl file from
3. Enter ReadTrigger in the Service Name field.

7. Enter the physical path for the input directory and click Next. The File Filtering
page is displayed.
8. Enter *.trg in the Include Files With Name Pattern field, click Next. The File
11. Click Project Schema Files, trigger.xsd, and trigger.
12. Click OK. The URL field in the Messages page is populated with the trigger.xsd
file.

1. Drag and drop FTP Adapter from the Component Palette to the External
displayed.
3. Enter SyncRead in the Service Name field.
7. Select Synchronous Get File, and click Next. The File Directories page is
displayed.
8. Enter the physical path for the output directory.
9. Click Next. The File Name page is displayed.
10. Enter dummy.txt in the File Name field and click Next. The Messages page is
displayed.
15. Click Finish. The outbound Oracle FTP Adapter is now configured and

Add An Outbound Oracle File Adapter Service
External References swim lane. The Adapter Configuration Wizard Welcome page
is displayed.
3. Enter WriteFile in the Service Name field.
6. Select Write File, enter Write in the Operation Name field, and then click Next.
The File Configuration page is displayed.
7. Enter the physical path for the output directory, enter address_%SEQ%.txt in
the File Naming Convention (po_%SEQ%.txt).

You have to assemble or wire the four components that you have created: Inbound
adapter service, BPEL process, two Outbound adapter references. Perform the
following steps to wire the components:
1. Drag the small triangle in the ReadTrigger in the Exposed Services area to the drop
zone that appears as a green triangle in the BPEL process in the Components area.
zone that appears as a green triangle in the SyncRead in the External References
area and to the drop zone that appears as a green triangle in WriteFile.

4. Double-click BPELDynamicSynchronousRead. The
BPELDynamicSynchronousRead.bpel page is displayed.
7. Enter ReceiveTrigger in the Name field.
9. Select ReadTrigger, and click OK.
BPELDynamicSynchronousRead.bpel page appears.
Create a Variable and add an Invoke Activity
15. Create a variable called file of type xsd:string, as shown in Figure 4–154.

Figure 4–154 The Create Variable Dialog
16. Click OK to return to BPELDynamicSynchronousRead.bpel page.
19. Enter Invoke_SyncRead in the Name field.
21. Select SyncRead, and click OK.
23. Select the default variable name and click OK. The Input variable field is
populated with the default variable name.
24. Repeat the same for the Output Variable field.
displayed.
26. Select jca.ftp.FileName property. Double-click in the corresponding value
column. The Adapter Property value dialog is displayed.
27. Click the Browse variables icon. The Variable XPath Builder dialog is displayed.
28. Expand Variables, select file, and then click OK. The value of the
jca.ftp.FileName is set to file.
29. Click OK. The Oracle JDeveloper BPELDynamicSynchronousRead.bpel page
appears.
Add another Invoke Activity

5. Select WriteFile, and click OK.
variable field in the Receive dialog. The Create Variable dialog is displayed.
8. Click OK. The Oracle JDeveloper BPELDynamicSynchronousRead.bpel page
appears, as shown in Figure 4–155.
Figure 4–155 The Oracle JDeveloper - BPELDynamicSynchronousRead.bpel Page
ReceiveTrigger and Invoke_SyncRead activities in the design area.
11. Enter AssignFileName in the Name field.
12. Click the Copy Operation tab. The Assign dialog is displayed.
14. Create the copy operation between the trigger file name and the file variable, as

15. Click OK in the Create Copy Operation dialog.
16. Click OK to return to the Oracle JDeveloper BPELDynamicSynchronousRead.bpel
page, as shown in Figure 4–157.
Figure 4–157 The Oracle JDeveloper - BPELDynamicSynchronousRead.bpel

Invoke_SyncRead and InvokeWrite activities in the design area.
6. Select InvokeSyncRead_SyncRead_OutputVariable in the Source Variable box,
and select body in the Source Part box, and then click OK. The Transform dialog is
displayed with the Source and Part selected.
7. Select InvokeWrite_Write_InputVariable in the Target Variable list, select body in
the Target Part.
8. Click the Browse Mappings icon at the end of the Mapper File field and select
addr1Toaddr2.xsl file from the xsl directory in your project.
9. Click OK.
10. Click File, Save All. The BPELDynamicSynchronousRead.bpel page is displayed,
Figure 4–158 The Oracle JDeveloper - BPELDynamicSynchronousRead.bpel

2. Copy the address-csv.txt file to the input directory and ensure it gets
created.
displayed.
9. Click ReceiveTrigger to display the activity details.
4.5.11 Copying, Moving, and Deleting Files
The Oracle File and FTP Adapters let you copy or move a file from one location to
another, or delete a file from the target directory. Additionally, the Oracle FTP Adapter
lets you move or copy files from a local file system to a remote file system and from a
remote file system to a local file system. This feature is implemented as a interaction
specification for outbound services. So, this feature can be accessed either by using a
BPEL invoke activity or a Mediator routing rule.
At a high level, you must create an outbound service and configure this service with
the source and target directories and file names.
The following use cases demonstrate the new functionality supported by Oracle File
and FTP Adapters that allow you to copy, move, and delete files by using an outbound
service:
■ Section 4.5.11.1, "Moving a File from a Local Directory on the File System to
Another Local Directory"
■ Section 4.5.11.2, "Copying a File from a Local Directory on the File System to
Another Local Directory"
■ Section 4.5.11.3, "Deleting a File from a Local File System Directory"
■ Section 4.5.11.4, "Using a Large CSV Source File"
■ Section 4.5.11.5, "Moving a File from One Remote Directory to Another Remote
Directory on the Same FTP Server"

■ Section 4.5.11.6, "Moving a File from a Local Directory on the File System to a
Remote Directory on the FTP Server"
■ Section 4.5.11.7, "Moving a File from a Remote Directory on the FTP Server to a
Local Directory on the File System"
■ Section 4.5.11.8, "Moving a File from One FTP Server to another FTP Server"
4.5.11.1 Moving a File from a Local Directory on the File System to Another Local
Directory
You can model only a part of this procedure by using the wizard because the
corresponding Adapter Configuration Wizard is not available. You must complete the
remaining procedure by manually configuring the generated JCA file.
You must perform the following steps to move a file from a local directory on the file
system to another local directory:
1. Create an empty BPEL process.
displayed.
4. Enter a service name in the Service Name field.
7. Select Synchronous Read File, enter FileMove in the Operation Name field, and
then click Next. The File Directories page is displayed.
8. Enter a dummy physical path for the directory for incoming files, and then click
Next. The File name page is displayed.
9. Enter a dummy file name, and then click Next. The Messages page is displayed.
10. Select Native format translation is not required (Schema is opaque), and then
click Next. The Finish page is displayed.
11. Click Finish. The outbound Oracle File Adapter is now configured.
Note: You have selected Synchronous Read File as the operation
because the WSDL file that is generated as a result of this operation is
similar to the one required for the file I/O operation.
Note: The dummy directory is not used. You must manually change
the directory in a later step.
Note: The dummy file name you enter is not used. You must
manually change the file name in a later step.

zone that appears as a green triangle in FileMove in the External References area.
The BPEL component is connected to the Oracle File Adapter outbound service.
13. Create an invoke activity for the FileMove service that you just created by
selecting the default settings.
The next step is to modify the generated WSDL file for MoveFileService service
and configure it with the new interaction specification for the move operation.
14. Open the FileMove_file.jca file and modify the endpoint interaction, as
shown in the following example.
You must configure the JCA file with the source and target directory and file
details. You can either hardcode the source and target directory and file details in
the JCA file or use header variables to populate them. In this example, header
variables are used.
<adapter-config name="FileMove" adapter="File Adapter"
<endpoint-interaction portType="FileMove_ptt" operation="FileMove">
<interaction-spec
className="oracle.tip.adapter.file.outbound.FileIoInteractionSpec">
<property name="SourcePhysicalDirectory" value="foo1"/>
<property name="SourceFileName" value="bar1"/>
<property name="TargetPhysicalDirectory" value="foo2"/>
<property name="TargetFileName" value="bar2"/>
<property name="Type" value="MOVE"/>
</interaction-spec>
</adapter-config>
15. Map the actual directory and file names to the source and target file parameters by
performing the following procedure:
a. Create 4 string variables with appropriate names. You must populate these
variables with the source and target directory details. The BPEL source view
shows you this:
<variables>
<variable name="InvokeMoveOperation_FileMove_InputVariable"
messageType="ns1:Empty_msg"/>
<variable name="InvokeMoveOperation_FileMove_OutputVariable"
messageType="ns1:FileMove_msg"/>
<variable name="sourceDirectory" type="xsd:string"/>
<variable name="sourceFileName" type="xsd:string"/>
<variable name="targetDirectory" type="xsd:string"/>
Note: You have modified the className attribute, and added
SourcePhysicalDirectory,
SourceFileName,TargetPhysicalDirectory,
TargetFileName and Type. Currently, the values for the source and
target details are dummy. You must populate them at run-time. You
can also hardcode them to specific directories or file names.
The Type attributes decides the type of operation. Apart from MOVE,
the other acceptable values for the Type attribute are COPY and
DELETE.

<variable name="targetFileName" type="xsd:string"/>
</variables>
b. Create an assign activity to assign values to sourceDirectory,
sourceFileName, targetDirectory, and targetFileName variables.
The assign operation appears in the BPEL source view as in the following
example:
<assign name="AssignFileDetails">
<copy>
<from expression="'/home/alex'"/>
<to variable="sourceDirectory"/>
</copy>
<copy>
<from expression="'input.txt'"/>
<to variable="sourceFileName"/>
</copy>
<copy>
<from expression="'/home/alex'"/>
<to variable="targetDirectory"/>
</copy>
<copy>
<from expression="'output.txt'"/>
<to variable="targetFileName"/>
</copy>
</assign>
In the preceding example, input.txt is moved from /home/alex to
output.txt in /home/alex.
c. Pass these parameters as headers to the invoke operation. The values in these
variables override the parameters in the JCA file.
<invoke name="InvokeMoveOperation"
inputVariable="InvokeMoveOperation_FileMove_InputVariable"
outputVariable="InvokeMoveOperation_FileMove_OutputVariable"
partnerLink="FileMove" portType="ns1:FileMove_ptt"
operation="FileMove">
<bpelx:inputProperty name="jca.file.SourceDirectory"
variable="sourceDirectory"/>
<bpelx:inputProperty name="jca.file.SourceFileName"
variable="sourceFileName"/>
<bpelx:inputProperty name="jca.file.TargetDirectory"
variable="targetDirectory"/>
<bpelx:inputProperty name="jca.file.TargetFileName"
variable="targetFileName"/>
</invoke>
16. Finally, add an initial receive or pick activity.
You have completed moving a file from a local directory on the file system to
another local directory.
Note: The source and target details are hardcoded in the preceding
example. You can also provide these details as run-time parameters.

4.5.11.2 Copying a File from a Local Directory on the File System to Another Local
Directory
Perform the following procedure to copy a file from a local directory on the file system
to another local directory:
1. Follow steps 1 through 12 of Section 4.5.11.1, "Moving a File from a Local Directory
on the File System to Another Local Directory".
2. Change the value of the TYPE attribute to COPY instead of MOVE in the endpoint
interaction, in Step 14 of Section 4.5.11.1, "Moving a File from a Local Directory on
the File System to Another Local Directory" as shown in the following example:
<adapter-config ...>
<connection-factory .../>
<endpoint-interaction ...>
<interaction-spec
<property .../>
<property name="Type" value="COPY"/>
</interaction-spec>
</adapter-config>
4.5.11.3 Deleting a File from a Local File System Directory
To delete a file, you require TargetPhysicalDirectory and TargetFileName
parameters.
To delete a file, delete_me.txt, from /home/alex directory, you must perform the
following:
1. Follow steps 1 through 12 in Section 4.5.11.1, "Moving a File from a Local Directory
on the File System to Another Local Directory"
2. Change the value of the TYPE attribute to DELETE in the endpoint interaction in
Step 14 of Section 4.5.11.1, "Moving a File from a Local Directory on the File
System to Another Local Directory", as shown in the following example:
<adapter-config name="FileDelete" adapter="File Adapter"
<endpoint-interaction portType="FileDelete_ptt" operation="FileDelete">
<interaction-spec
<property name="TargetPhysicalDirectory" value="/home/alex"/>
<property name="TargetFileName" value="delete_me.txt"/>
<property name="Type" value="DELETE"/>
</interaction-spec>
</adapter-config>
Note: You do not require SourcePhysicalDirectory and
SourceFileName to delete a file from a local file system directory.

4.5.11.4 Using a Large CSV Source File
Consider the following scenario, where you have a large CSV file of size 1 gigabyte
coming on the source directory, and you must perform the following:
1. Translate the CSV into XML.
2. Transform the resulting XML using XSL.
3. Translate the result from the transform operation into a fixed length file.
This use case is similar to the FlatStructure sample in the BPEL samples directory.
The difference is that the three steps occur in a single File I/O interaction.
To use a large CSV file and perform the operations listed in the preceding scenario,
you must perform the following steps:
1. Copy the address-csv.xsd and address-fixedLength.xsd files from the
FlatStructure sample into the xsd directory of your project.
2. Copy addr1Toaddr2.xsl from the FlatStructure sample into the xsl directory
of your project.
3. Configure the File I/O interaction, as shown in the following example. At a high
level, you must specify the source schema, the target schema, and the XSL in the
interaction specification along with the source and target directory or file details,
as shown in the following example:
<adapter-config name="FileMove" adapter="File Adapter"
<endpoint-interaction portType="FileMove_ptt" operation="FileMove">
<interaction-spec
<property name="SourceSchema" value="xsd/address-csv.xsd"/>
<property name="SourceSchemaRoot value="Root-Element"/>
<property name="SourceType" value="native"/>
<property name="TargetSchema" value="xsd/address-fixedLength.xsd"/>
<property name="TargetSchemaRoot value="Root-Element"/>
<property name="TargetType" value="native"/>
<property name="Xsl value="xsl/addr1Toaddr2.xsl"/>
</interaction-spec>
</adapter-config>
Note that you have provided the following additional parameters:
■ SourceSchema: Relative path to the source schema.
■ SourceSchemaRoot: The root element in the source schema.
■ SourceType: The type of data. The other possible type is XML.
■ TargetSchema: Relative path to the target schema.
Note: All the three steps occur in a single File I/O interaction. This
works only if all the records in the data file are of the same type.

■ TargetSchemaRoot: The root element in the target schema.
■ TargetType: The type of data. The other possible type is XML.
■ Xsl: Relative path to the Xsl file.
4.5.11.5 Moving a File from One Remote Directory to Another Remote Directory on
the Same FTP Server
The I/O use cases for the Oracle FTP Adapter are very similar to those for Oracle File
Adapter. However, there are a few nuances that need attention.
In this use case you will move a file within the same directory, which is similar to a
rename operation on the same server. Most FTP servers support the RNFR/RNTO FTP
commands that let you rename a file on the FTP server.
However, even if the RNFR/RNTO commands are not supported, moving a file within
the same directory is still possible because of a binding property,
UseNativeRenameOperation. By default, this property is set to TRUE, and in this
case the Oracle FTP Adapter uses the native RNFR/RNTO commands. However, if this
property is set to FALSE, then the Oracle FTP Adapter uses the Get and Put
commands followed by a Delete command to emulate a move operation.
You can model only a part of this procedure by using the wizard because the
corresponding Adapter Configuration Wizard is not available. You must complete the
remaining procedure by manually configuring the generated JCA file.
You must perform the following steps to move a file from a remote directory to
another remote directory on the same FTP server:
1. Create an empty BPEL process.
2. Drag and drop FTP Adapter from the Component Palette to the External
displayed.
4. Enter a service name in the Service Name field.
6. Click Next. The FTP Server Connection page is displayed.
7. Enter the JNDI name for the FTP server, and click Next. The Operation page is
displayed.
8. Select Synchronous Get File, enter FTPMove in the Operation Name field, and
then click Next. The File Directories page is displayed.
9. Enter a dummy physical path for the directory for incoming files, and then click
Next. The File name page is displayed.
Note: You have selected Synchronous Get File as the operation
because the WSDL file that is generated as a result of this operation is
similar to the one required for the file I/O operation.
Note: The dummy directory is not used. You must manually change
the directory in a later step.

10. Enter a dummy file name, and then click Next. The File Name page is displayed.
12. Select Native format translation is not required (Schema is opaque), and then
click Next. The Finish page is displayed.
13. Click Finish. The outbound Oracle File Adapter is now configured.
zone that appears as a green triangle in FTPMove in the External References area.
The BPEL component is connected to the Oracle FTP Adapter outbound service.
16. Create an invoke activity for the FTPMove service that you just created.
The next step is to modify the generated WSDL file for FTPMove service and
configure it with the new interaction specification for the move operation.
17. Open the FTPMove_ftp.jca file and modify the interaction-spec, as
You must configure the JCA file with the source and target directory and file
details. You can either hardcode the source and target directory and file details in
the JCA file or use header variables to populate them. In this example, header
variables are used.
<adapter-config name="FTPMove" adapter="Ftp Adapter"
<connection-factory location="eis/Ftp/FtpAdapter" adapterRef=""/>
<endpoint-interaction portType="FTPMove_ptt" operation="FTPMove">
<interaction-spec
className="oracle.tip.adapter.ftp.outbound.FTPIoInteractionSpec">
</interaction-spec>
</adapter-config>
Note: The dummy file name you enter is not used. You must
manually change the file name in a later step.
Note: You have modified the className attribute, and added
SourcePhysicalDirectory, SourceFileName,
TargetPhysicalDirectory, TargetFileName, and Type.
Currently, the values for the source and target details are dummy. You
must populate them at run-time. You can also hardcode them to
specific directories or file names.
The Type attributes decides the type of operation. Apart from MOVE,
the other acceptable values for the Type attribute are COPY and
DELETE.

18. Map the actual directory and file names to the source and target file parameters by
performing the following procedure:
a. Create 4 string variables with appropriate names. You must populate these
variables with the source and target directory details. The BPEL source view
shows you this:
<variables>
<variable name="InvokeMoveOperation_FileMove_InputVariable"
messageType="ns1:Empty_msg"/>
<variable name="InvokeMoveOperation_FileMove_OutputVariable"
messageType="ns1:FileMove_msg"/>
<variable name="sourceDirectory" type="xsd:string"/>
<variable name="sourceFileName" type="xsd:string"/>
<variable name="targetDirectory" type="xsd:string"/>
<variable name="targetFileName" type="xsd:string"/>
</variables>
b. Create an assign activity to assign values to sourceDirectory,
sourceFileName, targetDirectory, and targetFileName variables.
The assign operation appears in the BPEL source view as in the following
example:
<assign name="AssignFTPFileDetails">
<copy>
<from expression="'/home/ftp'"/>
<to variable="sourceDirectory"/>
</copy>
<copy>
<from expression="'input.txt'"/>
<to variable="sourceFileName"/>
</copy>
<copy>
<from expression="'/home/ftp/out'"/>
<to variable="targetDirectory"/>
</copy>
<copy>
<from expression="'output.txt'"/>
<to variable="targetFileName"/>
</copy>
</assign>
In the preceding example, input.txt is moved or renamed from
/home/ftp to output.txt in /home/ftp/out.
c. Pass these parameters as headers to the invoke operation. The values in these
variables override the parameters in the JCA file.
<invoke name="InvokeRenameService"
inputVariable="InvokeRenameService_RenameFile_InputVariable"
partnerLink="RenameFTPFile" portType="ns2:RenameFile_ptt"
operation="RenameFile">
<bpelx:inputProperty name="jca.file.SourceDirectory"
variable="returnDirectory"/>
<bpelx:inputProperty name="jca.file.SourceFileName" variable="returnFile"/>
<bpelx:inputProperty name="jca.file.TargetDirectory"
Note: The source and target details are hardcoded in the preceding
example. You can also provide these details as run-time parameters.

variable="returnDirectory"/>
<bpelx:inputProperty name="jca.file.TargetFileName" variable="targetFile"/>
</invoke>
19. Finally, add an initial receive or pick activity.
You have completed moving or renaming a file from a remote directory to another
remote directory on the same FTP server.
4.5.11.6 Moving a File from a Local Directory on the File System to a Remote
Directory on the FTP Server
The steps for this use case are the same as the steps for the use case in Section 4.5.11.5,
"Moving a File from One Remote Directory to Another Remote Directory on the Same
FTP Server" except that you must configure the source directory as local and the target
directory as remote.
Use the SourceIsRemote and TargetIsRemote properties to specify whether the
source and target file are on the local or remote file system, as shown in the following
example:
<interaction-spec
<property name="SourceIsRemote" value="false"/>
</interaction-spec>
</adapter-config>
Note: If the FTP server does not support the RNFR/RNTO FTP
commands, then you must set UseNativeRenameOperation to
FALSE and define the property in composite.xml, as shown in the
following example:
<reference name="FTPMove" ui:wsdlLocation="FTPMove.wsdl">
<interface.wsdl
interface="http://xmlns.oracle.com/pcbpel/adapter/ftp/SOAFtpIO/SOAF
tpIO/FTPMove/#wsdl.interface(FTPMove_ptt)"/>
<binding.jca config="FTPMove_ftp.jca">
<property name="UseNativeRenameOperation" type="xs:string"
many="false" override="may">false</property>
</binding.jca>
</reference>

4.5.11.7 Moving a File from a Remote Directory on the FTP Server to a Local
Directory on the File System
The steps for this use case are the same as the steps for the use case in Section 4.5.11.6,
"Moving a File from a Local Directory on the File System to a Remote Directory on the
FTP Server" except that you must configure the source directory as remote and the
target directory as local, as shown in the following example:
<interaction-spec
<property name="TargetIsRemote" value="false"/>
</interaction-spec>
</adapter-config>
4.5.11.8 Moving a File from One FTP Server to another FTP Server
To move a file from one FTP server to another FTP server you must sequentially
perform the use cases documented in the following sections:
1. Section 4.5.11.7, "Moving a File from a Remote Directory on the FTP Server to a
Local Directory on the File System" to upload the file from the local directory to
another FTP server
2. Section 4.5.11.6, "Moving a File from a Local Directory on the File System to a
Remote Directory on the FTP Server" to download the file from the FTP server to a
local directory
Note: In this example, you have configured SourceIsRemote as
false. In this case, the FTP input and output operation assumes that
the source file comes from a local file system. Also, notice that you did
not specify the parameter for target because TargetIsRemote is set
to true by default.
Note: In this example, you have configured TargetIsRemote as
false. In this case, the FTP I/O assumes that the source file comes
from a remote file system whereas the target is on a local file system.
Also, notice that you did not specify the parameter for source because
SourceIsRemote is set to true by default.

5
Oracle JCA Adapter for Sockets 5-1
5
Oracle JCA Adapter for Sockets
This chapter describes how to use Oracle JCA Adapter for Sockets (Oracle Socket
Adapter), which works with Oracle BPEL Process Manager (BPEL PM) and Oracle
Mediator (Mediator) as an external service.
■ Section 5.1, "Introduction to Oracle Socket Adapter"
■ Section 5.2, "Oracle Socket Adapter Features"
■ Section 5.3, "Oracle Socket Adapter Concepts"
■ Section 5.4, "Configuring Oracle Socket Adapter"
■ Section 5.5, "Oracle Socket Adapter Use Cases"
5.1 Introduction to Oracle Socket Adapter
Oracle Socket Adapter is a JCA 1.5 compliant adapter for modeling standard or
nonstandard protocols for communication over TCP/IP sockets. You can use an Oracle
Socket Adapter to create a client or a server socket, and establish a connection. The
data that is transported can be text or binary.
■ Section 5.1.1, "Oracle Socket Adapter Architecture"
■ Section 5.1.2, "Oracle Socket Adapter Integration with Mediator"
■ Section 5.1.3, "Oracle Socket Adapter Integration with BPEL PM"
■ Section 5.1.4, "Oracle Socket Adapter Integration with SOA Composite"
5.1.1 Oracle Socket Adapter Architecture
Oracle Socket Adapter is based on the JCA 1.5 architecture. JCA provides a standard
architecture for integrating heterogeneous enterprise information systems (EIS). The
JCA Binding Component of the Oracle Socket Adapter exposes the underlying JCA
interactions as services (WSDL with JCA binding) for BPEL PM integration. Figure 5–1
illustrates the architecture of Oracle Socket Adapter. For details about the Oracle JCA
Adapter architecture, see Section 1.2.1.1, "Architecture."

Introduction to Oracle Socket Adapter
Figure 5–1 Oracle Socket Adapter Architecture
5.1.2 Oracle Socket Adapter Integration with Mediator
Oracle Socket Adapter is automatically integrated with Mediator. When you create an
Oracle Socket Adapter service in JDeveloper Designer, the Adapter Configuration
Wizard is started. This wizard enables you to configure the Oracle Socket Adapter.
When configuration is complete, a WSDL file of the same name is created in the
Application Navigator section of Oracle JDeveloper. This WSDL file contains the
Wizard pages appear and prompt you for configuration information.
For more information about Oracle JCA Adapter integration with Mediator, see
Section 3.2, "Adapter Integration with Oracle Fusion Middleware."
5.1.3 Oracle Socket Adapter Integration with BPEL PM
Oracle Socket Adapter is automatically integrated with BPEL PM. When you drag and
drop Socket Adapter from the Component Palette of JDeveloper BPEL Designer, the
Adapter Configuration Wizard starts with a Welcome page, as shown in Figure 5–2.
Handshake Modes
Client Socket
Server Socket
(Interaction)
Client Socket
Server Socket
(Activation)
Socket Adapter
Native Schema Framework
JCA Binding Component
JCA 1.5
SOA/Fabric_____________________

Oracle Socket Adapter Features
Figure 5–2 The Adapter Configuration Wizard - Welcome Page
This wizard enables you to configure an Oracle Socket Adapter. The Adapter
Configuration Wizard then prompts you to enter a service name, as shown in
Figure 5–35. When configuration is complete, a WSDL file of the same name is created
in the Application Navigator section of Oracle JDeveloper. This WSDL file contains the
Wizard pages appear and prompt you for configuration information.
For more information about Oracle JCA Adapter integration with BPEL PM, see
Section 3.2, "Adapter Integration with Oracle Fusion Middleware."
5.1.4 Oracle Socket Adapter Integration with SOA Composite
A composite is an assembly of services, service components (BPEL PM and Mediator),
wires, and references designed and deployed together in a single application. The
composite processes the information described in the messages. The details of the
composite are stored in the composite.xml file. For more information on integration of
the Oracle Socket Adapter with SOA composite, see Section 3.2.4, "Oracle SOA
Composite Integration with Adapters."
5.2 Oracle Socket Adapter Features
Oracle Socket Adapter enables you to configure a BPEL process or a Mediator service
to read and write data over TCP/IP sockets. It includes the following features:
■ Allows modeling of standard or nonstandard protocols for communication over
TCP/IP sockets
■ Supports both inbound and outbound communication
■ Allows you to model complex protocol handshakes declaratively, by using XSL

Oracle Socket Adapter Concepts
■ Allows you the option of plugging in custom Java code to model a protocol
handshake
■ Provides support for reading and writing native data over sockets as the adapter is
integrated with the translator infrastructure (NXSD)
■ Supports multiple character encoding
5.3 Oracle Socket Adapter Concepts
This section describes the following Oracle Socket Adapter concepts:
■ Section 5.3.1, "Communication Modes"
■ Section 5.3.2, "Mechanisms for Defining Protocols"
■ Section 5.3.3, "Character Encoding and Byte Order"
■ Section 5.3.4, "Performance Tuning"
5.3.1 Communication Modes
Oracle Socket Adapter supports inbound and outbound communication over sockets
that can be unidirectional or bidirectional. The communication modes of Oracle Socket
Adapter are discussed in the following sections:
■ Section 5.3.1.1, "Inbound Synchronous Request/Response"
■ Section 5.3.1.2, "Outbound Synchronous Request/Response"
■ Section 5.3.1.3, "Inbound Receive"
■ Section 5.3.1.4, "Outbound Invoke"
5.3.1.1 Inbound Synchronous Request/Response
As part of inbound activation, the Oracle Socket Adapter opens a server socket and
waits for incoming connections. The adapter uses the connection to the server socket
and reads the request message, which is published to BPEL or Mediator. The Oracle
Socket Adapter then uses the same connection to send the response back
synchronously.
Figure 5–3 illustrates an inbound synchronous request/response scenario.

Figure 5–3 BPEL Scenario of Inbound Synchronous Request/Response
5.3.1.2 Outbound Synchronous Request/Response
In the case of outbound synchronous request/response, a request comes from BPEL or
Mediator. The Oracle Socket Adapter connects to the server socket to send the request
message to the server socket on the output stream. The Oracle Socket Adapter then
blocks the response from the server socket on the input stream and publishes the
response back to BPEL or Mediator.
Figure 5–4 illustrates an outbound synchronous request/response scenario.
Figure 5–4 BPEL Scenario of Outbound Synchronous Request/Response
5.3.1.3 Inbound Receive
As part of inbound activation, the Oracle Socket Adapter opens a server socket and
waits for incoming connections. The adapter uses the connection to the server socket
and reads the request message, which is published to BPEL or Mediator. In this
scenario, no reply is sent.

5.3.1.4 Outbound Invoke
In the case of an outbound one way invoke scenario, the request comes from BPEL or
Mediator. Oracle Socket Adapter connects to the server socket and sends the request
message to the server socket on the output stream without expecting a reply.
5.3.2 Mechanisms for Defining Protocols
Communication protocols or handshakes consist of different discrete steps such as
authentication procedures, acknowledgments, and sending or receiving data
depending on conditions. Oracle Socket Adapter supports the following mechanisms
to define the protocol handshakes.
■ Protocol with Handshake Mechanism Using Style Sheet
■ Protocol with Handshake Mechanism Using Custom Java Code
■ Protocol Without Handshake Mechanism
5.3.2.1 Protocol with Handshake Mechanism Using Style Sheet
Oracle Socket Adapter can be configured to use a protocol designed with a handshake
mechanism, defined using style sheets that use XPath Extension functions exposed by
the adapter. This can be granular read and write operation on the socket I/O stream or
till the end of the stream. These functions also enable you to use native format
constructs for reading and writing data. This handshake mechanism uses XSLT
constructs to define operations such as assignments, validations, and control flow.
You can use the XPath Extension functions with the translator infrastructure in the
following ways:
■ By using StyleReader, which is exposed by the NXSD framework, to read and
write from the socket stream using the following methods:
– socketRead(nxsdStyle:String,
nxsdStyleAttributes:String):String
You can use this method to read from the socket input stream.
– socketWrite(value:String, nxsdStyle:String,
nxsdStyleAttributes:String):String
You can use this method to write to the socket output stream.
The XSLT shown in Figure 5–5 demonstrates the usage of extension functions that
use StyleReader.

Figure 5–5 XSLT with Extension Functions That Use StyleReader
■ By annotating the schema, which defines the input and output variables, using
NXSD constructs to read and write from the socket stream using the following
methods:
– socketReadWithXlation():DocumentFragment
You can use this method to read from the socket input stream by using the
schema and schema element configured for input.
– socketWriteWithXlation(xml:NodeList)
You can use this method to write to the socket output stream by using the
schema configured for output.
The XSD file shown in Figure 5–6 demonstrates the usage of extension functions
by annotating the schema, which defines the input and output variables, using
NXSD constructs.

Figure 5–6 XSD with Extension Functions That Do Not Use StyleReader
To define a handshake using style sheet, you must select Use XSLT to define the
handshake and browse to select the XSL file in the Protocol page, as shown in
Figure 5–7.
Figure 5–7 Defining a Protocol with Handshake Mechanism By Using a Style Sheet
5.3.2.2 Protocol with Handshake Mechanism Using Custom Java Code
Oracle Socket Adapter can be configured to use a protocol with a customized
handshake mechanism, defined by plugging in custom Java code. The custom Java
code must implement
oracle.tip.pc.services.translation.util.ICustomParser, the
ICustomParser interface, provided by Oracle Socket Adapter, which enables custom
implementation of handshakes.

The following methods must be implemented based on the appropriate
communication paradigm:
■ public Element executeOutbound(InputStream in, OutputStream
out, Element payLoad) throws Exception;
The outbound handshake must implement this method.
Example:
public Element executeOutbound(InputStream in, OutputStream out, Element
payLoad) throws Exception {
BufferedReader in1 = new BufferedReader(new InputStreamReader(in));
PrintWriter out1 = new PrintWriter(new OutputStreamWriter(out));
out1.println(payLoad.getFirstChild().getNodeValue());
String retVal = in1.readLine();
StringBuffer strBuf = new StringBuffer();
strBuf.append("<?xml version='1.0' encoding='" + enc + "' ?>"
+ "<out xmlns='http://xmlns.oracle.com/EchoServer/'>");
strBuf.append(retVal + "</out>");
DOMParser parser = new DOMParser();
parser.setValidationMode(DOMParser.NONVALIDATING);
Element elem = (Element) parser.getDocument().getElementsByTagName(
"out").item(0);
return elem;
}
■ public Element executeInboundRequest(InputStream in) throws
Exception;
The inbound request must implement this method.
Example:
public Element executeInboundRequest(InputStream in) throws Exception {
BufferedReader in1 = new BufferedReader(new InputStreamReader(in));
String input = in1.readLine();
StringBuffer strBuf = new StringBuffer();
strBuf.append("<?xml version='1.0' encoding='" + enc + "' ?>"
+ "<EchoClientProcessRequest
xmlns='http://xmlns.oracle.com/EchoClient'>");
strBuf.append("<input>" + input +
"</input></EchoClientProcessRequest>");
DOMParser parser = new DOMParser();
parser.setValidationMode(DOMParser.NONVALIDATING);
parser.parse(new InputSource(new StringReader(strBuf.toString())));
Element elem = (Element) parser.getDocument().getElementsByTagName(
Note: The ICustomParser interface files are in the bpm-infra.jar
file. This jar file is available in the following directory:
$ORACLE_HOME/soa/modules/oracle.soa.fabric_11.1.1

"EchoClientProcessRequest").item(0);
return elem;
}
■ public void executeInboundReply(Element payLoad, OutputStream
out) throws Exception;
The inbound reply must implement this method.
Example:
public void executeInboundReply(Element payLoad, OutputStream out) throws
Exception {
PrintWriter out1 = new PrintWriter(new OutputStreamWriter(out));
NodeList list = payLoad.getChildNodes();
String retVal = null;
for(int i = 0; i < list.getLength(); i++) {
Node node = list.item(i);
NodeList list1 = node.getChildNodes();
for(int j = 0; j < list1.getLength(); j++) {
Node node1 = list1.item(j);
if(node1.getNodeType() == Node.TEXT_NODE) {
retVal = node1.getNodeValue();
}
}
}
out1.println(retVal);
out1.flush();
}
To use a custom Java code to define a handshake, you must select Use Custom Java
Code to define the handshake and specify the Java class implementing the handshake
in the Java Class field, as shown in Figure 5–8.
Note: in is the handle to the socket input stream and out is the
handle to the socket output stream.

Figure 5–8 Defining a Protocol with Handshake Mechanism By Using Custom Java Code
5.3.2.3 Protocol Without Handshake Mechanism
Oracle Socket Adapter can be configured to use protocols that do not require
handshakes involving translation to and from the socket I/O stream.
To use a protocol that does not require a handshake, you must select No Handshake
in the Protocol page, as shown in Figure 5–9.
Figure 5–9 Defining a Protocol without a Handshake Mechanism
5.3.3 Character Encoding and Byte Order
The Encoding property represents the character encoding in which native data is
stored, and the ByteOrder property is the byte order of the native data, which is either
BIG_ENDIAN or LITTLE_ENDIAN.
Character encoding and byte order can be specified in the schema file (NXSD), using
the Native Format Builder wizard. You can also specify the encoding and the byte

order to be used, by using Adapter Configuration Wizard. When encoding and byte
order are not specified, the default values are US_ASCII and BIG_ENDIAN.
To specify the encoding and byte order values, which are applicable only if you are
using translation, you must perform the following steps in the Protocol page of
Adapter Configuration Wizard:
1. In the Encoding/ByteOrder section of the Protocol page, select the Specify
Encoding/Byte Order option, as shown in Figure 5–10.
Figure 5–10 The Adapter Configuration Wizard - Protocol Page
2. Perform one of the following tasks to set the encoding:
a. To use the encoding specified in the schema file, select Use Encoding Value
from the Schema.
b. To specify the encoding using the Adapter Configuration Wizard, select
Encoding, and then select an encoding type from the Encoding list.
3. Perform one of the following tasks to set the byte order:
a. To use the byte order specified in the schema file, select Use Byte Order Value
from the schema.
b. To specify the byte order using Adapter Configuration Wizard, select
ByteOrder, and then select a byte order from the ByteOrder list.
4. Click Finish.
The Oracle Socket Adapter support the performance tuning feature. Performance can
be optimized for the Oracle Socket Adapter using Connection Pool, provided the
socket server you are connecting to does not close the socket with each interaction.
Note: If you select Encoding, then the encoding type specified using
the Adapter Configuration Wizard takes precedence over the
encoding type specified in the NXSD file.

Configuring Oracle Socket Adapter
Connection pool lets you use a socket connection repeatedly, avoiding the overload of
creating a new socket for each interaction.
For more information about performance tuning, see the chapter on "Oracle Adapters
Performance Tuning" in the Oracle Fusion Middleware Performance Guide.
5.4 Configuring Oracle Socket Adapter
The following tasks are required for configuring Oracle Socket Adapter:
■ Modifying the weblogic-ra.xml File
■ Modeling a Handshake
■ Designing an XSL File Using the XSL Mapper Tool
5.4.1 Modifying the weblogic-ra.xml File
To configure Oracle Socket Adapter, you must specify the value of the properties listed
in Table 5–1 in the weblogic-ra.xml file. You can update these properties from the
Oracle WebLogic Server console. For more information, see Section 2.4, "Adding an
Adapter Connection Factory."
The following is a sample weblogic-ra.xml file:
<wls:connection-instance>
<wls:description>Socket Adapter</wls:description>
<wls:jndi-name>eis/socket/SocketAdapter</wls:jndi-name>
<wls:connection-properties>
<wls:pool-params>
<wls:initial-capacity>0</wls:initial-capacity>
<wls:max-capacity>200</wls:max-capacity>
<wls:capacity-increment>5</wls:capacity-increment>
<wls:shrinking-enabled>true</wls:shrinking-enabled>
<wls:shrink-frequency-seconds>60</wls:shrink-frequency-seconds>
<wls:connection-creation-retry-frequency-seconds>2</wls:connection-creation-retry-
Table 5–1 Oracle Socket Adapter Configuration Properties
Host In case of outbound interaction, the system name on which the socket server is
running, to which you want to connect. In case of inbound interaction, it is always
localhost.
Port In case of outbound interaction, it is the port number on which a socket server is
running, to which an adapter connects. In case of inbound interaction, it is the port
number on which the socket adapter listens for incoming connections.
Timeout With this value set to a nonzero timeout interval, a read() call on the InputStream
associated with this socket blocks for only this amount of time. If the timeout interval
expires, then a java.net.SocketTimeoutException is raised though the socket
is still valid. The option must be enabled before entering the blocking operation to
have effect. The timeout interval must be greater than 0. A timeout interval of 0 is
interpreted as an infinite timeout. The value is in milliseconds.
KeepAlive Applicable only in case of outbound interactions. Should be set to true to use
connection pool feature.
BacklogQueue Applicable in case of inbound interactions. This value indicates the maximum queue
length for incoming connection indications (a request to connect). If a connection
indication arrives when the queue is full, then the connection is refused.

frequency-seconds>
<wls:connection-reserve-timeout-seconds>5</wls:connection-reserve-timeout-seconds>
<wls:match-connections-supported>true</wls:match-connections-supported>
<wls:use-first-available>true</wls:use-first-available>
</wls:pool-params>
<wls:transaction-support>NoTransaction</wls:transaction-support>
<wls:reauthentication-support>true</wls:reauthentication-support>
<wls:properties>
<wls:property>
<wls:name>Host</wls:name>
<wls:value>localhost</wls:value>
</wls:property>
<wls:property>
<wls:name>Port</wls:name>
<wls:value>12110</wls:value>
</wls:property>
<wls:property>
<wls:name>Timeout</wls:name>
</wls:property>
<wls:property>
<wls:name>BacklogQueue</wls:name>
</wls:property>
<wls:property>
<wls:name>KeepAlive</wls:name>
<wls:value>True</wls:value>
</wls:property>
</wls:properties>
<wls:res-auth>Application</wls:res-auth>
</wls:connection-properties>
</wls:connection-instance>
5.4.2 Modeling a Handshake
A handshake may be required to negotiate a connection with a client or a server
socket.
5.4.2.1 Modeling an Outbound Handshake
The outbound XSLT uses an input corresponding to the invoked message. The
outbound XSLT writes to the socket output stream by using extension functions. The
output is dummy for unidirectional or a response for bidirectional communication.
The following example demonstrates the modeling of a Synchronous
Request/Response communication paradigm:
<xsl:stylesheet
...
xmlns:socket="http://www.oracle.com/XSL/Transform/java/oracle.tip.adapter.socket.P
rotocolTranslator" />
xmlns:request="http://www.TragetNameSpace.com/Request" >
Note: To set up connection pooling, you must set the KeepAlive
property to true.

<xsl:template match="/">
<!–- Write the entire content of "books" element using translator -->
<xsl:variable name="username" select="socket:socketWriteWithXlation(.)" />
<!–- Read the stream using translator -->
<xsl:copy-of select="socket:socketReadWithXlation()" />
</xsl:template>
</xsl:stylesheet>
5.4.2.2 Modeling an Inbound Handshake
The inbound XSLT uses a dummy input, reads the socket input stream through
extension functions, and constructs the XML record to be published.
The following example demonstrates a handshake in which the client sends across a
user identification terminated by a comma (,) and a password terminated by a
semicolon (;) for validation, and then sends the message payload:
<xsl:stylesheet
...
xmlns:socket="http://www.oracle.com/XSL/Transform/java/oracle.tip.adapter.socket.P
rotocolTranslator" />
<xsl:template match="/">

<xsl:variable name="username"
select="socket:socketRead('terminated','terminatedBy=,')" />

<xsl:if test="normalize-space($username)='user'">
<xsl:variable name="password"
select="socket:socketRead('terminated','terminatedBy=;')" />

<xsl:if test="normalize-space($password)='password'">

<xsl:variable name="ack1" select="socket:socketWrite('001','','')" />
<output>

<xsl:copy-of select="socket:socketReadWithXlation()" />
</output>
</xsl:if>

<xsl:else><xsl:variable name="ack2" select="socket:socketWrite('000','','')"
/></xsl:else>
</xsl:if>
</xsl:template>
</xsl:stylesheet>
5.4.3 Designing an XSL File Using the XSL Mapper Tool
You can design an XSL file by using the XSL mapper tool for Oracle Socket Adapter.
The following sections describe the procedure for designing XSL for different
communication scenarios:
■ Section 5.4.3.1, "Designing XSL for Inbound Synchronous Request/Reply"

■ Section 5.4.3.2, "Designing XSL for Outbound Synchronous Request/Reply"
5.4.3.1 Designing XSL for Inbound Synchronous Request/Reply
This section describes the procedure for designing XSL for an inbound synchronous
request/reply scenario by using the XSL mapper tool:
Design an SOA Composite
To design an SOA composite, perform the steps described in Section 5.5.1.2,
"Designing the SOA Composite."
Create an Inbound Oracle Socket Adapter Service
To create an inbound Oracle Socket Adapter service, perform the following steps:
1. Drag and drop Socket Adapter from the Components Palette to the Exposed
Services swim lane. The Welcome page of the Adapter Configuration Wizard is
displayed.
3. Enter the service name, HelloWorld in the Service Name field and then click
Next. The Adapter Interface page is displayed.
4. Select Define from operation and schema (specified later), as shown in the
Figure 5–36, and click Next. The Operation page is displayed.
5. Select Inbound Synchronous Request/Reply as the Operation Type and then click
Next. The Socket Connection page is displayed.
6. Enter eis/socket/InboundSocketAdapter in the Socket Connection JNDI
Name field, as shown in Figure 5–38, and click Next. The Messages page is
displayed.
7. Click Browse For Schema File that appears at the end of the URL field in the
Request Message Schema box. The Type Chooser dialog is displayed.
8. Click Project Schema Files, HelloWorld.xsd, and HelloWorldProcessRequest, as
HelloWorld.xsd file.
Reply Message Schema box. The Type Chooser dialog is displayed.
11. Click Project Schema Files, HelloWorld.xsd, and HelloWorldProcessResponse.
Note: To perform this use case, you require the HelloWorld.xsd
file. You can copy this file from the following location to
HelloWorldCompositexsd under the HelloWorldComposite
project:
code/products/adapters)
Note: The steps provided in Section 5.5.1.2, "Designing the SOA
Composite" are applicable to a composite with BPEL PM.
Alternatively, you can create a composite with Mediator.

12. Click OK. The URL fields in the Messages page are populated with the
HelloWorld.xsd files, as shown in Figure 5–40.
13. Click Next. The Protocol page is displayed, as shown in Figure 5–11.
14. Select Use XSLT to define the handshake.
15. Click the create new xsl file icon that appears at the end of the Xslt field. The
Input dialog appears as shown in Figure 5–12.
Figure 5–12 The input Dialog of the Protocol Page
16. Use the default value, request.xsl, as the name of the XSL file, as shown in
Figure 5–12 and click OK.
17. Click the create new xsl file icon that appears at the end of the ReplyXslt field. The
Input dialog appears.
18. Use the default value, reply.xsl, as the name of the XSL file, and click OK.

19. Click Finish. The request.xsl and the reply.xsl files are created.
Figure 5–13 shows the request.xsl page.
Figure 5–13 The Oracle JDeveloper - request.xsl Page
Figure 5–14 shows the reply.xsl page.
Note: A dummy.xsd file appears in the left Source pane of the
request.xsl page, which is used as the source for the XSL mapper
tool.
In an inbound request scenario, Oracle Socket Adapter reads native
data that is received by the socket and converts it to an XML format.
That is, on the source side there is no XML file. Because the XSLT
mapper always needs source and target XSD files, a dummy XSD file
appears in the mapper tool.

Figure 5–14 The Oracle JDeveloper - reply.xsl Page
20. Define the request part of the inbound synchronous request/reply operation as
follows:
a. In the request.xsl page, drag and drop socketRead from the Advanced
Functions list of the Components Palette to the middle pane, as shown in
Figure 5–15.
Note: A dummy.xsd file appears in the right target pane of the
reply.xsl page. This dummy.xsd file is used as the target for the
XSL mapper tool.

b. Double-click the socketRead advanced function. The Edit Function -
socketRead dialog appears.
c. Enter the function parameters in the nxsdStyle and nxsdStyleAttributes
fields, as shown in Figure 5–16.
Figure 5–16 The Edit Function - socketRead Dialog
Note: The socketRead function reads from the socket input stream
by using the StyleReader exposed by the NXSD framework.

d. Click OK. The request.xsl (XSL mapper) page is displayed.
e. Link the sockRead function in the middle pane to the target input node on
the right pane. The request.xsl (XSL mapper) with the XSL mapping is
displayed as shown in Figure 5–17.
21. Define the reply part of the inbound synchronous request/reply operation as
follows:
a. From the Component Palette list, select Advanced, and then select Advanced
Functions. A list of advanced functions are displayed.
b. In the reply.xsl page, drag and drop socketWrite from the Advanced
Functions list of the Component Palette to the middle pane.
c. Double-click the socketWrite advanced function. The Edit Function -
socketWrite dialog appears.
d. Enter the function parameters in the valueToWrite, nxsdStyle, and
nxsdStyleAttributes fields, as shown in Figure 5–18.

Figure 5–18 The Edit Function - socketWrite Dialog
e. Click OK. The reply.xsl (XSL mapper) page is displayed.
f. Link the sockWrite function in the middle pane to the target input node on
the right pane. The reply.xsl (XSL mapper) with the XSL mapping is
Figure 5–19 The Oracle JDeveloper - reply.xsl Page
Note: The socketWrite function writes to the socket output stream
by using the StyleReader exposed by the NXSD framework.

22. Click File, Save All. The request.xsl and reply.xsl files for the inbound Oracle
Socket Adapter are created.
5.4.3.2 Designing XSL for Outbound Synchronous Request/Reply
This section describes the procedure for designing XSL for an outbound synchronous
request/reply scenario by using the XSL mapper tool:
Design an SOA Composite
To design an SOA composite, perform the steps described in Section 5.5.1.2,
"Designing the SOA Composite.".
Create an Outbound Oracle Socket Adapter Reference
To create an outbound Oracle Socket Adapter reference, perform the following steps:
1. Drag and drop Socket Adapter from the Components Palette to the External
References swim lane. The Welcome page of the Adapter Configuration Wizard is
displayed.
3. Enter the service name, HelloWorld in the Service Name field and then click
Next. The Adapter Interface page is displayed.
Figure 5–36 and click Next. The Operation page is displayed.
5. Select Outbound Synchronous Request/Reply as the Operation Type and then
click Next. The Socket Connection page is displayed.
6. Enter eis/socket/OutboundSocketAdapter in the Socket Connection JNDI
Name field and click Next. The Messages page is displayed.
Note: To perform this use case, you require the HelloWorld.xsd
file. You can copy this file from the following location to
HelloWorldCompositexsd under the HelloWorldComposite
project:
Note: The steps provided in Section 5.5.1.2, "Designing the SOA
Composite" are applicable to a composite with BPEL PM.
Alternatively, you can create a composite with Mediator.

13. Click Next. The Protocol page is displayed.
15. Click the create new xsl file icon that appears at the end of the Xslt field. The
Input dialog appears.
16. Use the default value, invoke.xsl, as the name of the XSL file and click OK.
17. Click Finish. The invoke.xsl file appears in the XSL mapper, as shown in
Figure 5–20.
Figure 5–20 The Oracle JDeveloper - invoke.xsl Page
18. Right-click the HelloWorldProcessResponse element on the target side. A menu is
displayed as shown in Figure 5–21.

19. Click Add Variable.... The Add Variable dialog is displayed as shown in
Figure 5–22.
Figure 5–22 The Add Variable Dialog
20. Enter var1 in the Local Name field, and click OK. The var1 variable is added to
the target pane of the XSL mapper.
21. From the Component Palette list, select Advanced; then, select Advanced
Functions. A list of advanced functions is displayed.
22. Define the request part of the outbound synchronous request/reply operation, to
write the data to the socket server, as follows:
a. Drag and drop socketWriteWithXlation from the Advanced Functions list of
the Component Palette to the middle pane, as shown in Figure 5–23.

b. Drag the var1 node to the socketWriteWithXlation function. A link is created,
c. Double-click the socketWriteWithXlation advanced function. The Edit
Function - socketWriteWithXlation dialog appears.
d. Enter a dot (.) in the NodeList field, as shown in Figure 5–25.

Figure 5–25 The Edit Function - socketWriteWithXlation Dialog
e. Click OK. A Warning dialog appears.
f. Click Yes. The invoke.xsl page is displayed. The request part of the
Synchronous Request/Reply operation is defined.
23. Define the reply part of the outbound synchronous request/reply operation as
follows:
a. Drag and drop socketReadWithXlation from the Advanced Functions list of
the Component Palette to the middle pane, as shown in Figure 5–26.
Note: The socketWriteWithXlation function writes to the
socket output stream using the schema configured for the output.
The dot (.) specified in the NodeList field signifies writing the
HelloWorldProcessRequest to the top level node.

b. From the Component Palette list, select General; then, select XSLT
Constructs. A list of XSLT constructs is displayed.
c. Drag copy-of from the Component Palette to HelloWorldProcessResponse in
the target pane. The Copy-of Type Dialog appears, as shown in Figure 5–27.

Figure 5–27 The Oracle JDeveloper - invoke.xsl Page with Copy-of Type Dialog
d. Click OK. The invoke.xsl (XSL mapper) page is displayed with the copy-of
XSLT construct added to the target pane, as shown in Figure 5–28.

Oracle Socket Adapter Use Cases
e. Drag the copy-of XSLT construct to the socketReadWithXlation function. A
link is created, as shown in Figure 5–29.
24. Click File, Save All. The Outbound Synchronous Request/Reply handshake is
defined.
5.5 Oracle Socket Adapter Use Cases
This section includes the following Oracle Socket Adapter use cases:
■ Section 5.5.1, "Oracle Socket Adapter Hello World"
■ Section 5.5.2, "Flight Information Display System"
5.5.1 Oracle Socket Adapter Hello World
This is a simple HelloWorld use case, which demonstrates the synchronous inbound
request/response and synchronous outbound request/response modes of
communication using Oracle Socket Adapter. The HelloWorld business process takes
an input string from the Oracle Socket Adapter inbound service and publishes the
message to the BPEL process. The BPEL process invokes the Oracle Socket Adapter
outbound service (a simple HelloWorld Server, which adds a prefix ?Hello? to the
input string and returns it) and returns the received string using a synchronous reply.
■ Section 5.5.1.3, "Creating the Inbound Oracle Socket Adapter Service"

■ Section 5.5.1.4, "Creating the Outbound Oracle Socket Adapter Service"
■ Section 5.5.1.7, "Monitoring Using the Enterprise Manager Console"
To perform this use case, you require the HelloWorld.xsd files. You can copy this
file from the following location to "HelloWorldCompositexsd" under the project
HelloWorldComposite:
Also, copy request.xsl, reply.xsl, and invoke.xsl to
HelloWorldCompositexsl from the above location.
1. In Application Navigator of Oracle JDeveloper, click New Application. The
2. Enter helloworld-socket in the Application Name field, as shown in
Figure 5–30, and then click Next. The Name your project page is displayed.
Figure 5–30 The Create SOA Application Dialog
3. Click OK. The Name Your Project dialog is displayed.
4. Enter HelloWorldComposite in the Project Name field, and then select SOA
under Project Technologies and move it to the Selected box by clicking the
right-arrow, as shown in Figure 5–31.
The HelloWorld application and the HelloWorldComposite project appear in the
Application Navigator.

Figure 5–31 The Create Project Dialog
6. Select Composite With BPEL in the Composite Template box, as shown in
Figure 5–32, and click Finish. The Create BPEL Process dialog is displayed.
Figure 5–32 The Configure SOA Settings Dialog
7. Enter HelloWorldFlow in the Name field and select Define Service Later from
the Template box, as shown in Figure 5–33.

Figure 5–33 The Create BPEL Process Dialog
8. Click OK. The HelloWorld application and the HelloWorldComposite project
appear in the design area, as shown in Figure 5–34.
Figure 5–34 The Oracle JDeveloper - composite.xml
5.5.1.3 Creating the Inbound Oracle Socket Adapter Service
Perform the following steps to create an inbound Oracle Socket Adapter service:
displayed.

3. Enter HelloWorldClient in the Service Name field, as shown in Figure 5–35.
Figure 5–35 The Adapter Configuration Wizard Service Name Page
Figure 5–36 and click Next. The Operation page is displayed.
Figure 5–36 The Adapter Configuration Wizard - Adapter Interface Page

6. Select Inbound Synchronous Request/Reply as the Operation Type, as shown in
Figure 5–37.
7. Click Next. The Socket Connection page is displayed.
displayed.
Figure 5–38 The Adapter Configuration Wizard Socket Connection Page

13. Click Project Schema Files, HelloWorld.xsd, and HelloWorldProcessRequest.

Figure 5–40 The Adapter Configuration Wizard File Messages Page
17. Click Browse to select the XSL file that appears at the end of the Xslt field. The
SOA Resource Browser dialog is displayed.
18. Select request.xsl as the file name, as shown in Figure 5–41, and click OK. The Xslt
field is populated.
Figure 5–41 The SOA Resource Browser Dialog

19. Click Browse to select the XSL file that appears at the end of the ReplyXslt field.
The SOA Resource Browser dialog is displayed.
20. Select reply.xsl as the file name and click OK. The Xslt field is populated, as
Figure 5–42 The Adapter Configuration Wizard Protocol Page
21. Click Finish. The composite.xml page appears, as shown in Figure 5–43.
Figure 5–43 The Oracle JDeveloper - composite.xml Page
5.5.1.4 Creating the Outbound Oracle Socket Adapter Service
Perform the following steps to create an outbound Oracle Socket Adapter service:

1. Drag and drop Socket Adapter from the Component Palette to the External
displayed.
3. Enter HelloWorldServer in the Service Name field.
6. Select Outbound Synchronous Request/Reply as the operation type, as shown in
Figure 5–44.
Figure 5–44 The Adapter Configuration Wizard Operation Type Page
displayed.

18. Select invoke.xsl as the file name, as shown in Figure 5–46, and click OK. The Xslt
field is populated.

19. Click Finish. The Composite.xml page appears, as shown in Figure 5–47.

1. Drag the small triangle in the HelloWorldClient in the Exposed Services area to
the drop zone that appears as a green triangle in the HelloWorldFlow BPEL
process in the Components area.
2. Drag the small triangle in the HelloWorldFlow BPEL process in the Components
area to the drop zone that appears as a green triangle in the HelloWorldServer in
the External References area.
4. Double-click HelloWorldFlow. The BPELHelloWorld.bpel page is displayed.
5. Drag and drop a Receive activity from the Component Palette to the design area,

Figure 5–49 The Oracle JDeveloper - HelloWorldFlow.bpel
7. Enter ReceiveInput in the Name field, as shown in Figure 5–50.
9. Select HelloWorldClient, as shown in Figure 5–51, and click OK.

11. Select the default variable name and click OK. The Variable field is populated
with the default variable name.
HelloWorldFlow.bpel page appears, as shown in Figure 5–53.

1. Drag and drop an Invoke activity after the ReceiveInput activity from the
Component Palette to the design area, as shown in Figure 5–54.

3. Enter WriteHelloWorld in the Name field, as shown in Figure 5–55.

5. Select HelloWorldServer, as shown in Figure 5–56, and click OK.
8. Repeat the same for selecting the output variable. The Invoke dialog is displayed,

9. Click OK. The Oracle JDeveloper HelloWorldFlow.bpel page appears, as shown in
Figure 5–58.
Add a Reply Activity
10. Drag and drop a Reply activity from the Component Palette to the design area, as

11. Double-click the Reply activity. The Reply dialog is displayed.
12. Enter Reply in the Name field.
14. Select HelloWorldClient, as shown in Figure 5–51, and click OK.
15. Click the Auto-Create Variable icon to the right of the Variable field in the Reply
the default variable name, as shown in Figure 5–60.

Figure 5–60 The Reply Dialog
17. Click OK. The Oracle JDeveloper HelloWorldFlow.bpel page appears, as shown in
Figure 5–61.
Add Assign Activities

Figure 5–62.
22. In the left pane, under the ReceiveInput_InboundRequestReply_InputVariable
variable select, ns3:input.
23. In the right pane, under the WriteHelloWorld_OutboundRequestReply_
InputVariable variable select, ns3:input as shown in Figure 5–63.
24. Click OK. The Assign dialog is displayed.
25. Click OK. The Oracle JDeveloper HelloWorldFlow.bpel page is displayed.
26. Add another Assign activity in between the Invoke and the Reply activities.
27. Double-click the assign activity.
28. Click the Copy Operation tab, and select Copy Operation.

29. In the left pane, select ns3:result under WriteHelloWorld_
OutboundRequestReply_OutputVariable.
30. In the right pane, select ns3:result under Reply_InboundRequestReply_
OutputVariable and click OK.
31. Click OK, the Oracle JDeveloper HelloWorldFlow.bpel page is displayed, as
5.5.1.7 Monitoring Using the Enterprise Manager Console

displayed.
5.5.2 Flight Information Display System
The Flight Information Display System use case demonstrates the various modes of
defining handshakes by using Oracle Socket Adapter.
A Flight Information Display Server (FIDS) is started by an FIDS client requesting
information on flight status for flights originating from a particular source, JFK, or
SFO. The FIDS, in turn, invokes flight data requests for three airlines, Airline1, Airline
2, and Airline 3. The FIDS then collates the information received and replies to the
FIDS client by using the HTTP protocol.
■ Section 5.5.2.3, "Creating the Inbound Oracle Socket Adapter Service"
■ Section 5.5.2.4, "Creating Outbound Oracle Socket Adapter Services"
■ Section 5.5.2.7, "Monitoring Using the Enterprise Manager Console"
To perform this use case, you require the Airline1.xsd, Airline2.xsd,
Airline3.xsd, and FIDS.xsd files. You also require the invoke.xsl,
request.xsl, and reply.xsl files. These file can be copied from the following
location:
application and a project for the use case, perform the following steps:
2. Enter FIDSApp in the Application Name field, and then click Next. The Name
your project page is displayed.
3. Click OK. The Name Your Project dialog is displayed.
4. Enter FIDSComposite in the Project Name field, and then select SOA under
Project Technologies and move it to the Selected box by clicking the right-arrow.
The FIDSApp application and the FIDSComposite project appear in the
Application Navigator.

5. Click Next. The Configure SOA Settings dialog appears.
The Create BPEL Process dialog is displayed.
7. Enter BPEL_FIDS in the Name field and select Define Service Later from the
Template box.
8. Click OK. The FIDSApp application and the FIDSComposite project appear in the
design area, as shown in Figure 5–65.
Copy the Airline1.xsd, Airline2.xsd, Airline3.xsd, and FIDS.xsd files
from the following location to FIDSCompositexsd under the project
FIDSComposite:
Also, copy invoke.xsl, request.xsl, and reply.xsl to FIDSCompositexsl
from the location mentioned.
5.5.2.3 Creating the Inbound Oracle Socket Adapter Service
Perform the following steps to create an inbound Oracle Socket Adapter service that
would be used to expose the FIDSApp application:
displayed.
3. Enter FIDS in the Service Name field.

6. Select Inbound Synchronous Request/Reply as the operation type.
Name field and then select Specify Host and Port, as shown in Figure 5–66.
9. Enter 9000 in the PortNumber field and click Next. The Messages page is
displayed.
11. Click Project Schema Files, FIDS.xsd, and FIDSProcessRequest, as shown in
Figure 5–67.

12. Click OK. The URL field in the Messages page is populated with the FIDS.xsd file.
14. Click Project Schema Files, FIDS.xsd, and FIDSProcessReply.
15. Click OK. The URL fields in the Messages page are populated with the FIDS.xsd
files, as shown in Figure 5–68.
Figure 5–68 The Adapter Configuration Wizard - Messages Page

18. Click the Browse to select the XSL file icon that appears at the end of the Xslt
field. The SOA Resource Browser dialog is displayed.
19. Select request.xsl as the file name and click OK. The Xslt field is populated.
20. Click the Browse to select the XSL file icon that appears at the end of the
ReplyXslt field. The SOA Resource Browser dialog is displayed.
21. Select reply.xsl as the file name and click OK. The Xslt field is populated as shown
in Figure 5–69.

5.5.2.4 Creating Outbound Oracle Socket Adapter Services
Perform the following steps to create an outbound Oracle Socket Adapter service for
the Airline1 server socket:
displayed.
3. Enter Airline1 in the Service Name field.
6. Select Outbound Synchronous Request/Reply as the Operation Type.
Name field, as shown in Figure 5–71, and then select Specify Host and Port.

Figure 5–71 The Adapter Configuration Wizard - Socket Connection Page
9. Enter the name of the system where the Airline1 socket server program must run
in the HostName field and 9001 in the PortNumber field, and click Next. The
Messages page is displayed.
11. Click Project Schema Files, Airline1.xsd, and Source.
12. Click OK. The URL field in the Messages page is populated with the Airline1.xsd
file.
14. Click Project Schema Files, Airline1.xsd, and Flight-Details.
Airline1.xsd files, as shown in Figure 5–72.

19. Select invoke.xsl as the file name, as shown in Figure 5–73, and click OK. The Xslt
field is populated.
20. Click Finish. The composite.xml page appears as shown in Figure 5–74.

displayed.
6. Select Outbound Synchronous Request/Reply as the operation type.
Name field and then select Specify Host and Port.
11. Click Project Schema Files, Airline2.xsd, and Source.
file.
14. Click Project Schema Files, Airline2.xsd, and flight-details.

Airline2.xsd files.
17. Select No Handshake.
18. Click Finish. The composite.xml page appears as shown in Figure 5–75.
displayed.
6. Select Outbound Synchronous Request/Reply as the operation type.
Name field and then select Specify Host and Port.

11. Click Project Schema Files, Airline3.xsd, and src.
file.
14. Click Project Schema Files, Airline3.xsd, and airline.
Airline3.xsd files.
17. Select Use Custom Java Code to define the handshake.
18. Enter com.oracle.socket.fids.custom.Airline3Custom in the Java Class
field.
You have to assemble or wire the components that you have created: Inbound adapter
service, BPEL process, Outbound adapter references. Perform the following steps to
wire the components:
1. Drag the small triangle in the FIDS client in the Exposed Services area to the drop
zone that appears as a green triangle in the BPEL_FIDS process in the Components
area.
2. Drag the small triangle in the BPEL_FIDS process in the Components area to the
drop zone that appears as a green triangle in the Airline1, Airline2, and Airline3
servers in the External References area.
The Oracle JDeveloper composite.xml file appears, as shown in Figure 5–77.

4. Double-click BPEL_FIDS. The BPELFIDS.bpel page is displayed.
7. Retain the default name Receive_1 in the Name field.
9. Select FIDS, as shown in Figure 5–78, and click OK.

with the default variable name.
12. Check Create Instance, and click OK. The Oracle JDeveloper BPEL_FIDS.bpel
page appears, as shown in Figure 5–80.

Figure 5–80 The Oracle JDeveloper - BPEL_FIDS.bpel
Add a Reply Activity
13. Drag and drop an Reply activity from the Component Palette to the design area,

14. Double-click the Reply activity. The Reply dialog is displayed.
15. Retain the default name Reply_1 in the Name field.
17. Select FIDS, as shown in Figure 5–78, and click OK.
18. Click the Auto-Create Variable icon to the right of the Variable field in the Reply
with the default variable name, as shown in Figure 5–82.
Figure 5–82 The Reply Dialog
20. Click OK. The Oracle JDeveloper BPEL_FIDS.bpel page appears, as shown in
Figure 5–83.

Add a Flow Activity
21. Drag and drop a Flow activity from the Component Palette in between the Receive
and the Reply activities in the design area, as shown in Figure 5–84.
22. Expand the Flow_1 activity. This displays a screen to create sequences.

Design the Flow for Airline1 Server
23. Drag and drop a Switch activity from the Component Palette to Sequence_1, as
Figure 5–85 The Oracle JDeveloper - BPEL_FIDS.bpel Page
and <otherwise>.
25. In the <case> section, click the View Condition Expression icon, as shown in
Figure 5–86. The Condition Expression pop-up window is displayed.

Figure 5–86 The Oracle JDeveloper - BPEL_FIDS.bpel Page
27. Enter boolean(bpws:getVariableData('Receive_1_
InboundRequestReply_
InputVariable','FIDSProcessRequest','/ns5:FIDSProcessRequest/
ns5:AirlineName')='Airline1') as the expression, as shown in Figure 5–87,
and click OK. The screen returns to the Condition Expression pop-up window.
Note: This expression ensures that this flow is executed only when
information for Airline1 is requested.

Figure 5–87 The Expression Builder Dialog
28. Add an invoke activity to the <case> section.
a. Drag and drop an Invoke activity in the <case> section.
b. Double-click the Invoke activity. The Invoke dialog is displayed.
c. Click Browse Partner Links at the end of the Partner Link field. The Partner
Link Chooser dialog is displayed.
d. Select Airline1, and click OK.
e. Click the Automatically Create Input Variable and the Automatically Create
Output Variable icons to the right of the Input and Output Variable fields in
the Invoke dialog. The Create Variable dialogs are displayed.
f. Select the default variable names and click OK. The Variable fields are
populated with the default variable name. The Invoke dialog is displayed.
g. Click OK. The Oracle JDeveloper BPEL_FIDS.bpel page is displayed, as

29. Add an assign activity to the <case> section.
a. Drag and drop an Assign activity from the Component Palette before the
Invoke_1 activity in the <case> section.
b. Double-click the Assign_1 activity. The Assign dialog is displayed.
c. Click the Copy Operation tab. The Assign dialog is displayed.
d. Select Copy Operation. The Create Copy Operation dialog is displayed.
e. Create the copy operation between the source from the input variable of the
Receive_1 activity and the source from the input variable of the Invoke_1
activity, as shown in Figure 5–89.

f. Click OK in the Create Copy Operation dialog.
g. Click OK.
The BPEL_FIDS.bpel page is displayed, as shown in Figure 5–90.
Figure 5–90 The Oracle JDeveloper - BPELFIDS.bpel
30. Add a Transform activity to the <case> section.

a. Drag and drop a Transform activity in the <case> section, after the Invoke_1
activity.
b. Double-click the Transform activity.
c. Click the Transformation tab.
d. Click the Create...(Alt+N) icon. The Source Variable dialog is displayed.
e. Select Invoke_1_OutboundRequestReply_OutputVariable from the Source
Variable list and click OK.
f. Select Reply_1_InboundRequestReply_OutputVariable from the Target
Variable list.
g. Click OK. The XSL mapper is displayed.
h. Link the tns:Flight node from the source, on the left pane to the target
FlightDetails node on the right pane. The Auto Map Preferences dialog
appears.
i. Click OK. The Transformation_1.xsl (XSL mapper) is displayed, as shown in
Figure 5–91.
Figure 5–91 The Oracle JDeveloper - Transformation_1.XSL Page
31. Click File, Save All. The BPEL_FIDS.bpel page is displayed, as shown in
Figure 5–92, with the flow defined for the Airline1 server.

32. Double-click the empty Sequence activity and enter Sequence_2 in the Name
field.
33. Drag and drop a Switch activity from the Component Palette to Sequence_2.
and <otherwise>.
35. In the <case> section, click the View Condition Expression icon. The Condition
Expression pop-up window is displayed.
ns5:AirlineName')='Airline2') as the expression, and click OK. The
b. Double-click the Invoke_2 activity. The Invoke dialog is displayed.

e. Click the Automatically Create Input Variable and the Automatically Create
Output Variable icons to the right of the Input and Output Variable fields in
the Invoke dialog. The Create Variable dialogs are displayed.
f. Select the default variable names and click OK. The Input and Output Variable
fields are populated with the default variable names. The Invoke dialog is
displayed.
g. Click OK. An Invoke activity is added to the Oracle JDeveloper BPEL_
FIDS.bpel page under Sequence_2.
a. Drag and drop an Assign activity from the Component Palette before the
Invoke activity in the <case> section.
b. Double-click the Assign_2 activity. The Assign dialog is displayed.
c. Click the Copy Operation tab. The Assign dialog is displayed.
d. Select Copy Operation. The Create Copy Operation dialog is displayed.
e. Create the copy operation between the source from the input variable of the
f. Click OK in the Create Copy Operation dialog.
g. Click OK.
40. Create a temporary variable and add a Transform activity to the <case> section.

a. Click the Variables... icon represented by (x). The Variables dialog is displayed
b. Click the Create... icon. The Create Variable dialog is displayed as shown in
Figure 5–95.
Note: The temporary variable is used for storing flight details from
the Airline2 server, which would later be appended to the reply
variable.

Figure 5–95 The Create Variable Dialog
c. Select Message Type as the variable type.
d. Click the Browse Message Types icon at the end of the Message Type field.
The Type Chooser dialog is displayed.
e. Click Message Types, Partner Links, FIDS, FIDS.wsdl, Message Types, and
then FIDSProcessReply_msg_reply, as shown in Figure 5–96.
f. Click OK. The Message type field in the Create Variable dialog is populated
with the FIDSProcessReply_msg_reply partner link.

g. Click OK. A variable, Variable_1, of type Message Type is added to the
Variables list in the Variable dialog.
h. Click OK to return to the BPEL_FIDS.bpel page.
i. Drag and drop a Transform activity in the <case> section, after the Invoke_2
activity.
j. Double-click the Transform_2 activity.
k. Click the Transformation tab.
l. Click the Create... icon. The Source Variable dialog is displayed.
m. Select Invoke_2_OutboundRequestReply_OutputVariable from the Source
n. Select Variable_1 from the Target Variable list.
o. Click OK. The XSL mapper is displayed.
p. Link the tns:flight node from the source, on the left pane to the target
appears as shown in Figure 5–97.
Figure 5–97 The Transformation_2.XSL Page With Auto Map Preference Dialog
q. Click OK. The Transformation_2.xsl (XSL mapper) file with the XSL mapping
is displayed.
The BPEL_FIDS.bpel page is displayed, as shown in Figure 5–98, with the flow
defined for the Airline2 server.

42. Right-click the Flow_1 activity. Click Add Sequence from the menu. Sequence_3
is added.
43. Drag and drop a Switch activity from the Component Palette to Sequence_3.
and <otherwise>.
45. In the <case> section, click the View Condition Expression icon. The Condition
Expression pop-up window is displayed.
ns5:AirlineName')='Airline3') as the expression, and click OK. The
b. Double-click the Invoke_3 activity. The Invoke dialog is displayed.

e. Click the Automatically Create Input Variable and Automatically Create
Output Variable icon to the right of the Input and Output Variable field in the
Invoke dialog. The Create Variable dialogs are displayed.
f. Select the default variable names and click OK. The Input and Output Variable
fields are populated with the default variable names. The Invoke dialog is
displayed.
g. Click OK. An Invoke activity is added to Oracle JDeveloper BPEL_FIDS.bpel
page under Sequence_3.
h. Drag and drop an Assign activity from the Component Palette before the
Invoke activity in the <case> section.
i. Double-click the Assign_3 activity. The Assign dialog is displayed.
j. Click the Copy Operation tab. The Assign dialog is displayed.
k. Select Copy Operation. The Create Copy Operation dialog is displayed.
l. Create the copy operation between the source from the input variable of the
m. Click OK in the Create Copy Operation dialog.
n. Click OK.
50. Create a temporary variable and add a Transform activity to the <case> section.
a. Click the Variables... icon represented by (x). The Variables dialog is displayed
Note: The temporary variable is used for storing flight details from
the Airline3 server, which would later be appended to the reply
variable.

b. Click the Create... icon. The Create Variable dialog is displayed.
c. Select Message Type as the variable type.
d. Click the Browse Message Types icon at the end of the Message Type field.
e. Click Message Types, Partner Links, FIDS, FIDS.wsdl, Message Types, and
then FIDSProcessReply_msg_reply, as shown in Figure 5–96.
f. Click OK. The Message type field in the Create Variable dialog is populated
with the FIDSProcessReply_msg_reply partner link.
g. Click OK. A variable, Variable_2, of type Message Type is added to the
Variables list in the Variable dialog.
h. Click OK to return to the BPEL_FIDS.bpel page.
i. Drag and drop a Transform activity in the <case> section, after the Invoke_3
activity.
j. Double-click the Transform_3 activity.
k. Click the Transformation tab.
l. Click the Create... icon. The Source Variable dialog is displayed.
m. Select Invoke_3_OutboundRequestReply_OutputVariable from the Source
n. Select Variable_2 from the Target Variable list.
o. Click OK. The XSL mapper is displayed.
p. Link the tns:flight node from the source, on the left pane to the target
appears.

q. Click OK. The Transformation_3.xsl (XSL mapper) file with the XSL mapping
is displayed, as shown in Figure 5–101.
Figure 5–101 The Transformation_3.XSL Page
51. Click File, Save All. The BPEL_FIDS.bpel page is displayed, as shown in
Figure 5–102, with the flow defined for the Airline3 server.
Reply and Receive activities in the design area.
53. Double-click the Assign_4 activity. The Assign dialog is displayed.
Figure 5–103.

55. Select Append Operation. The Create Append Operation dialog is displayed.
56. Create an append operation to append the information stored in the temporary
variable, Variable_1, to the reply variable, Reply_1_
InboundRequestReply_OutputVariable, as shown in Figure 5–104.
Figure 5–104 The Create Append Operation Dialog
58. Select Append Operation. The Create Append Operation dialog is displayed.
59. Create another append operation to append the information stored in the
temporary variable, Variable_2, to the reply variable, Reply_1_
InboundRequestReply_OutputVariable, as shown in Figure 5–105.

Figure 5–105 The Create Append Operation Dialog
61. Click OK. The Oracle JDeveloper BPEL_FIDS.bpel page is displayed, as shown in
Figure 5–106.

You must run the Server and Client java programs to test the application. For more
information, see the associated README file.
5.5.2.7 Monitoring Using the Enterprise Manager Console

displayed.

Native Format Builder Wizard 6-1
6
Native Format Builder Wizard
This chapter describes the Native Format Builder Wizard, which enables you to create
native schemas used for translation. It includes use cases and constructs for the
schema.
■ Section 6.1, "Creating Native Schema Files with the Native Format Builder Wizard"
■ Section 6.2, "Native Schema Constructs"
■ Section 6.3, "Translator XPath Functions"
■ Section 6.4, "Use Cases for the Native Format Builder"
6.1 Creating Native Schema Files with the Native Format Builder Wizard
Oracle JCA Adapters are software components that enable the integration between
various enterprise information systems (EIS’) and Oracle BPEL Process Manager
(BPEL PM), or Oracle Mediator (Mediator). Adapters accept native messages in XML
or non-XML format and publish them to BPEL PM or Mediator as XML messages.
Adapters can also accept XML messages and convert them back to native EIS format.
This translation from native data format to XML and back is performed using a
definition file (non-XML schema definition), which itself is defined in XML schema
format. The Native Format Builder wizard enables you to sample native data and
create the native XSD (NXSD) grammar for translation of native data.
When you click the Define Schema for Native Format button in the Messages page of
the Adapter Configuration Wizard shown in Figure 6–1, the Native Format Builder
wizard is displayed. The Messages page is the last page that is displayed in the
Adapter Configuration Wizard before the Finish page.

Creating Native Schema Files with the Native Format Builder Wizard
Figure 6–1 Starting the Native Format Builder Wizard
6.1.1 Supported File Formats
The Native Format Builder wizard guides you through the creation of a native schema
file from the following file formats shown in Figure 6–2. You must have a sample data
file format for the selected type to create a native schema. You can also select the
option for editing an existing native schema created with this wizard, except for those
generated from a Document Type Definition (DTD) or COBOL Copybook file types.
For information on editing the native schema file, see Section 6.1.2, "Editing Native
Schema Files."
Figure 6–2 Native Format Builder Wizard

6.1.1.1 Delimited
This option enables you to create native schemas for records, where the fields are
separated by a value such as a comma or number sign (#).
6.1.1.2 Fixed Length (Positional)
This option enables you to create native schemas for records, where all fields are of
fixed lengths.
6.1.1.3 Complex Type
This option enables you to create native schema for records, where the fields may
themselves be records having multiple delimiter types.
6.1.1.4 DTD
This option enables you to generate native schema from the user-supplied DTD, which
contains information about the structure of an XML document.
6.1.1.5 COBOL Copybook
This option enables you to generate native schema from the user-supplied COBOL
Copybook definition.
A COBOL mainframe application typically uses a COBOL Copybook file to define its
data layout. The converter creates a native schema from a COBOL Copybook so that
the run-time translator can parse the associated data file.
A COBOL Copybook is typically a collection of group items (structures). These group
items contain other items, which can be groups or elementary items. Elementary items
are items that cannot be further subdivided. For example:
01 Purchase-Order
05 Buyer
10 BuyerName PIC X(5) USAGE DISPLAY.
04 Seller
08 SellerName PICTURE XXXXX.
Purchase-order is a group item with two child group items (Buyer, Seller). The
numbers 01, 05, 04, and so on indicate the level of the group (that is, the hierarchy of
data within that group).
Groups can be defined that have different level-numbers for the same level in the
hierarchy. For example, Buyer and Seller have different level numbers, but are at
the same level in the hierarchy. A group item includes all group and elementary items
that follow it until a level number less than or equal to the level number of that group
is encountered.
Each of the group items (Buyer and Seller) has a child elementary item. The PIC or
PICTURE clause defines the data layout. For example, BuyerName defines an
alphanumeric type of size equal to five characters. SellerName has the same data
layout as BuyerName.
Group items in COBOL can be mapped to elements in XML schema with the
complexType type. Similarly, elementary items can be mapped to elements of type
simple type with certain native format annotations to help the run-time translator
parse the corresponding data file.
For example, the Buyer item can be mapped to the following definition:

<element name="Buyer">
<complexType>
<sequence>

<element name="Name" type="string" nxsd:style="fixedLength"
nxsd:padStyle="tail" nxsd:paddedBy=" " nxsd:length="5"/>
</sequence>
</complexType>
</element>
User Inputs
You are expected to provide the following information:
■ Target namespace for the native schema to be generated
■ Character set of the host computer on which the data file was generated. By
default, this is set to EBCDIC (ebcdic-cp-us).
■ Byte order of the host computer on which the data file was generated. By default,
this is set to big-endian.
■ Record delimiter, which is typically the new line character, or no delimiter, or any
user-supplied string.
■ Container tag name for generated native schema. By default, this is set to
Root-Element.
COBOL Clauses
Table 6–1 describes COBOL clauses. The numeric types covered in Table 6–1 are stored
as one character per digit. Support for clauses is defined as follows:
■ Y indicates that the clause is supported.
■ N indicates that the clause is not supported.
■ I indicates that the clause is ignored.
Table 6–1 COBOL Clauses (Numeric Types Stored as One Character Per Digit)
COBOL
Clause
Design-Time
Support
Run-Time
Support
Supported
Synonyms Comments
PIC X(n) Y Y XXX… Alphanumeric – An allowable
character from the character set of
the computer. Each X corresponds to
one byte.
PIC A(n) Y Y AA… Alphabetic – Any letter of the
alphabet or space. Each A
corresponds to one byte.
PIC 9(n)
DISPLAY
Y Y 9999… Any character position that contains
a numeral. Each nine is counted in
the size of the item.
OCCURS n
TIMES
Y Y Fixed-length array
JUSTIFIED Y Y For A and X types. Right justifies
with the space pad. Data is aligned
at the rightmost character position.
REDEFINES Y Y Allows the same computer memory
area to be described by different
data items.

The numeric types described in Table 6–1 are stored as one character per digit.
Table 6–2 describes the numeric types that are stored in a more efficient manner.
PIC
9(m)V9(n)
DISPLAY
Y Y Size = n+m bytes
OCCURS
DEPENDING
ON
Y Y NA
BLANK WHEN
ZERO
I I Ignored
RENAMES N N This is rarely seen in COBOL
Copybooks
INDEX N N Four-byte index
SYNCHRONIZE
D
I I SYNC NA
POINTER N N NA
PROCEDURE-P
OINTER
NA
FILLER Y Y NA
Table 6–2 COBOL Clauses (Numeric Types Stored More Efficiently)
COBOL
Clause
Design-Time
Support
Run-Tim
e
Support
Supported
Synonyms Comments
USAGE [IS] Y Y Both these keywords are optional.
PIC 9(n)
COMP
Y Y COMPUTAT
IONAL,
BINARY,
COMP-4
Length varies with n:
■ n = 1-4 (2 bytes)
■ n = 5-9 (4 bytes)
■ n = 10-18 (8 bytes)
COMP-1 Y Y COMPUTAT
IONAL-1
Single precision, floating point number
that is four bytes long.
COMP-2 Y Y COMPUTAT
IONAL-2
Double precision, floating point
number that is eight bytes long.
PIC 9(n)
COMP-3
Y Y PACKED-D
ECIMAL,
COMPUTAT
IONAL-3
Two digits are stored in each byte. An
additional half byte at the end is
allocated for the sign, even if the value
is unsigned.
PIC 9(n)
COMP-4
Y Y COMPUTAT
IONAL-4
Treated the same as a COMP type and
given its own data type for
customizing requirements.
PIC 9(n)
COMP-5
N N Capacity of the native binary
representation.
PIC S9(n)
DISPLAY
Y Y PIC S99… Sign nibble in the rightmost zone by
default. S is not counted in the size.
Table 6–1 (Cont.) COBOL Clauses (Numeric Types Stored as One Character Per Digit)
COBOL
Clause
Design-Time
Support
Run-Time
Support
Supported
Synonyms Comments

The following clauses can be added to impact the sign position.
■ SIGN IS LEADING
Used with signed zoned numerics.
■ SIGN IS TRAILING
Used with signed zoned numerics.
■ SIGN IS LEADING SEPARATE
The character S is counted in the size.
■ SIGN IS TRAILING SEPARATE
The character S is counted in the size.
Table 6–3 describes picture editing types.
PIC S9(n)
COMP
Y Y Same as COMP. Negative numbers are
represented as two’s complement.
PIC S9(n)
COMP-3
Y Y NA
PIC
9(m)V9(n)
COMP
Y Y Length is the same as COMP.
PIC
9(m)V9(m)
COMP-3
Y Y Length = Ceiling ((n+m+1)/2)
Note: These assume that the numerics are stored using IBM COBOL
format. If these are generated for other platforms with different data
storage formats, then a custom data handler for that type must be
written.
Table 6–3 Edited Pictures
Edited Pictures Supported Editing Types Unsupported Editing Types
Edited
alphanumeric
Simple Insertion: B(blank) 0 / ,
Edited float
numeric
Special insertion: . (period)
Edited numeric ■ Simple Insertion: B(blank) 0
/ ,
■ Special insertion: . (period)
■ Fixed Insertion: cs + - CR
DB (Inserts a symbol at the
beginning or end)
■ Floating Insertion: cs + -
■ Zero suppression: Z *
■ Replacement insertion: Z * + -
c
Table 6–2 (Cont.) COBOL Clauses (Numeric Types Stored More Efficiently)
COBOL
Clause
Design-Time
Support
Run-Tim
e
Support
Supported
Synonyms Comments

Edited pictures are more for presentation purposes and are rarely seen in data files. It
is assumed that the editing symbols are also present in the data. For example, if you
have:
05 AMOUNT PIC 999.99
then, this field is six bytes wide and has a decimal point in the data.
Simple, special, and fixed insertions are handled by this method. Floating insertion,
zero suppression, and replacement insertion are not supported.
6.1.2 Editing Native Schema Files
You can edit an existing native schema generated using the Native Format Builder
wizard by sampling a delimited, fixed length, or complex type file. To edit an existing
native schema select the Edit existing option in the Choose Type page of the Native
Format Builder wizard, and click Browse to navigate to the location of the existing
schema file and then select the native schema file that must be edited. The Native
Format Builder wizard guides you through the editing of the native schema file.
Figure 6–3 shows the Native Format Builder - Choose Type page with the Edit existing
option selected.
Figure 6–3 The Native Format Builder Wizard - Choose Type Page
Before you edit a native schema file, you must ensure that the sample file specified in
the annotation within the schema exists. This annotation is automatically added when
the native schema is generated the first time from the sample file.
For example, if the specified sample file path in the annotation is
 and if the file is not located at the
path specified, then the wizard displays an error.
Note: You can not edit native schemas generated from a Document
Type Definition (DTD) or COBOL Copybook file types.

Native Schema Constructs
6.2 Native Schema Constructs
This section provides an overview of the various constructs of native schema used to
translate the native format data to XML and also explains the usage of these native
schema constructs.
■ Section 6.2.1, "Understanding Native Schema Constructs"
■ Section 6.2.2, "Using Native Schema Constructs"
6.2.1 Understanding Native Schema Constructs
Table 6–4 shows the constructs applicable only on the <schema> tag.
Table 6–4 Constructs Applicable Only on the <schema> Tag
Construct Description
byteOrder The byte order of the native data as bigEndian or
littleEndian.
encoding The encoding in which the actual data is stored. Any legal
encoding supported by java.io.InputStreamReader.
headerLines A positive integer specifying the number of lines to be skipped,
before translating the native data.
headerLinesTerminated
By
Skip until the specified string, before translating the native data.
standalone If declared, adds the standalone attribute in the XML declaration
prolog of the translated XML, with the actual value as that
specified in nxsd:standalone. Allowed values are true and
false.
stream Whether the data is stored as characters or bytes. Allowed
values are CHARS and BYTES.
uniqueMessageSeparato
r
String specifying the unique message separator in the native
data, in case of a batch of messages.
version The type of native data. Possible values are NXSD, DTD, XSD, and
OPAQUE.
xmlversion If declared, adds the XML declaration prolog to the translated
XML with the actual value as that specified in
nxsd:xmlversion. Allowed values are 1.0 and 1.1.
outboundHeader String specifying the header value to be inserted in the
outbound message.
dataLines Integer specifying the number of lines to process in the native
file.
fieldValidation If set to true, then translator performs data type validation on
the tokens read from the native.
validation If set to true, then the translator performs result validation both
on the inbound and outbound.
Note: The validation construct is supported for built in
simple types only.
validateNxsd If set to true, then a thorough native grammar validation is
performed. This construct is switched off by default and must be
switched off in production for better performance.

Table 6–5 shows the constructs applicable on all tags other than the <schema> tag.
useArrayIdentifiers If set to true, then it optimizes the native framework for
handling array identifiers. This may result in a performance hit
for very large payloads. By default, arrayIdentifiers are not
supported.
parseBom If set to true, then the byte order mark is looked for in the
native stream and encoding is derived from this.
encodeLineTerminators If set to true, then the semantic interpretation of ${eol} is
rn instead of n.
Table 6–5 Constructs Applicable On All Tags Other Than the <schema> Tag
arrayIdentifierLength The length of the array being stored in the native data occupying
the specified length
arrayLength The value of this construct is used as the length of the array,
which can also be a variable resolved to a valid number. This
value overrides any minOccurs and maxOccurs attributes of
the particle where it is specified. Use this feature as follows:
nxsd:style="array" nxsd:arrayLength="10"
This indicates that the array length is 10.
arrayTerminatedBy The last item in the array being terminated by the specified
string
assign Assigns a value to the variable that is declared
cellSeparatedBy The cells of the array in the native data being separated by the
specified string
choiceCondition Either fixedLength or terminated
conditionValue Matches the string read from the native stream for the
choiceCondition construct, against the specified string in the
conditionValue construct
dataLines The value specified in this construct is used to translate only a
portion of the data and not the entire data.
dateFormat A valid Java date format representing the date in the native data
identifierLength The number of characters and bytes in which the actual length of
the data is stored
itemSeparatedBy The items in the list being separated by the specified string
leftSurroundedBy,
rightSurroundedBy
The native data surrounded
length The length of the native data to be read. Used with fixed-length
style.
listTerminatedBy The last item in the list being terminated by the specified string
Table 6–4 (Cont.) Constructs Applicable Only on the <schema> Tag

6.2.2 Using Native Schema Constructs
■ Section 6.2.2.1, "Defining Fixed-Length Data"
■ Section 6.2.2.2, "Defining Terminated Data"
■ Section 6.2.2.3, "Defining Surrounded Data"
■ Section 6.2.2.4, "Defining Lists"
■ Section 6.2.2.5, "Defining Arrays"
■ Section 6.2.2.6, "Conditional Processing"
■ Section 6.2.2.7, "Defining Dates"
■ Section 6.2.2.8, "Using Variables"
■ Section 6.2.2.9, "Defining Prefixes and Suffixes"
■ Section 6.2.2.10, "Defining Skipping Data"
■ Section 6.2.2.11, "Defining fixed and default Values"
■ Section 6.2.2.12, "Defining write"
■ Section 6.2.2.13, "Defining LookAhead"
lookAhead Looks for a match ahead of the current position in the input
stream. If a match is found, then the node on which this
construct is specified is processed; otherwise, it is skipped. Use
this feature as follows:
nxsd:lookAhead="20" nxsd:lookFor="abc"
This indicates to skip 20 characters and look for the string abc
starting from that location. If this is found, then the node is
processed; otherwise, it is skipped.
paddedBy The string used for padding
padStyle head, tail, or none
quotedBy The native data being quoted by the specified string
skip Skips the specified number of bytes or characters
skipLines Skips the number of lines specified
skipUntil Skips until the string specified
startsWith Looks for the specified string in the native data. If it exists, then
proceeds with the element where it is specified; otherwise, skips
and processes the next element.
style The style used to read the native data from the input stream.
Allowed values are fixedLength, surrounded, terminated,
list, and array.
surroundedBy The native data being surrounded by the specified string
terminatedBy The native data being terminated by the string specified
variable Declares a single variable
variables Declares a set of variables or assigns the declared variables a
valid value
Table 6–5 (Cont.) Constructs Applicable On All Tags Other Than the <schema> Tag

■ Section 6.2.2.14, "Defining outboundHeader"
■ Section 6.2.2.15, "Defining Complex Condition in conditionValue"
■ Section 6.2.2.16, "Defining Complex Condition in choiceCondition"
■ Section 6.2.2.17, "Defining dataLines"
■ Section 6.2.2.18, "Defining Date Formats with Time Zone"
■ Section 6.2.2.19, "Implementing Validation During Translation"
■ Section 6.2.2.20, "Processing Files with BOM"
6.2.2.1 Defining Fixed-Length Data
Fixed-length data in the native format can be defined in the native schema by using
the fixed-length style. There are three types of fixed length:
■ With padding
■ Without padding
■ With the actual length also being read from the native data
Native Data Format to Be Translated: With Padding
The actual data may be less than the length specified. In this case, you can specify
paddedBy and padStyle as head or tail. When the data is read, the pads are
trimmed accordingly. The following is a sample native data to be translated:
GBP*UK000012550.00
Native Schema: With Padding
<?xml version="1.0" encoding="US-ASCII"?>
targetNamespace="http://www.oracle.com/ias/processconnect"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
nxsd:stream="chars"
nxsd:version="NXSD">
<element name="fixedlength">
<complexType>
<sequence>
<element name="currency_code" nxsd:style="fixedLength" nxsd:length="4"
nxsd:padStyle="tail" nxsd:paddedBy="*">
<simpleType>
<maxLength value="4" />
</restriction>
</simpleType>
</element>
<element name="country_code" nxsd:style="fixedLength" nxsd:length="2"
nxsd:padStyle="none">
<simpleType>
<length value="2" />
</restriction>
</simpleType>
</element>
<element name="to_usd_rate" nxsd:style="fixedLength" nxsd:length="12"
nxsd:padStyle="head" nxsd:paddedBy="0">

<simpleType>
</restriction>
</simpleType>
</element>
</sequence>
</complexType>
</element>
</schema>
Translated XML Using the Native Schema: With Padding
<fixedlength xmlns="http://www.oracle.com/ias/processconnect">
<currency_code>GBP</currency_code>
<country_code>UK</country_code>
<to_usd_rate>12550.00</to_usd_rate>
</fixedlength>
Native Data Format to Be Translated: Without Padding
To define a fixed-length data in native schema, you can use the fixed-length style. In
case the actual data is less than the length specified, the white spaces are not trimmed.
The following is a sample native data to be translated:
GBP*UK000012550.00
Native Schema: Without Padding
nxsd:stream="chars"
<complexType>
<sequence>
<element name="currency_code" nxsd:style="fixedLength" nxsd:length="4">
<simpleType>
</restriction>
</simpleType>
</element>
<element name="country_code" nxsd:style="fixedLength" nxsd:length="2">
<simpleType>
<length value="2" />
</restriction>
</simpleType>
</element>
<element name="to_usd_rate" nxsd:style="fixedLength" nxsd:length="12">
<simpleType>
</restriction>
</simpleType>

</element>
</sequence>
</complexType>
</element>
</schema>
Translated XML Using the Native Schema: Without Padding
<currency_code>GBP*</currency_code>
<country_code>UK</country_code>
<to_usd_rate>000012550.00</to_usd_rate>
</fixedlength>
Native Data Format to Be Translated: Actual Length Also Being Read from the
Native Data
When the length of the data is also stored in the native stream, this style is used to first
read the length, and subsequently read the data according to the length read. The
following is a sample native data to be translated:
03joe13DUZac.1HKVmIY
Native Schema: Actual Length Also Being Read from the Native Data
nxsd:stream="chars"
<complexType>
<sequence>
<element name="user" type="string" nxsd:style="fixedLength"
nxsd:identifierLength="2" />
<element name="encr_user" type="string" nxsd:style="fixedLength"
</sequence>
</complexType>
</element>
</schema>
Translated XML Using the Native Schema: Actual Length Also Being Read from
the Native Data
<user>joe</user>
<encr_user>DUZac.1HKVmIY</encr_user>
</fixedlength>
6.2.2.2 Defining Terminated Data
This format is used when the terminating mark itself is supposed to be treated as part
of the actual data and not as a delimiter. When it is not clear whether the mark is part
of actual data or not, you can use nxsd:quotedBy to be safe. Specifying
nxsd:quotedBy means that the corresponding native data may or may not be

quoted. If it is quoted, then the actual data is read from the begin quotation to the end
quotation as specified in nxsd:quotedBy. Otherwise, it is read until the
terminatedBy character is found.
Examples for the Optionally quoted and Not quoted scenarios are provided in the
following sections:
Native Data Format to Be Translated: Optionally Quoted
The following is a sample native data to be translated:
Fred,"2 Old Street, Old Town,Manchester",20-08-1954,0161-499-1718
Native Schema: Optionally Quoted
nxsd:stream="chars"
<element name="terminated">
<complexType>
<sequence>
<element name="PersonName" type="string" nxsd:style="terminated"
nxsd:terminatedBy="," />
<element name="Address" type="string" nxsd:style="terminated"
nxsd:terminatedBy="," nxsd:quotedBy="""/>
<element name="DOB" type="string" nxsd:style="terminated"
<element name="Telephone" type="string" nxsd:style="terminated"
nxsd:terminatedBy="${eol}" />
</sequence>
</complexType>
</element>
Translated XML Using the Native Schema: Optionally Quoted
<terminated xmlns="http://www.oracle.com/ias/processconnect">
<PersonName>Fred</PersonName>
<Address>2 Old Street, Old Town,Manchester</Address>
<DOB>20-08-1954</DOB>
<Telephone>0161-499-1718</Telephone>
</terminated>
Native Data Format to Be Translated: Not Quoted
This is used when the data is terminated by a particular string or character. The
following is a sample native data to be translated:
1020,16,18,,1580.00
Native Schema: Not Quoted

nxsd:stream="chars"
<complexType>
<sequence>
<element name="product" type="string" nxsd:style="terminated"
<element name="ordered" type="string" nxsd:style="terminated"
<element name="inventory" type="string" nxsd:style="terminated"
<element name="backlog" type="string" nxsd:style="terminated"
<element name="listprice" type="string" nxsd:style="terminated"
</sequence>
</complexType>
</element>
</schema>
Translated XML Using the Native Schema: Not Quoted
<terminated xmlns="http://www.oracle.com/ias/processconnect">
<product>1020</product>
<ordered>16</ordered>
<inventory>18</inventory>
<backlog></backlog>
<listprice>1580.00</listprice>
</terminated>
6.2.2.3 Defining Surrounded Data
This is used when the native data is surrounded by a mark.
The following are types of surrounded data:
■ Left and right surrounding marks are different.
■ Left and right surrounding marks are the same.
Native Data Format to Be Translated: Left and Right Surrounding Marks Are
Different
The following is a sample native data to be translated for which the left and the right
surrounding marks are different:
(Ernest Hemingway Museum){Whitehead St.}
Native Schema: Left and Right Surrounding Marks Are Different
xmlns:tns="http://www.oracle.com/ias/processconnect"
nxsd:stream="chars"
<element name="limstring">
<complexType>

<sequence>
<element name="Landmark" type="string" nxsd:style="surrounded"
nxsd:leftSurroundedBy="(" nxsd:rightSurroundedBy=")" />
<element name="Street" type="string" nxsd:style="surrounded"
nxsd:leftSurroundedBy="{" nxsd:rightSurroundedBy="}" />
</sequence>
</complexType>
</element>
</schema>
Translated XML Using the Native Schema: Left and Right Surrounding Marks Are
Different
<limstring xmlns="http://www.oracle.com/ias/processconnect">
<Landmark>Ernest Hemingway Museum</Landmark>
<Street>Whitehead St.</Street>
</limstring>
Native Data Format to Be Translated: Left and Right Surrounding Marks Are the
Same
The following is a sample native data to be translated for which the left and the right
surrounding marks are the same:
.FL..Florida Keys.+Key West+
Native Schema: Left and Right Surrounding Marks Are the Same
nxsd:stream="chars"
<element name="limstring">
<complexType>
<sequence>
<element name="State" type="string" nxsd:style="surrounded"
nxsd:surroundedBy="."/>
<element name="Region" type="string" nxsd:style="surrounded"
nxsd:surroundedBy="." />
<element name="City" type="string" nxsd:style="surrounded"
nxsd:surroundedBy="+" />
</sequence>
</complexType>
</element>
</schema>
Translated XML Using the Native Schema: Left and Right Surrounding Marks Are
the Same
<limstring xmlns="http://www.oracle.com/ias/processconnect">
<State>FL</State>
<Region>Florida Keys</Region>
<City>Key West</City>
</limstring>

6.2.2.4 Defining Lists
This format applies to lists with the following characteristics:
■ All Items Separated by the Same Mark, but the Last Item Terminated by a
Different Mark (Bounded)
■ All Items Separated by the Same Mark, Including the Last Item (Unbounded)
All Items Separated by the Same Mark, but the Last Item Terminated by a
Different Mark (Bounded)
The following sections explain the format of the data to be translated, the native
schema, and the translated XML.
Native Data Format to Be Translated:
125,200,255
Native Schema:
xmlns:tns="http://xmlns.oracle.com/pcbpel/nxsd/smoketest"
targetNamespace="http://xmlns.oracle.com/pcbpel/nxsd/smoketest"
nxsd:stream="chars"
<element name="list" type="tns:Colors" />
<complexType name="Colors" nxsd:style="list" nxsd:itemSeparatedBy=","
nxsd:listTerminatedBy="${eol}">
<sequence>
<element name="Red" type="string" />
<element name="Green" type="string" />
<element name="Blue" type="string" />
</sequence>
</complexType>
</schema>
Translated XML Using the Native Schema
<list xmlns="http://www.oracle.com/ias/processconnect">
<Red>125</Red>
<Green>200</Green>
<Blue>255</Blue>
</list>
All Items Separated by the Same Mark, Including the Last Item (Unbounded)
configure;startup;runtest;shutdown;

Native Schema:
xmlns:tns="http://xmlns.oracle.com/pcbpel/nxsd/smoketest"
nxsd:stream="chars"
<element name="list" type="tns:CommandSet" />
<complexType name="CommandSet" nxsd:style="list" nxsd:itemSeparatedBy=";">
<sequence>
<element name="Cmd1" type="string" />
</sequence>
</complexType>
</schema>
Translated XML Using the Native Schema:
<list xmlns="http://www.oracle.com/ias/processconnect">
<Cmd1>configure</Cmd1>
<Cmd2>startup</Cmd2>
<Cmd3>runtest</Cmd3>
<Cmd4>shutdown</Cmd4>
</list>
6.2.2.5 Defining Arrays
This is for an array of complex types where the individual cells are separated by a
separating character and the last cell of the array is terminated by a terminating
character.
The following are examples of array types:
■ All Cells Separated by the Same Mark, but the Last Cell Terminated by a Different
Mark (Bounded)
■ All Cells Separated by the Same Mark, Including the Last Cell (Unbounded)
■ Cells Not Separated by Any Mark, but the Last Cell Terminated by a Mark
(Bounded)
■ The Number of Cells Being Read from the Native Data
■ Explicit Array Length
All Cells Separated by the Same Mark, but the Last Cell Terminated by a Different
Mark (Bounded)
"Smith, John","1 Old Street, Old Town, Manchester",,"0161-499-1717".

Fred,"2 Old Street, Old Town,Manchester","20-08-1954","0161-499-1718".
"Smith, Bob",,,0161-499-1719.#
Native Schema:
nxsd:stream="chars"
nxsd:version="NXSD"
>
<element name="array">
<complexType>
<sequence>
<element name="Member" maxOccurs="unbounded"
nxsd:style="array" nxsd:cellSeparatedBy="${eol}"
nxsd:arrayTerminatedBy="#">
<complexType>
<sequence>
<element name="Name" type="string" nxsd:style="terminated"
nxsd:terminatedBy="," nxsd:quotedBy='"'/>
nxsd:terminatedBy="." nxsd:quotedBy='"'/>
</sequence>
</complexType>
</element>
</sequence>
</complexType>
</element>
</schema>
<array xmlns="http://www.oracle.com/ias/processconnect">
<Member>
<Name>Smith, John</Name>
<Address>1 Old Street, Old Town, Manchester</Address>
<DOB></DOB>
</Member>
<Member>
<Name>Fred</Name>
<DOB>20-08-1954</DOB>
</Member>
<Member>
<Name>Smith, Bob</Name>
<Address></Address>
<DOB></DOB>

</Member>
</array>
All Cells Separated by the Same Mark, Including the Last Cell (Unbounded)
"Smith, John","1 Old Street, Old Town, Manchester",,"0161-499-1717".
Fred,"2 Old Street, Old Town,Manchester","20-08-1954","0161-499-1718".
"Smith, Bob",,,0161-499-1719.
Native Schema:
nxsd:stream="chars"
<complexType>
<sequence>
nxsd:style="array" nxsd:cellSeparatedBy="rn">
<complexType>
<sequence>
nxsd:terminatedBy="." nxsd:quotedBy='"'/>
</sequence>
</complexType>
</element>
</sequence>
</complexType>
</element>
</schema>
<Member>
<DOB></DOB>
</Member>

<Member>
<Name>Fred</Name>
<DOB>20-08-1954</DOB>
</Member>
<Member>
<Address></Address>
<DOB></DOB>
</Member>
</array>
Cells Not Separated by Any Mark, but the Last Cell Terminated by a Mark
(Bounded)
"Smith, John","1 Old Street, Old Town, Manchester",,"0161-499-1717"
Fred,"2 Old Street, Old Town,Manchester","20-08-1954","0161-499-1718"
"Smith, Bob",,,0161-499-1719
#
Native Schema:
nxsd:stream="chars"
<complexType>
<sequence>
nxsd:style="array" nxsd:arrayTerminatedBy="#">
<complexType>
<sequence>
nxsd:terminatedBy="rn" nxsd:quotedBy='"'/>
</sequence>
</complexType>
</element>
</sequence>
</complexType>
</element>

</schema>
<Member>
<DOB></DOB>
</Member>
<Member>
<Name>Fred</Name>
<DOB>20-08-1954</DOB>
</Member>
<Member>
<Address></Address>
<DOB></DOB>
</Member>
</array>
The Number of Cells Being Read from the Native Data
3"Smith, John","1 Old Street, Old Town, Manchester",,"0161-499-1717"
"Smith, Bob",,,0161-499-1719
Native Schema:
nxsd:stream="chars"
<element name="arrayidentifierlength">
<complexType>
<sequence>
<element name="Member" maxOccurs="unbounded" nxsd:style="array"
nxsd:arrayIdentifierLength="1">
<complexType>
<sequence>

nxsd:terminatedBy="rn" nxsd:quotedBy='"'/>
</sequence>
</complexType>
</element>
</sequence>
</complexType>
</element>
</schema>
<arrayidentifierlength xmlns="http://www.oracle.com/ias/processconnect">
<Member>
<DOB></DOB>
</Member>
<Member>
<Name>Fred</Name>
<DOB>20-08-1954</DOB>
</Member>
<Member>
<Address></Address>
<DOB></DOB>
</Member>
</arrayidentifierlength>
Explicit Array Length
3;John;Steve;Paul;Todd;
Native Schema:
nxsd:stream="chars"
<annotation>
<appinfo>
<nxsd:variables>

<nxsd:variable name="len" />
</nxsd:variables>
</appinfo>
</annotation>
<complexType>
<sequence>
<element name="TotalMembers" type="string" nxsd:style="terminated"
nxsd:terminatedBy=";">
<annotation>
<appinfo>
<nxsd:variables>
<nxsd:assign name="len" value="${0}" />
</nxsd:variables>
</appinfo>
</annotation>
</element>
<element name="Member" type="string" minOccurs="0" maxOccurs="unbounded"
nxsd:style="array,terminated" nxsd:arrayLength="${len}"
nxsd:terminatedBy=";" />
</sequence>
</complexType>
</element>
</schema>
<array xmlns="http://xmlns.oracle.com/pcbpel/nxsd/smoketest">
<TotalMembers>3</TotalMembers>
<Member>John</Member>
<Member>Steve</Member>
<Member>Paul</Member>
</array>
6.2.2.6 Conditional Processing
This section provides the following examples of conditional processing:
■ Processing One Element Within a Choice Model Group Based on the Condition
■ Processing Elements Within a Sequence Model Group Based on the Condition
Processing One Element Within a Choice Model Group Based on the Condition
PO28/06/2004^|ABCD Inc.|Oracle
OracleApps025070,000.00
Database 021230,000.00
ProcessCon021040,000.00
PO01/07/2004^|EFGH Inc.|Oracle
Websphere 025070,000.00
DB2 021230,000.00
Eclipse 021040,000.00
SO29/06/2004|Oracle Apps|5
Navneet Singh

PO28/06/2004^|IJKL Inc.|Oracle
Weblogic 025070,000.00
Tuxedo 021230,000.00
JRockit 021040,000.00
IN30/06/2004;Navneet Singh;Oracle;Oracle Apps;5;70,000.00;350,000.00
Native Schema:
nxsd:stream="chars"
<element name="container">
<complexType>
<choice maxOccurs="unbounded" nxsd:choiceCondition="fixedLength"
nxsd:length="2">
<element ref="tns:PurchaseOrder" nxsd:conditionValue="PO" />
<element ref="tns:SalesOrder" nxsd:conditionValue="SO" />
<element ref="tns:Invoice" nxsd:conditionValue="IN" />
</choice>
</complexType>
</element>

<element name="PurchaseOrder" type="tns:POType"/>
<complexType name="POType">
<sequence>
<element name="Date" type="string" nxsd:style="terminated"
nxsd:terminatedBy="^" />
<element name="Buyer" type="string" nxsd:style="surrounded"
nxsd:surroundedBy="|" />
<element name="Supplier" type="string" nxsd:style="terminated"
<element name="Items">
<complexType>
<sequence>
<element name="Line-Item" minOccurs="3" maxOccurs="3">
<complexType>
<group ref="tns:LineItems" />
</complexType>
</element>
</sequence>
</complexType>
</element>
</sequence>
</complexType>
<group name="LineItems">

<sequence>
<element name="Id" type="string" nxsd:style="fixedLength" nxsd:length="10"
nxsd:padStyle="none"/>
<element name="Quantity" type="string" nxsd:style="fixedLength"
<element name="Price" type="string" nxsd:style="terminated"
</sequence>
</group>

<element name="SalesOrder" type="tns:SOType" />
<complexType name="SOType">
<sequence>
nxsd:terminatedBy="|" />
<element name="Item" type="string" nxsd:style="terminated"
<element name="Quantity" type="string" nxsd:style="terminated"
<element name="Buyer" type="string" nxsd:style="terminated"
</sequence>
</complexType>

<element name="Invoice" type="tns:INVType" />
<complexType name="INVType">
<sequence>
<element name="Purchaser" type="string" nxsd:style="terminated"
<element name="Seller" type="string" nxsd:style="terminated"
<element name="TotalPrice" type="string" nxsd:style="terminated"
</sequence>
</complexType>
</schema>
<container xmlns="http://www.oracle.com/ias/processconnect">
<PurchaseOrder>
<Date>28/06/2004</Date>
<Buyer>ABCD Inc.</Buyer>
<Supplier>Oracle</Supplier>
<Items>
<Line-Item>
<Id>OracleApps</Id>
<Quantity>50</Quantity>

<Price>70,000.00</Price>
</Line-Item>
<Line-Item>
<Id>Database </Id>
</Line-Item>
<Line-Item>
<Id>ProcessCon</Id>
</Line-Item>
</Items>
</PurchaseOrder>
<PurchaseOrder>
<Date>01/07/2004</Date>
<Buyer>EFGH Inc.</Buyer>
<Items>
<Line-Item>
<Id>Websphere </Id>
</Line-Item>
<Line-Item>
<Id>DB2 </Id>
</Line-Item>
<Line-Item>
<Id>Eclipse </Id>
</Line-Item>
</Items>
</PurchaseOrder>
<SalesOrder>
<Date>29/06/2004</Date>
<Item>Oracle Apps</Item>
<Buyer>Navneet Singh</Buyer>
</SalesOrder>
<PurchaseOrder>
<Date>28/06/2004</Date>
<Buyer>IJKL Inc.</Buyer>
<Items>
<Line-Item>
<Id>Weblogic </Id>
</Line-Item>
<Line-Item>
<Id>Tuxedo </Id>
</Line-Item>
<Line-Item>
<Id>JRockit </Id>

</Line-Item>
</Items>
</PurchaseOrder>
<Invoice>
<Date>30/06/2004</Date>
<Purchaser>Navneet Singh</Purchaser>
<Seller>Oracle</Seller>
<Price>5</Price>
<Quantity>70,000.00</Quantity>
<TotalPrice>350,000.00</TotalPrice>
</Invoice>
</container>
Processing Elements Within a Sequence Model Group Based on the Condition
PO28/06/2004^|ABCD Inc.|Oracle
OracleApps025070,000.00
Database 021230,000.00
ProcessCon021040,000.00
PO01/07/2004^|EFGH Inc.|Oracle
Websphere 025070,000.00
DB2 021230,000.00
Eclipse 021040,000.00
SO29/06/2004|Oracle Apps|5
Navneet Singh
PO28/06/2004^|IJKL Inc.|Oracle
Weblogic 025070,000.00
Tuxedo 021230,000.00
JRockit 021040,000.00
IN30/06/2004;Navneet Singh;Oracle;Oracle Apps;5;70,000.00;350,000.00
Native Schema:
nxsd:stream="chars"
<element name="container">
<complexType>
<sequence maxOccurs="unbounded">
<element ref="tns:PurchaseOrder" minOccurs="0" nxsd:startsWith="PO" />
<element ref="tns:SalesOrder" minOccurs="0" nxsd:startsWith="SO" />
<element ref="tns:Invoice" minOccurs="0" nxsd:startsWith="IN" />

</sequence>
</complexType>
</element>

<element name="PurchaseOrder" type="tns:POType"/>
<complexType name="POType">
<sequence>
nxsd:terminatedBy="^" />
<element name="Buyer" type="string" nxsd:style="surrounded"
nxsd:surroundedBy="|" />
<element name="Supplier" type="string" nxsd:style="terminated"
<element name="Items">
<complexType>
<sequence>
<element name="Line-Item" minOccurs="3" maxOccurs="3">
<complexType>
<group ref="tns:LineItems" />
</complexType>
</element>
</sequence>
</complexType>
</element>
</sequence>
</complexType>
<group name="LineItems">
<sequence>
<element name="Id" type="string" nxsd:style="fixedLength" nxsd:length="10"
nxsd:padStyle="none"/>
<element name="Quantity" type="string" nxsd:style="fixedLength"
</sequence>
</group>

<element name="SalesOrder" type="tns:SOType" />
<complexType name="SOType">
<sequence>
<element name="Buyer" type="string" nxsd:style="terminated"
</sequence>
</complexType>

<element name="Invoice" type="tns:INVType" />

<complexType name="INVType">
<sequence>
<element name="Purchaser" type="string" nxsd:style="terminated"
<element name="Seller" type="string" nxsd:style="terminated"
<element name="TotalPrice" type="string" nxsd:style="terminated"
</sequence>
</complexType>
</schema>
<container xmlns="http://www.oracle.com/ias/processconnect">
<PurchaseOrder>
<Date>28/06/2004</Date>
<Buyer>ABCD Inc.</Buyer>
<Items>
<Line-Item>
<Id>OracleApps</Id>
</Line-Item>
<Line-Item>
<Id>Database </Id>
</Line-Item>
<Line-Item>
<Id>ProcessCon</Id>
</Line-Item>
</Items>
</PurchaseOrder>
<PurchaseOrder>
<Date>01/07/2004</Date>
<Buyer>EFGH Inc.</Buyer>
<Items>
<Line-Item>
<Id>Websphere </Id>
</Line-Item>
<Line-Item>
<Id>DB2 </Id>

</Line-Item>
<Line-Item>
<Id>Eclipse </Id>
</Line-Item>
</Items>
</PurchaseOrder>
<SalesOrder>
<Date>29/06/2004</Date>
<Buyer>Navneet Singh</Buyer>
</SalesOrder>
<PurchaseOrder>
<Date>28/06/2004</Date>
<Buyer>IJKL Inc.</Buyer>
<Items>
<Line-Item>
<Id>Weblogic </Id>
</Line-Item>
<Line-Item>
<Id>Tuxedo </Id>
</Line-Item>
<Line-Item>
<Id>JRockit </Id>
</Line-Item>
</Items>
</PurchaseOrder>
<Invoice>
<Date>30/06/2004</Date>
<Purchaser>Navneet Singh</Purchaser>
<Seller>Oracle</Seller>
<Price>5</Price>
<Quantity>70,000.00</Quantity>
<TotalPrice>350,000.00</TotalPrice>
</Invoice>
</container>
6.2.2.7 Defining Dates
This example shows how to define dates.
11/16/0224/11/02
11-20-2002
23*11*2002
01/02/2003 01:02
01/02/2003 03:04:05

Native Schema:
nxsd:stream="chars"
<element name="dateformat">
<complexType>
<sequence>
<element name="StartDate" type="dateTime" nxsd:dateFormat="MM/dd/yy"
nxsd:style="fixedLength" nxsd:length="8" />
<element name="EndDate" type="dateTime" nxsd:dateFormat="dd/MM/yy"
nxsd:style="terminated" nxsd:terminatedBy="${eol}" />
<element name="Milestone" type="dateTime" nxsd:dateFormat="MM-dd-yyyy"
<element name="DueDate" type="dateTime" nxsd:dateFormat="dd*MM*yyyy"
<element name="Date" type="dateTime" nxsd:dateFormat="MM/dd/yyyy hh:mm"
<element name="Date" type="dateTime" nxsd:dateFormat="MM/dd/yyyy hh:mm:ss"
</sequence>
</complexType>
</element>
</schema>
<dateformat xmlns="http://xmlns.oracle.com/pcbpel/nxsd/smoketest">
<StartDate>2002-11-16T00:00:00</StartDate>
<EndDate>2002-11-24T00:00:00</EndDate>
<Milestone>2002-11-20T00:00:00</Milestone>
<DueDate>2002-11-23T00:00:00</DueDate>
<Date>2003-01-02T01:02:00</Date>
<Date>2003-01-02T03:04:05</Date>
</dateformat>
The following example depicts the use of nxsd:dateParsingMode="lax/strict"
and locale support.
11/16/0224/11/02
11-20-2002
23*11*2002
01/02/2003 01:02
01/02/2003 03:04:05
Thu, 26 May 2005 15:50:11 India Standard Time
Do, 26 Mai 2005 15:43:10 Indische Normalzeit
20063202
Note: nxsd:dateParsingMode="lax/strict" and locale
support have been added to the existing date format.

Native Schema:
nxsd:stream="chars"
<complexType>
<sequence>
<element name="StartDate" type="date" nxsd:dateFormat="MM/dd/yy"
nxsd:localeLanguage="en" nxsd:style="fixedLength" nxsd:length="8" />
<element name="EndDate" type="date" nxsd:dateFormat="dd/MM/yy"
<element name="Milestone" type="dateTime" nxsd:dateFormat="MM-dd-yyyy"
<element name="DueDate" type="dateTime" nxsd:dateFormat="dd*MM*yyyy"
<element name="Date" type="dateTime" nxsd:dateFormat="MM/dd/yyyy hh:mm"
<element name="Date" type="dateTime" nxsd:dateFormat="MM/dd/yyyy hh:mm:ss"
<element name="LongDateInEnglish" type="dateTime" nxsd:dateFormat="EEE, d
MMM yyyy HH:mm:ss zzzz" nxsd:localeLanguage="en" nxsd:localeCountry="US"
<element name="LongDateInGerman" type="dateTime" nxsd:dateFormat="EEE, d
MMM yyyy HH:mm:ss zzzz" nxsd:localeLanguage="de" nxsd:style="terminated"
<element name="InvalidDate" type="dateTime" nxsd:dateParsingMode="lax"
nxsd:dateFormat="yyyyMMdd" nxsd:style="terminated" nxsd:terminatedBy="${eol}" />
</sequence>
</complexType>
</element>
</schema>
Translated XML:
<StartDate>2002-11-16</StartDate>
<EndDate>2002-11-24</EndDate>
<Date>2003-01-02T01:02:00</Date>
<Date>2003-01-02T03:04:05</Date>
<LongDateInEnglish>2005-05-26T15:50:11</LongDateInEnglish>
<LongDateInGerman>2005-05-26T15:43:10</LongDateInGerman>
<InvalidDate>2008-08-02T00:00:00</InvalidDate>
</dateformat>

6.2.2.8 Using Variables
This example shows how to use variables.
{,;}Fred,"2 Old Street, Old Town,Manchester","20-08-1954";"0161-499-1718"
phone-2
phone-3
Native Schema:
nxsd:stream="chars"
<element name="variable">
<annotation>
<documentation>
1. var1 - variable declaration
2. var2 - variable declaration with default value
3. EOL - variable declaration with referencing a system variable
</documentation>
<appinfo>
<junkies/>
<nxsd:variables>
<nxsd:variable name="var1" />
<nxsd:variable name="var2" value="," />
<nxsd:variable name="SystemEOL" value="${system.line.separator}" />
</nxsd:variables>
<junkies/>
<junkies/>
<junkies/>
</appinfo>
</annotation>
<complexType>
<sequence>
<element name="delims" type="string" nxsd:style="surrounded"
nxsd:leftSurroundedBy="{" nxsd:rightSurroundedBy="}" >
<annotation>
<appinfo>
<junkies/>
<junkies/>
<junkies/>
<nxsd:variables>
<nxsd:assign name="var1" value="${0,1}"/>
<nxsd:assign name="var2" value="${1}" />
</nxsd:variables>
</appinfo>
</annotation>
</element>
nxsd:terminatedBy="${var1}" nxsd:quotedBy=""" />

nxsd:terminatedBy="${var1}" nxsd:quotedBy="""/>
nxsd:terminatedBy="${var2}" nxsd:quotedBy='"'/>
<element name="Telephone1" type="string" nxsd:style="terminated"
nxsd:terminatedBy="${eol}" nxsd:quotedBy='"'/>
</sequence>
</complexType>
</element>
</schema>
<variable xmlns="http://xmlns.oracle.com/pcbpel/nxsd/smoketest">
<delims>,;</delims>
<DOB>20-08-1954</DOB>
<Telephone1>0161-499-1718</Telephone1>
<Telephone2>phone-2</Telephone2>
<Telephone3>phone-3</Telephone3>
</variable>
6.2.2.9 Defining Prefixes and Suffixes
In native format, when data is read, the specified data is prefixed, suffixed, or both, as
Native Data to Be Translated:
Fred, "2 Old Street, Old Town,Manchester","20-08-1954",0161-499-1718
Native Schema:
nxsd:stream="chars"
nxsd:version="NXSD"
>
<complexType>
<sequence>
<element name="PersonName" type="string" nxsd:prefixWith="Mr."
nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy=""" />
<element name="Address" type="string" nxsd:suffixWith="]]"
nxsd:prefixWith="[[" nxsd:style="terminated" nxsd:terminatedBy=","
nxsd:quotedBy="""/>
</sequence>

</complexType>
</element>
</schema>
<terminated xmlns="http://xmlns.oracle.com/pcbpel/nxsd/smoketest">
<PersonName>Mr.Fred</PersonName>
<Address>[[2 Old Street, Old Town,Manchester]]</Address>
<DOB>20-08-1954</DOB>
</terminated>
6.2.2.10 Defining Skipping Data
Translator skips, before or after the data is read, depending on the skipMode
construct, as shown in the following example:
Fred, "2 Old Street, Old Town,Manchester","20-08-1954",0161-499-1718
Native Schema:
nxsd:stream="chars"
nxsd:version="NXSD"
>
<complexType>
<sequence>
<element name="PersonName" type="string" nxsd:skip="5"
nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy=""" />
<element name="Address" type="string" nxsd:skipMode="before" nxsd:skip="3"
nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="""/>
<element name="DOB" type="string" nxsd:skipMode="after" nxsd:skip="6"
nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy='"'/>
</sequence>
</complexType>
</element>
</schema>
Translated XML Using Native Schema:
<DOB>20-08-1954</DOB>

<Telephone>99-1718</Telephone>
</terminated>
6.2.2.11 Defining fixed and default Values
When an element is declared without nxsd annotations but the value specified is
either fixed or default, the translator uses the value provided and does not throw
any exceptions.
Native Schema:
nxsd:stream="chars"
<annotation>
<appinfo>
<nxsd:variables>
<nxsd:variable name="x" value="hello" />
</nxsd:variables>
<junkies/>
<junkies/>
<junkies/>
</appinfo>
</annotation>
<complexType>
<sequence>
nxsd:terminatedBy="," nxsd:quotedBy=""" />
<element name="Age" type="string" fixed="16" />
<element name="salutation" type="string" default="${x}" />
</sequence>
</complexType>
</element>
</schema>
<Age>16</Age>

<DOB>20-08-1954</DOB>
<salutation>hello</salutation>
</terminated>
6.2.2.12 Defining write
The write construct writes the literal at the current position in the output stream,
either before writing the actual data or after writing it.
Input XML:
<DOB>20-08-1954</DOB>
</terminated>
Native Schema:
nxsd:stream="chars"
nxsd:version="NXSD"
>
<complexType>
<sequence>
<element name="PersonName" type="string" nxsd:writeMode="before"
nxsd:write="Mr." nxsd:style="terminated" nxsd:terminatedBy=","
nxsd:quotedBy=""" />
<element name="Address" type="string" nxsd:writeMode="after"
nxsd:write="Over." nxsd:style="terminated" nxsd:terminatedBy=","
nxsd:quotedBy="""/>
</sequence>
</complexType>
</element>
</schema>
Translated Data Using Native Schema:
Mr.Fred,"2 Old Street, Old Town,Manchester",Over.20-08-1954,0161-499-1718
6.2.2.13 Defining LookAhead
The LookAhead construct is of the following types:

■ Type 1: LookAhead X chars, read the value from a position using a style, and
match against the specified literal.
■ Type 2: LookAhead X chars, read the value from a position using a style, and store
that value in a variable to be used later.
LookAhead: Type 1
LookAhead X chars, read the value from a position using a style, and match against
the specified literal.
Fred,"2 Old Street, Old Town,Manchester","20-08-1954","0161-499-1718",YES
Native Schema:
nxsd:stream="chars"
<element name="LookAhead">
<complexType>
<sequence minOccurs="0" nxsd:lookAhead="70" nxsd:lookFor="YES">
</sequence>
</complexType>
</element>
</schema>
<LookAhead xmlns="http://xmlns.oracle.com/pcbpel/nxsd/smoketest">
<DOB>20-08-1954</DOB>
</LookAhead>
LookAhead: Type 2
In native schema, LookAhead X chars, read the value from a position using a style,
and store that value in a variable to be used later.
Name1,"2 Old Street, Old Town,Manchester",20-08-1954,"0161-499-1718", YES

Name2,"2 Old Street, Old Town,Manchester",20-08-1954,"0161-499-1718", NO
Native Schema:
nxsd:stream="chars"

<complexType>
<choice maxOccurs="unbounded" nxsd:choiceCondition="${x}" nxsd:lookAhead="70"
nxsd:scanLength="3" nxsd:assignTo="${x}">
<element name="Record1" type="string" nxsd:conditionValue="YES"
nxsd:style="terminated" nxsd:terminatedBy="," nxsd:skipMode="after"
nxsd:skipUntil="${eol}" />
<element name="Record2" type="string" nxsd:conditionValue="NO "
</choice>
</complexType>
</element>
</schema>
<Record1>Name1</Record1>
</LookAhead>
6.2.2.14 Defining outboundHeader
The actual content of outboundHeader can use variables, specifically ${eol}. When
headerLines and outboundHeader both are available, outboundHeader takes
precedence in the outbound.
Note: In the inbound direction, the Skipping Headers feature is
supported. Only predefined variables can be used in a header because
other variables might either not be accessible or would have only
literals.

Input XML:
<DOB>20-08-1954</DOB>
</terminated>
Native Schema:
nxsd:stream="chars"
nxsd:version="NXSD"
nxsd:hasHeader="true"
nxsd:outboundHeader="This is a header ${eol}">
<complexType>
<sequence>
</sequence>
</complexType>
</element>
</schema>
Translated Data:
This is a header
Fred,"2 Old Street, Old Town,Manchester",20-08-1954,0161-499-1718
6.2.2.15 Defining Complex Condition in conditionValue
When you use the conditionValue construct along with the choiceCondition
construct, you can specify match criteria such as equals (==) and not equals (!=), along
with the Boolean operators AND and OR, for comparison between the value read and
the value specified in the conditionValue construct.
Order, ID41678, 20May2000
Item1, GigaWidget, 60, $75
Item2, MegaBucket, 48, $125
Cust1, Hopkins Associates, ID26490
Item3, Rt.Clopper, 40, $100

Item4, Lt.Clopper, 50, $100
Cust2, Jersey WebInovaters, ID46786
Native Schema:
<?xml version="1.0" ?>
targetNamespace="http://xmlns.oracle.com/pcbpel/nxsd/extensions/SampleNS"
xmlns:tns="http://xmlns.oracle.com/pcbpel/nxsd/extensions/SampleNS"
attributeFormDefault="unqualified" nxsd:encoding="US-ASCII"
nxsd:stream="chars" nxsd:version="NXSD">
<xsd:element name="Container">
<xsd:complexType>
<xsd:choice minOccurs="1" maxOccurs="unbounded"
nxsd:choiceCondition="terminated" nxsd:terminatedBy=",">
<xsd:element name="Customer" nxsd:conditionValue="(== Cust1) or (== Cust2)
and (!= emp)">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="C1" type="xsd:string" nxsd:style="terminated"
</xsd:element>
nxsd:terminatedBy="${eol}" nxsd:quotedBy=""">
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="Item" nxsd:conditionValue="(== Item1) or (== Item2) or
(==Item3) or (== Item4)">
<xsd:complexType>
<xsd:sequence>
</xsd:element>
</xsd:element>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="Order" nxsd:conditionValue="Order">
<xsd:complexType>
<xsd:sequence>
</xsd:element>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:choice>

</xsd:complexType>
</xsd:element>
</xsd:schema>
<Container xmlns="http://xmlns.oracle.com/pcbpel/nxsd/extensions/SampleNS">
<Order>
<C1> ID41678</C1>
<C2> 20May2000</C2>
</Order>
<Item>
<C1> GigaWidget</C1>
<C2> 60</C2>
<C3> $75</C3>
</Item>
<Item>
<C1> MegaBucket</C1>
<C2> 48</C2>
<C3> $125</C3>
</Item>
<Customer>
<C1> Hopkins Associates</C1>
<C2> ID26490</C2>
</Customer>
<Order>
<C1> ID41680</C1>
<C2> 20May2000</C2>
</Order>
<Item>
<C1> Rt.Clopper</C1>
<C2> 40</C2>
<C3> $100</C3>
</Item>
<Item>
<C1> Lt.Clopper</C1>
<C2> 50</C2>
<C3> $100</C3>
</Item>
<Customer>
<C1> Jersey WebInovaters</C1>
<C2> ID46786</C2>
</Customer>
</Container>
6.2.2.16 Defining Complex Condition in choiceCondition
The choiceCondition construct is used along with the conditionValue construct for
records that are complex and may have fields delimited by multiple delimiter types.
The other choiceCondition types available are FixedLength, Variable, and Ad
hoc. The following example is for the variable choiceCondition type.

Native Schema:
<complexType>
<choice maxOccurs="unbounded" nxsd:choiceCondition="${x}" nxsd:lookAhead="70"
nxsd:scanLength="3" nxsd:assignTo="${x}">
<element name="Record1" type="string" nxsd:conditionValue="YES"
<element name="Record2" type="string" nxsd:conditionValue="NO "
</choice>
</complexType>
</element>
</LookAhead>
6.2.2.17 Defining dataLines
If the requirement is to translate only a portion of the data and not the entire data, then
you can specify the number of lines to be ignored from the beginning of the file and
the number of lines to be translated from that point onwards by using the dataLines
construct.
Fred,addr,20-08-1954,0161-499-1718
Tam,addr,20-08-1954,0161-499-1718
Albert,addr,20-08-1954,0161-499-1718
Bill,addr,20-08-1954,0161-499-1718
Phil,addr,20-08-1954,0161-499-1718
Native Schema:
nxsd:stream="chars"
nxsd:version="NXSD"
nxsd:headerLines="1"
nxsd:dataLines="1">
<complexType>
<sequence maxOccurs="unbounded">

</sequence>
</complexType>
</element>
</schema>
<PersonName>Tam</PersonName>
<Address>addr</Address>
<DOB>20-08-1954</DOB>
</terminated>
6.2.2.18 Defining Date Formats with Time Zone
In the translator, the date or time must be associated with a time zone. The translator
supports the date formats with time zone for both, the date in native data and for the
date in XML.
There are two parts when translating a date/time string. First, the format of the date in
the native data (dateformat), second is the time zone to use when parsing that date
(timeZone or useTimeZone). The translator uses these details while parsing the
date/time string.
After the parsing, by default, the date string is converted to the ISO-8601 format in an
XML. You can override the defaults by using XMLDateFormat and XMLTimeZone, or
useTimeZone.
11/16/0224/11/02
11-20-2002
23*11*2002
01/02/2003 01:02
01/02/2003 03:04:05
Thu, 26 May 2005 15:50:11 India Standard Time
Do, 26 Mai 2005 15:43:10 Indische Normalzeit
20063202
11/16/02
Native Schema:
nxsd:stream="chars"
<complexType>

<LongDateInEnglish>2005-05-26T15:50:11+05:30</LongDateInEnglish>
<LongDateInGerman>2005-05-26T15:43:10+05:30</LongDateInGerman>
<InvalidDate>2008-08-02T00:00:00</InvalidDate>
<MyFormatDate>16-11-2002</ MyFormatDate >
</dateformat>
6.2.2.19 Implementing Validation During Translation
You must configure Oracle JCA Adapters to implement validation during translation.
Validation helps ensure that Oracle JCA Adapters do not publish invalid messages
during translation.
You can implement either one or both of the following types of validation:
■ Payload Validation
■ Schema Validation
6.2.2.19.1 Payload Validation Payload validation involves validating the input and
output XML messages that are processed by Oracle JCA Adapters. You can set payload
validation at one of the following levels:
■ Top-Level Validation
■ Field-Level Validation
Top-Level Validation
In top-level validation, the DOMResult (result in the form of a Document Object
Model) is validated against the XML schema. This form of validation is implemented
on both inbound and outbound payloads. This form of validation can control the
publishing of invalid records and provide information about XML validation errors.
However, it does not provide translation context. For example, information about the
line and column in the native stream where the error was encountered is not provided
by top-level validation.
To implement top-level validation of XML messages:
■ The nxsd namespace in the message must be set to the following:
■ The validation flag must be set to true as follows:
nxsd:validation="true"
For example:
nxsd:stream="chars"
nxsd:version="NXSD"
nxsd:validation="true"
>
Field-Level Validation
In field-level validation, the individual fields are validated against the XML schema.
This form of validation is implemented only on inbound payloads, not on outbound
payloads.

If the XML message does not conform to the XML schema, then information about the
exact line and character where the error was encountered is displayed.
To implement field-level validation of XML messages:
■ The validation flag must be set to true as follows:
nxsd:fieldValidation="true"
For example:
nxsd:stream="chars"
nxsd:version="NXSD"
nxsd:fieldValidation="true"
>
6.2.2.19.2 Schema Validation Schema validation involves validating the schema (native
schemas or XML schemas) that you define for the native or XML data formats to be
translated by the Oracle JCA Adapters.
To enable schema validation:
■ The validate nxsd flag must be set to true as follows:
nxsd:validateNxsd="true"
For example:
nxsd:stream="chars"
nxsd:version="NXSD"
nxsd: validateNxsd ="true"
>
6.2.2.20 Processing Files with BOM
The byte order mark (BOM) is a special U+FEFF Unicode character that describes the
encoding of a byte sequence. The Native Format Translator can be configured to use
BOM for determining the character encoding of the native input data. By default, BOM
is not used. If your input data uses BOM, then set the nxsd:parseBom attribute to
true in the native schema. Otherwise, the translator throws a parsing error.
Note: The nxsd:validateNxsd="true" validation flag does not
affect payload level validations.

Translator XPath Functions
The following is a sample nxsd file:
<?xml version= '1.0' encoding= 'UTF-8' ?>
xmlns:tns="http://TargetNamespace.com/InboundService"
targetNamespace="http://TargetNamespace.com/InboundService"
nxsd:parseBom="true" nxsd:version="NXSD" nxsd:stream="chars"
nxsd:encoding="UTF8">
<xsd:element name="Root-Element">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="mydata" minOccurs="1" maxOccurs="unbounded"
nxsd:style="array"
nxsd:cellSeparatedBy="${eol}">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="C1" type="xsd:string"
nxsd:length="3"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
6.3 Translator XPath Functions
The translator XPath functions can translate data from a native format (such as CSV,
fixed-length, tab-delimited, and COBOL Copybook formats) to an XML format and
from an XML format to a native format. The translator XPath functions are of two
types, streaming and non-streaming. The difference is that the streaming translator
XPath functions implement the batching transformation approach while the
non-streaming XPath functions do not implement the batching transformation
approach. With the batching transformation approach, files that are of the order of a
few gigabytes (GB) can be processed without running into memory issues.
■ Section 6.3.1, "Terminologies"
■ Section 6.3.2, "Translator XPath Functions"
6.3.1 Terminologies
This section describes the terminologies that you must understand for using
translation XPath functions.
Attachment Element
An attachment element unusually refers to the actual content elsewhere by using an
"href" attribute. The actual content may be present in a file system or in a database
table. An attachment is usually represented by using the following schema construct:
<element name="hrefelement">
<complexType>
<attribute name="href" type="string"/>

</complexType>
</element>
The "href" attribute contains the actual location of the data being referred to. It can
contain the path to a file in the file system or a pointer (primary key) to a database
entity.
Scalable DOM
Scalable DOM (SDOM), from Oracle XML Developer Kit (Oracle XDK), provides
scalable and pluggable support for DOM. This removes problems of memory
inefficiency, limited scalability, and lack of control over the DOM configuration. Using
the lazy materialization mechanism, Oracle XDK only creates nodes that are accessed
and frees unused nodes from memory. Applications can process very large XML
documents with improved scalability.
6.3.2 Translator XPath Functions
A translator may be required while reading and writing files. This section discusses
the following translator XPath functions:
■ doTranslateFromNative Function
■ doTranslateToNative Function
■ doStreamingTranslate Function
6.3.2.1 doTranslateFromNative Function
The doTranslateFromNative XPath function translates input data into XML. The input
data can be a string, an attachment element, or a base64Binary element.
ora:dotranslateFromNative('input','nxsdTemplate','nxsdRoot','tar
getType','attachment element?')
The following table describes the parameters used in the syntax for using this function:
Parameter Description
input Input data for the XPath function; the data can either be a string
data that must be translated, a File/FTP Adapter attachment, an
attachment referring to an external file path, or a base64Binary
element.
nxsdTemplate NXSD schema to use to translate the input data into XML format.
nxsdRoot Root element in the NXSD schema.
targetType This parameter decides how the XPath function translates the
native data into XML. Must be set to either 'DOM', or
'ATTACHMENT' or 'SDOM'. If the targetType parameter is:
■ ‘DOM’, then the translated data is returned as a DOM.
■ ‘ATTACHMENT’, then the translated data is returned as an
attachment. If the optional parameter
(attachmentElement) is available to the XPath function,
then the XPath function uses the corresponding href
attribute to write the translated XML. However, if the
parameter is absent, then the XPath function creates a new
database-backed attachment and returns that. See
Example 6–4 for more details.
■ ‘SDOM’, then the translated data is returned as SDOM. You
must use this if the returned XML file is huge.

Example 6–1 Configuring the XPath Function When the Input Data Is of String Type and
Must Be Converted to an XML DOM
<variables>
<variable…/>
<variable name="csv_data" type="xsd:string"/>
</variables>
<assign name="assignCSVData">
<copy>
<from expression="'this, is, csv, data…'"/>
<to variable="csv_data"/>
</copy>
</assign>
<assign name=”doTranslateFromNativeCall”>
<copy>
<from expression="ora: doTranslateFromNative (bpws:getVariableData(‘csv_
data’),’xsd/address-csv.xsd’,’Root-Element’,’DOM’)"/>
<to variable="returnVariable" query="/ns1:Root-Element"/>
</copy>
</assign>
In this example:
■ csv_data is a BPEL variable containing CSV data to be translated into XML.
■ xsd/address-csv.xsd is relative path to the NXSD schema in the project.
■ Root-Element is a root element in the NXSD schema (This is optional.)
■ returnVariable is the returned XML data as DOM.
Example 6–2 When the Input data is an Attachment, Which Must Be Translated to a DOM
1. Define attachmentElement in the schema of the BPEL process, as follows:
<schema targerNamespace=”…”>
<element name="attachmentElement">
<complexType>
</complexType>
</element>
</schema>
2. Create a variable of type attachment element in the schema of the BPEL process, as
follows:
<variables>
<variable…/>
<variable name="attachmentVariable" type="client:attachmentElement"/>
</variables>
3. Assign the source file path that you must translate, as follows:
<assign name="AssignAttachmentReference">
<copy>
<from expression="'/tmp/xpath/in/address.csv'"/>
<to variable="attachmentVariable"
attachmentElement This parameter is optional. This is the attachment for the returned
XML file.

query="/client:attachmentElement/@href"/>
</copy>
</assign>
4. Call the XPath function, as follows:
<assign name="xlateFromNative">
<copy>
<from
expression="ora:doTranslateFromNative(bpws:getVariableData('attachmentVariable'
),'xsd/address-csv.xsd', 'Root-Element', 'DOM')"/>
</copy>
</assign>
In this example:
■ attachmentVariable is an attachment variable in BPEL referring to the source
file path.
■ xsd/address-csv.xsd is the relative path to the NXSD schema in the project.
■ Root-Element is a root element in the NXSD schema.
■ returnVariable is the XML data returned as DOM.
Example 6–3 Configuring XPath Function When the Input Data Is Base64-encoded and
Must Be Translated to DOM
1. Define the base64-encoded element in the schema of the BPEL process, as follows:
<element name="mtomElement" type="base64Binary"/>
</schema>
2. Create a variable of type mtom element in the schema of the BPEL process, as
follows:
<variables>
<variable…/>
<variable name="encodedData" type="client:mtomElement"/>
</variables>
3. Assign the source file path that you need to translate, as follows
<assign name="assignBase64EncodedData">
<copy>
<from expression="'b3JhY2xl'"/>
<to variable="encodedData" query="/client:mtomElement"/>
</copy>
</assign>
<copy>
<from expression="ora: doTranslateFromNative
(bpws:getVariableData('encodedData'),'xsd/address-csv.xsd','Root-Element',’DOM’
)"/>
</copy>
</assign>
In this example:

■ mtomElement is a BPEL variable containing base64-encoded data to be translated
into XML.
■ returnVariable is the XML data returned as DOM.
Example 6–4 Configuring XPath Function When the Input Data Is of String Type, Which
Must Be Translated to an Attachment Referred to by a File-Path
<complexType>
</complexType>
</element>
</schema>
2. Create an input variable of type string and an output variable of type attachment
in the schema of the BPEL process, as follows:
<variables>
<variable…/>
<variable name="returnAttachmentVariable" type="client:attachmentElement"/>
</variables>
3. Assign the CSV data that you need to translate, as follows:
<copy>
</copy>
</assign>
4. Populate the attachment with the path of the file where you want the translated
data to be stored, as follows:
<assign name="AssignAttachmentReferenceForOutput">
<copy>
<from expression="'/tmp/xpath/output/address.xml'"/>
<to variable=" returnAttachmentVariable "
</copy>
</assign>
5. Call the XPath function as follows:
<copy>
<from expression="ora: doTranslateFromNative (bpws:getVariableData('csv_
data'),'xsd/address-csv.xsd','Root-Element',’ATTACHMENT’,
bpws:getVariableData('returnAttachmentVariable'))"/>
<to variable="returnAttachmentVariable"/>
</copy>
</assign>
In this example:

■ csv_data is a BPEL string variable containing CSV data to be translated into
XML.
■ returnAttachmentVariable is the returned attachment.
Note: In this example, targetType is set to ATTACHMENT, and
returnAttachmentVariable points to the file path where the translated XML is to
be written.
However, the fifth parameter
(bpws:getVariableData('returnAttachmentVariable')) is optional. If this
parameter is missing, then the XPath function creates a database-backed attachment
and returns it. In such a case, the XPath function is configured, as follows:
<complexType>
</complexType>
</element>
</schema>
2. Create an input variable of type string and an output variable of type attachment
in the schema of the BPEL process, as follows:
<variables>
<variable…/>
<variable name="returnAttachmentVariable" type="client:attachmentElement"/>
</variables>
3. Assign the CSV data that you need to translate, as follows:
<copy>
</copy>
</assign>
<copy>
<from expression="ora: doTranslateFromNative
(bpws:getVariableData('csv_
data'),'xsd/address-csv.xsd','Root-Element',’ATTACHMENT’)"/>
<to variable="returnAttachmentVariable"/>
</copy>
</assign>
After the XPath call returns, the returnAttachmentVariable variable is
populated with the href attribute pointing to the GUID representing the
database-backed attachment.
Note: If the data being translated is huge, then you must use either ATTACHMENT
or SDOM as the targetType parameter for the XPath function.

6.3.2.2 doTranslateToNative Function
The doTranslateToNative XPath function translates an input DOM into string
data or an attachment.
Syntax:
ora:dotranslateToNative('input','nxsdTemplate','nxsdRoot','targe
tType','attachmentElement?')
Example 6–5 Configuring the XPath Function When the Input Data Is of XML Format and
Must Be Translated Into CSV String Format
<variables>
<variable…/>
<variable name="inputDOM" type="ns1:Root-Element"/> <!- - data that needs to be
translated into native - ->
<variable name="returned_csv_data" type="xsd:string"/>
</variables>
<assign name=”doTranslateToNativeCall”>
<copy>
<from expression="ora: doTranslateToNative
(bpws:getVariableData('inputDOM'),'xsd/address-csv.xsd',’Root-Element’,'STRING')"/
>
<to variable="returned_csv_data"/>
</copy>
</assign>
In this example:
■ inputDOM is a BPEL DOM variable containing XML data to be translated into
string data representing the translated CSV.
input Input data for the XPath function; the data can either be DOM or
SDOM data that must be translated to a native format such as
CSV.
nxsdTemplate NXSD schema to be used to translate the input data into XML
format.
nxsdRoot Name of the root element in the NXSD schema.
XML data into native formats. Must be set to either 'STRING', or
'ATTACHMENT'. If the targetType parameter is:
■ STRING, then the translated data is returned as a string.
■ ATTACHMENT, then the translated data is returned as an
attachment. If the optional parameter
(attachmentElement) is available to the XPath function,
then the XPath function uses the corresponding href
attribute to write the translated native data. However, if the
parameter is absent, then the XPath function creates a new
database-backed attachment and returns that. See
Example 6–6 for more details.
attachmentElement This parameter is optional. This is the attachment to which the
translated data is written.

■ return_csv_data is the string variable that contains the translated CSV data.
Example 6–6 Configuring XPath Function to Translate an Incoming XML DOM into an
Attachment Representing the Target File-Path for the Translated CSV
<complexType>
</complexType>
</element>
</schema>
2. Create an input variable of type attachmentElement in the schema of the BPEL
process, as follows:
<variables>
<variable…/>
<variable name="inputDOM" type="ns1:Root-Element"/>
</variables>
3. Assign the target file path where you want the translated CSV to be written, as
follows:
<assign name="AssignAttachmentReference">
<copy>
<from expression="'/tmp/xpath/out/address.csv'"/>
<to variable="attachmentVariable"
</copy>
</assign>
<assign name="xlateToNative">
<copy>
<from
expression="ora:doTranslateToNative(bpws:getVariableData('inputDOM'),'xsd/addre
ss-csv.xsd', 'Root-Element', 'ATTACHMENT', bpws:getVariableData('
attachmentVariable'))"/>
<to variable="attachmentVariable"/>
</copy>
</assign>
In this example:
■ inputDOM is a BPEL DOM variable containing XML data to be translated into a
CSV output file represented by /tmp/xpath/out/address.csv.
■ AttachmentElement points to the target output file path represented by
/tmp/xpath/out/address.csv.

Note: In this example, targetType is set to ATTACHMENT, and
AttachmentVariable points to the file path where the translated CSV file is to be
written.
However, the fifth parameter
(bpws:getVariableData('attachmentVariable')) is optional. If this
parameter is missing, then the XPath function creates a database-backed attachment
and returns it. In such a case, the XPath function is configured as follows:
<complexType>
</complexType>
</element>
</schema>
2. Create an input variable of type attachmentElement in the schema of the BPEL
process, as follows:
<variables>
<variable…/>
<variable name="inputDOM" type="ns1:Root-Element"/>
</variables>
<assign name="xlateToNative">
<copy>
<from
expression="ora:doTranslateToNative(bpws:getVariableData('inputDOM'),'xsd/addre
ss-csv.xsd', 'Root-Element', 'ATTACHMENT')"/>
<to variable="attachmentVariable"/>
</copy>
</assign>
After the XPath call returns, attachmentVariable is populated with the href
attribute pointing to the GUID representing the database-backed attachment.
6.3.2.3 doStreamingTranslate Function
XPath functions implement the batching transformation approach. With this approach,
files that are of the order of a few gigabytes (GB) can be processed without running
into memory issues. Arbitrarily large payloads can be handled because the
transformation engine does not store the result of the transformation in its memory.
The transformation engine flushes its memory after a batch of elements of the large file
is processed. The default batch size is 10000, which is the number of elements after
which the transformation engine flushes its memory. This parameter is used internally
and is optional.
Syntax:
ora:doStreamingTranslate('input','streamingXpathContext','target
Type','attachmentElement?')
Note: Batching transformation approach is supported for XML
documents that have repeating structures only.

The streamingXPathContext parameter specifies the context for the streaming
transformation and, it must conform to the following schema element:
<schema targetNamespace="…">
<element name="streamingcontext">
complexType>
<sequence>
<element name="sourceSchema" type="string"/>
<element name="sourceRootElement" type="string"/>
<element name="sourceType" type="string"/>
<element name="xsl" type="string"/>
<element name="targetSchema" type="string"/>
<element name="targetRootElement" type="string"/>
<element name="targetType" type="string"/>
<element name="batchSize" type="string"/>
</sequence>
</complexType>
</element>
</schema>
In context:
6.3.2.4 Batching Transformation Features
This section discusses the following features of batching transformation:
input Input data for the XPath function; the data can either be SDOM or
an Attachment element.
streamingXpathContext DOM representing the XPath context.
input data into an attachment. This must be set to either SDOM or
ATTACHMENT.
attachmentElement This parameter is optional. This is the attachment to which the
data is streamed.
Schema Element Description
sourceSchema Source NXSD schema used to translate a native data to XML.
sourceRootElement Name of root element in source NXSD schema.
sourceType Set this to either xml or native depending on the input data.
xsl Relative path of the XSL file.
targetSchema Target NXSD schema used to translate an XML into native
data.
targetRootElement Name of root element in target NXSD schema.
targetType Set this to either xml or native depending on the output
data.
batchSize The number of elements after which the transformation
engine flushes its memory.

Applicability
Batching transformation is applicable to:
■ Documents with repeating structure
■ XSLTs not requiring aggregation across entire document
Batched Invocation of XSLT Engine
The following procedure highlights the batched invocation of the XSLT engine:
1. Splitting the source document into multiple batches of one or more records
2. Performing the XSLT transformation one batch at a time
3. Combining the result of the XSLT invocation to a single target document
Splitting or Combining Performed on the Fly
The source documents are split and the results are combined into a target document:
■ Without any intermediate memory or disk storage
■ Through pipelining or intercepting SAX events
Low In-Memory Footprint
Batching transformation method uses low memory for the following tasks:
■ Transforming arbitrarily large XML documents, which are constrained by the
target system
■ For standalone tests, 540 MB is transformed in less than 3 minutes
Example 6–7 implements the FlatStructure FileAdapter sample using streaming
transformation XPath functions. This sample use case translates the inbound native
attachment from a CSV format to an XML format, and then applies the user-supplied
XSL file to the resulting XML file. The transformed XML file is then translated into a
fixed-length content represented by an attachment.
Example 6–7 Using Streaming Transformation XPath Function
1. Define attachmentElement, as shown:
<complexType>
</complexType>
</element>
</schema>
2. Create a variable for the input attachment referring to the inbound csv file and the
output attachment referring to the output fixed-length file. Create the variable
corresponding to the streaming context. You must populate this variable before
making a call to the XPath function.
<variables>
<variable name="xlationContext" element="client:streamingcontext"/>
<variable name="inputAttachment" element="client:attachmentElement"/>
<variable name="returnAttachment" element="client:attachmentElement"/>
</variables>
<!- - Assign the input and output attachments - ->
<assign name="assignValuesForAttachments">

<copy>
<from expression="’/tmp/xpath/in/address.csv’ "/>
<to variable="inputAttachment"
</copy>
<copy>
<from expression="’/tmp/xpath/out/address_fixedLength.txt’ "/>
<to variable="returnAttachment"
</copy>
</assign>
<!- - Assign the streaming context - ->
<assign name="AssignStreamingContext">
<copy>
<from expression="'xsd/address-csv.xsd'"/>
<to variable="xlationContext"
query="/client:streamingcontext/client:sourceSchema"/>
</copy>
<copy>
<from expression="'Root-Element'"/>
query="/client:streamingcontext/client:sourceRootElement"/>
</copy>
<copy>
<from expression="'native'"/>
query="/client:streamingcontext/client:sourceType"/>
</copy>
<copy>
<from expression="'xsd/address-fixedLength.xsd'"/>
query="/client:streamingcontext/client:targetSchema"/>
</copy>
<copy>
<from expression="'Root-Element'"/>
query="/client:streamingcontext/client:targetRootElement"/>
</copy>
<copy>
<from expression="'native'"/>
query="/client:streamingcontext/client:targetType"/>
</copy>
<copy>
<from expression="'xsl/addr1Toaddr2.xsl'"/>
query="/client:streamingcontext/client:xsl"/>
</copy>
<copy>
<from expression="'10000'"/>
query="/client:streamingcontext/client:batchSize"/>
</copy>
</assign>
<!- - call the XPath function - ->
<assign name="executeStreamingXPath">
<copy>
<from
expression="ora:doStreamingTranslate(bpws:getVariableData('inputAttachment','/c
lient:attachmentElement'),

Use Cases for the Native Format Builder
bpws:getVariableData('xlationContext'), 'ATTACHMENT',
bpws:getVariableData('returnAttachment'))"/>
<to variable="returnAttachment" query="/client:attachmentElement"/>
</copy>
</assign>
6.4 Use Cases for the Native Format Builder
This section describes the following use cases:
■ Section 6.4.1, "Defining the Schema for a Delimited File Structure"
■ Section 6.4.2, "Defining the Schema for a Fixed Length File Structure"
■ Section 6.4.3, "Defining the Schema for a Complex File Structure"
■ Section 6.4.4, "Removing or Adding Namespaces to XML with No Namespace"
■ Section 6.4.5, "Defining the Choice Condition Schema for a Complex File
Structure"
■ Section 6.4.6, "Defining Choice Condition With LookAhead for a Complex File
Structure"
■ Section 6.4.7, "Defining Array Type Schema for a Complex File Structure"
■ Section 6.4.8, "Defining the Schema for a DTD File Structure"
■ Section 6.4.9, "Defining the Schema for a COBOL Copybook File Structure"
6.4.1 Defining the Schema for a Delimited File Structure
A comma-separated value (CSV) file is a common non-XML file structure.
Use the Delimited option in the Native Format Builder wizard, when creating the
XML schema for this native file.
The nxsd:headerLines="1" schema attribute signifies that the first line must be
treated as a header row and skipped in the native data before actually translating the
rest of the data. The nxsd:stream="chars" schema attribute signifies that the data
should be read as characters. If nxsd:stream is set as bytes,
nxsd:stream="bytes", then this schema attribute signifies that the native data
should be read as bytes. For each of the element declarations, Name, Street, City,
State, and Country, which have a corresponding scalar data, the
nxsd:style="terminated" attribute defines that the corresponding data is stored
in terminated style. The actual terminator is then defined by the
nxsd:terminatedBy="," attribute specified at that construct. See Section 6.2.2.2,
"Defining Terminated Data" for details on the terminated style.
In this use case, the Native Format Builder uses a delimited sample file type that
contains the address details, such as name, street, city, state, and country. Every
element in this sample native file is delimited by a comma (,). You can generate the
corresponding NXSD and also test it. Perform the following steps to run the use case:
1. The data in a sample text file, address-csv.txt, appears as below:
Note: Sampling the data with multi-character delimiter in Native
Format Builder is not supported currently. The same can be achieved
through hand coding the NXSD with the appropriate Delimited By
string.

Name,Street1,Street2,City,State,Country
Oracle India Private Limited, Lexington Towers Prestige St. John's Woods, 2nd
Cross Road Chikka Audugodi, Bangalore, Karnataka, India
Intel Technology India Private Limited, Survey #23-56 P Devarabeesanahalli
Village, Outer Ring Road Varthur Hobli, Bangalore, Karnataka, India
2. Navigate to the Adapter Configuration Wizard Messages page, as displayed in
Figure 6–4, and click the Define Schema for Native Format button.
Figure 6–4 Starting the Native Format Builder Wizard
The Native Format Builder Welcome page is displayed, as shown in Figure 6–5.
Figure 6–5 Native Format Builder Wizard Welcome Page

3. Click Next. The Choose Type page is displayed, as shown in Figure 6–6.
Figure 6–6 Native Format Builder Wizard Choose Type Page
4. Click Next. The Native Format Builder File Description page is displayed.
5. Click Browse and select the address-csv.txt file, as shown in Figure 6–7.
Figure 6–7 Native Format Builder Wizard File Description Page
6. Click Next. The Record Organization page is displayed, as shown in Figure 6–8.

Figure 6–8 Native Format Builder Wizard Record Organization Page
7. Select File contains multiple record instances, then select Multiple records are of
single type, and then click Next. The Specify Elements page is displayed.
8. Enter AddressBook in the Enter name of element containing multiple records
field and enter Address in the Enter a name for element that will represent
record field, as shown in Figure 6–9.
Figure 6–9 Native Format Builder Wizard Specify Elements Page
9. Click Next. The Specify Delimiters page is displayed, as shown in Figure 6–10.

Figure 6–10 Native Format Builder Wizard Specify Delimiters Page
10. Ensure that the Comma(,) option is selected in the Delimited By field, and click
Next. The Field Properties page is displayed, as shown in Figure 6–11.
Figure 6–11 Native Format Builder Wizard Field Properties Page
11. Select Use the first record as the field names, then click Next. The Generated
Native Format File page is displayed, as shown in Figure 6–12.
Note: The first record is used as the field name, is also treated as a
header record, and is skipped during translation.

Figure 6–12 Native Format Builder Wizard Generated Native Format File Page
The corresponding native schema definition is as follows:
xmlns:tns="http://TargetNamespace.com/Read"
targetNamespace="http://TargetNamespace.com/Read"
nxsd:version="NXSD"
nxsd:stream="chars"
nxsd:encoding="ASCII"
nxsd:headerLinesTerminatedBy="${eol}"
>
<xsd:element name="AddressBook">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Address" minOccurs="1" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Name" type="xsd:string"
<xsd:element name="Street1" type="xsd:string"
<xsd:element name="Street2" type="xsd:string"
<xsd:element name="City" type="xsd:string"
<xsd:element name="State" type="xsd:string"

<xsd:element name="Country" type="xsd:string"
nxsd:style="terminated" nxsd:terminatedBy="${eol}"
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
12. Click Test. The Test NXSD Schema dialog is displayed, as shown in Figure 6–13.
Figure 6–13 Test NXSD Schema Dialog
13. Click the Generate XML icon. The resultant XML is displayed on the Result XML
pane of the Test NXSD Schema dialog, as shown in Figure 6–14.

The native data using the corresponding native schema format is translated into
the following XML:
<?xml version = '1.0' encoding = 'UTF-8'?>
<AddressBook xmlns="http://TargetNamespace.com/ReadFile">
<Address>
<Name>Oracle India Private Limited</Name>
<Street1> Lexington Towers Prestige St. John's Woods</Street1>
<Street2> 2nd Cross Road Chikka Audugodi</Street2>
<City> Bangalore</City>
<State> Karnataka</State>
<Country> India</Country>
</Address>
<Address>
<Name>Intel Technology India Private Limited</Name>
<Street1> Survey #23-56 P Devarabeesanahalli Village</Street1>
<Street2> Outer Ring Road Varthur Hobli</Street2>
<City> Bangalore</City>
<State> Karnataka</State>
<Country> India</Country>
</Address>
</AddressBook>
14. Click OK. The Generated Native Format Schema File page is displayed, as shown
in Figure 6–12.
15. Click Next. The Native Format Builder Finish page is displayed, as shown in
Figure 6–15.

Figure 6–15 Native Format Builder Wizard Finish Page
16. Click Finish. The Adapter Configuration Wizard Messages page is displayed, as
shown in Figure 6–16, containing the generated NXSD.
Figure 6–16 Adapter Configuration Wizard Messages Page
6.4.1.1 Defining a Asterisk (*) Separated Value File Structure
The use case defined in the previous example is just one specific case of the *SV class,
where the wildcard can be substituted by any character or string. For example, for the
native data containing a plus (+) separated value, substitute the wildcard with the
plus (+) character.

Use the Delimited type option in the Native Format Builder wizard when creating the
Native Data Format to Be Translated
The following native data format is provided:
a+b+c+d+e
f+g+h+i+j
Native Schema
The corresponding native schema definition is similar to the one in the previous use
case except that instead of nxsd:terminatedBy="," you now define the terminated
by format as nxsd:terminatedBy="+". See Section 6.2.2.2, "Defining Terminated
Data" for details about the terminated style.
6.4.2 Defining the Schema for a Fixed Length File Structure
In this example, the native data used is the same as in the CSV case, but the data used
is of type fixed length and not CSV.
Use the Fixed Length option in the Native Format Builder wizard, to create the XML
schema for this native file.
In this use case, the Native Format Builder uses a fixed-length file type called
address that contains the address details such as name, street, city, state, and country.
Every element in this address native file has a fixed length. You can generate the
1. The data in a sample text file, address.txt, appears as below:
Name Street City State Country
ABC Private Limited Street1 Bangalore Karnataka India
XYZ Private Limited Street1 Bangalore Karnataka India
2. Launch the Adapter Configuration Wizard and navigate to the Messages page, as
displayed in Figure 6–4, and click Define Schema For Native Format. The Native
Format Builder Welcome page is displayed, as shown in Figure 6–5.
3. Click Next. The Choose Type page is displayed.
4. Select Fixed Length as the file type, as shown in Figure 6–17.

6. Click Browse and select the address.txt file, as displayed in Figure 6–18.
7. Click Next. The Record Organization page is displayed, as shown in Figure 6–19.

Figure 6–19 Native Format Builder Wizard Record Organization Page
8. Select Multiple records are of single type, and click Next. The Specify Elements
page is displayed.
9. Enter AddressBook in the Enter name of element containing multiple records
field, and enter Address in the Enter a name for element that will represent
record field, as shown in Figure 6–20.
Figure 6–20 Native Format Builder Wizard Specify Elements Page
10. Click Next. The Field Lengths for Multiple Record Files page is displayed.
11. Click the ruler at the desired position to mark fields on the sample text area, as
shown in Figure 6–21 and click Next. The Field Properties page is displayed.

Figure 6–21 Native Format Builder Wizard Field Lengths for Multiple Record Files Page
12. Check Use the first record as the field names, as shown in Figure 6–22.
13. Click Next. The Generated Native Format Schema File page is displayed, as shown
in Figure 6–23.

Figure 6–23 Native Format Builder Wizard Native Format Schema File Page
The corresponding native schema definition is similar to the definition of the CSV,
file but style changes from nxsd:style="terminated" to
nxsd:style="fixedLength" along with the relevant attributes for the
fixed-length style. For the fixed-length style, the one mandatory attribute is the
length: nxsd:length. The value of nxsd:length is the actual length of the
data to be read.
xmlns:tns="http://TargetNamespace.com/FileIn_1"
targetNamespace="http://TargetNamespace.com/FileIn_1"
nxsd:version="NXSD"
nxsd:stream="chars"
nxsd:headerLinesTerminatedBy="${eol}"
<xsd:element name="AddressBook">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Address" minOccurs="1" maxOccurs="unbounded"
nxsd:style="array" nxsd:cellSeparatedBy="${eol}">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Name" type="xsd:string"
<xsd:element name="Street" type="xsd:string"
<xsd:element name="City" type="xsd:string"
<xsd:element name="State" type="xsd:string"

<xsd:element name="Country" type="xsd:string"
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
15. Click the Generate XML icon. The resultant XML is displayed on the Result XML
pane of the Test NXSD Schema dialog, as shown in Figure 6–25.

The native data using the corresponding native schema format is translated into
the following XML:
<AddressBook xmlns="http://TargetNamespace.com/Read">
<Address>
<Name>ABC Private Limited </Name>
<Street>Street1 </Street>
<City> Bangalore </City>
<State>Karnataka </State>
<Country>India</Country>
</Address>
<Address>
<Name>XYZ Private Limited </Name>
<Street>Street1 </Street>
<City> Bangalore </City>
<State>Karnataka </State>
<Country>India </Country>
</Address>
</AddressBook>
16. Click OK. The Generated Native Format File page is displayed, as shown in
Figure 6–23.
Figure 6–15.
18. Click Finish. The Adapter Configuration Wizard Messages page is displayed, as
shown in Figure 6–16, that contains the generated NXSD.

6.4.3 Defining the Schema for a Complex File Structure
The file structure of an invoice is more complex than the structure of CSV, *SV, and
fixed-length files discussed in the preceding use cases. An invoice usually contains
buyer information, seller information, and line items. Each of these elements, in turn,
can be of complex type. For example, the buyer element can be defined as a
partner-type, where partner-type consists of three elements - id, name, and address.
Use the Complex Type option in the Native Format Builder wizard when creating the
In this use case, the Native Format Builder uses invoice.txt, a complex file type
called invoice, which contains multiple records such as buyer, seller, and items. Also,
using this use case, you can generate the NXSD and test it. Perform the following steps
to run this use case:
1. The data in a sample text file, invoice.txt, appears as below:
6335722^Company One^First Street 999 San Jose
95129USCA650-801-6250
^Oracle^Bridge Parkway 1600 Redwood Shores 94065USCA650-506-7000
001|BPEL Process Manager Enterprise Edition|20000,2,+40000+
002|BPEL Process Manager Standard Edition|10000,5,+50000+
003|BPEL Process Manager Developer Edition|1000,20,+20000+#110000
Format Builder Welcome page is displayed as shown in Figure 6–5.
3. Click Next. The Choose Type page is displayed as shown in Figure 6–26.
4. Select Complex Type (Contains records whose fields may themselves be records
having multiple delimiter types).
6. Click Browse and select the invoice.txt file, and enter Invoice in the Root
Element field, as displayed in Figure 6–27.

7. Click Next. The Native Format Builder Design Schema is displayed, as shown in
Figure 6–28.
Figure 6–28 Native Format Builder Wizard Design Schema Page
Create the partner-type Complex Type
The schema structure that you can build using the invoice.txt sample is as follows:
Invoice
Buyer => partner-type
Seller => partner-type
Items => item-type

Invoice-total => double
The first line in the native data consists of buyer details, followed by seller details,
followed by line items, and finally the total for the line items. Both buyer and seller
elements have the same complex structure, as follows:
■ The first seven characters are the UID
■ This is followed by the buyer/seller name surrounded by “^”.
■ This is followed by the address until the end of the line.
8. Click the Add Complex Type icon. A Complex Type, <new_complex_type> is
created in the Schema Tree under Invoice, as shown in Figure 6–29.
9. Select the first row of the sample text from the right-hand pane of the Sample File
section, and drag and drop it on the <new_complex_type> node. The Complex
Type Details dialog is displayed.
10. Enter partner-type in the Complex Type Name field, as shown in Figure 6–30.

Figure 6–30 Native Format Builder Wizard Design Schema Page - Complex Type Details
Dialog
11. Click the ruler at the desired position to mark fields on the sample text area, and
then click the Generate Fields button. The system tries to interpret the style of
data for the defined fields.
12. Enter id, name, and address in the Name field, as shown in Figure 6–31.
Note: For the Fixed Length or Mixed Delimiter type options, a
ruler-based text area is displayed. You have to use the rulers to
identify fields within the sample text. In case of delimited data, select
or enter the appropriate delimiter in the Delimited By field.

Figure 6–31 Complex Type Details Dialog
13. Click the pencil icon adjacent to each field to display the corresponding Edit Field
Details dialog that enables you to edit the field properties. For example, click the
pencil icon adjacent to the Name field. The Edit Field Details dialog is displayed,
Figure 6–32 Edit Field Details Dialog
14. Edit the following field properties, as shown in Figure 6–32.

■ Type: The data type of the sample text. Select String from the Type list.
■ Style: Represents the style of the complex type element. You can select any of
the following four options:
– fixed length
– surrounded
– terminated
– left/right surrounded
In this example, select surrounded.
■ Surrounded By: This option is displayed when you select surrounded in the
Style option. In this example, enter caret (^) in the Surrounded By field.
The field properties displayed on this panel correspond to the NXSD attributes
used in the schema.
15. Click OK. The Complex Type Details dialog is displayed with the field properties
that you selected.
16. Verify or edit the field properties for id and address Name fields.
17. Click OK in the Complex Type Details dialog. The Native Format Builder Design
Schema page is displayed, as shown in Figure 6–33.
Figure 6–33 Native Format Builder Wizard Design Schema Page - partner-type Complex
Type
Create an address-type Complex Type
The address element can be further defined as another complex-type that contains a
fixed-length street, city, and so on.
18. Create another <new_complex_type> node in the Schema Tree. See Step 8 in
Create the partner-type Complex Type.
19. Drag and drop the address part in the first row of the sample text to the Complex
Type, <new_complex_type>. The Complex Type Details dialog is displayed.

20. Enter address-type in the Complex Type Name field.
21. Click the ruler to mark fields on the sample text area, and then click the Generate
Fields button. Now, enter street1, street2, city, zip, country, state, and phone in
the Name field, as shown in Figure 6–34.
Figure 6–34 Native Format Builder Wizard Design Schema Page - Complex Type Details
Dialog
22. Click OK. The Native Format Builder Design Schema page is displayed, as shown
in Figure 6–35.

Assign the address-type Complex Type to address field of partner-type Complex
Type
You must assign the address-type complex type to the address field of the partner-type
complex type. You can assign a complex type to an element by using one of the
following methods:
■ Drag and drop the address-type node on the address field node of the
partner-type complex type. This instantly assigns address-type to the address
field element.
■ Select the address field node of the partner-type complex type and then click
the pencil icon.
The Edit Field Details dialog is displayed, as shown in Figure 6–36.
Figure 6–36 Edit Field Details Dialog
23. Select the address-type option in the Type list, and click OK. The address-type
option is assigned to the address field element in the Native Format Builder
Design Schema page, as shown in Figure 6–37.

Create ‘buyer’ and ‘seller’ Global Elements
24. Select Invoice, and click the Add Element icon. An element, <new_element>, is
created in the Schema Tree under the root element, Invoice.
25. Rename it to buyer.
26. Again, select Invoice, and click the Add Element icon. An element, <new_
element>, is created in the Schema Tree under Invoice.
27. Rename it to seller.
Now, drag and drop the partner-type node on each of the buyer and seller nodes,
to assign the partner-type complex type to these nodes. The Schema Tree appears,

Create item-type Complex Type, and items and invoice-total Element Nodes
The items element can be considered an array of item-types. The last line item in the
native file ends with the number sign (#), followed by the line-item total.
28. Select Invoice, and click the Add Element icon. An element, <new_element>, is
created in the Schema Tree under Invoice.
29. Rename it to items.
30. Create the item-type complex type and define the field properties, as shown in
Figure 6–39.

31. Drag and drop item-type complex type to the items element to assign item-type to
this element.
32. Select items - item-type and click the pencil icon. The Element Details dialog is
displayed.
Figure 6–40 Element Details Dialog
33. Set the following properties in the Element Details dialog, as shown in
Figure 6–40:
1. Set Max. Occurence - UNBOUNDED
2. Select Array. The Cell Separator and Array Separator are enabled.
3. Set Cell Separator - ${eol}
4. Set Array Separator - #
34. Click OK.
35. Create the invoice-total element, and drag and drop the sample text (110000) on
the <new_element> node. The Element Details dialog is displayed.
36. Enter invoice-total in the Element Name field, and click Generate Fields. The
Alert message is displayed, as shown in Figure 6–41.
Note: The element items is defined as an array of item-type.

Figure 6–41 Element Details Dialog - Alert Message
If a single field is identified in the sampled data for a global element, then the
properties of this data are applied to the global element itself.
37. Click OK in the Alert message. The Element Details dialog is displayed.
38. Select double in the Data Type list, and click OK. The Native Format Builder
Design Schema page is displayed, as shown in Figure 6–42.
Figure 6–42 Native Format Builder Wizard Design Schema Page - Complete Schema Tree

in Figure 6–43, which displays the native format file.
The native schema definition corresponding to the preceding native data can be
defined as follows:
<schema attributeFormDefault="qualified" elementFormDefault="qualified"
targetNamespace="http://xmlns.oracle.com/ias/pcbpel/fatransschema/demo"
xmlns:tns="http://xmlns.oracle.com/ias/pcbpel/fatransschema/demo"
xmlns="http://www.w3.org/2001/XMLSchema"
nxsd:version="NXSD" nxsd:stream="chars">
<element name="invoice" type="tns:invoiceType" />
<complexType name="invoiceType">
<sequence>
<element name="purchaser" type="tns:partnerType" />
<element name="seller" type="tns:partnerType" />
<element name="line-item" type="tns:line-itemType"
maxOccurs="unbounded" nxsd:style="array"
nxsd:cellSeparatedBy="${eol}" nxsd:arrayTerminatedBy="#"/>
<element name="total" type="double" nxsd:style="terminated"
nxsd:terminatedBy="${eol}"/>
</sequence>
</complexType>
<complexType name="partnerType">
<sequence>
<element name="uid" type="string" nxsd:style="fixedLength"
nxsd:length="7" nxsd:padStyle="tail" nxsd:paddedBy=" "/>
<element name="name" type="string" nxsd:style="surrounded"
nxsd:surroundedBy="^"/>
<element name="address" type="tns:addressType" />
</sequence>

</complexType>
<complexType name="addressType">
<sequence>
<element name="street1" type="string" nxsd:style="fixedLength"
<element name="street2" type="string" nxsd:style="fixedLength"
<element name="city" type="string" nxsd:style="fixedLength"
<element name="postal-code" type="string" nxsd:style="fixedLength"
nxsd:length="5" nxsd:padStyle="none"/>
<element name="country" type="string" nxsd:style="fixedLength"
<element name="state" type="string" nxsd:style="fixedLength"
<element name="phone" type="string" nxsd:style="terminated"
nxsd:terminatedBy="${eol}"/>
</sequence>
</complexType>
<complexType name="line-itemType">
<sequence>
<element name="uid" type="string" nxsd:style="fixedLength"
<element name="description" type="string" nxsd:style="surrounded"
nxsd:surroundedBy="|"/>
<element name="price" type="double" nxsd:style="terminated"
nxsd:terminatedBy=","/>
<element name="quantity" type="integer" nxsd:style="terminated"
nxsd:terminatedBy=","/>
<element name="line-total" type="double" nxsd:style="surrounded"
nxsd:surroundedBy="+"/>
</sequence>
</complexType>
</schema>

41. Click the Generate XML icon. The Result XML is displayed on the right pane of
the Test NXSD Schema dialog, as shown in Figure 6–45.
Figure 6–45 Test NXSD Schema Dialog - Result XML
The translated XML looks as follows:

<invoice xmlns="http://xmlns.oracle.com/pcbpel/demoSchema/invoice-nxsd">
<purchaser>
<uid>6335722</uid>
<name>Company One</name>
<address>
<street1>First Street</street1>
<street2>999</street2>
<city>San Jose</city>
<postal-code>95129</postal-code>
<country>US</country>
<state>CA</state>
<phone>650-801-6250</phone>
</address>
</purchaser>
<seller>
<uid/>
<name>Oracle</name>
<address>
<street1>Bridge Parkway</street1>
<street2>1600</street2>
<city>Redwood Shores</city>
<postal-code>94065</postal-code>
<country>US</country>
<state>CA</state>
<phone>650-506-7000</phone>
</address>
</seller>
<line-item>
<uid>001</uid>
<description>BPEL Process Manager Enterprise Edition</description>
<price>20000</price>
<quantity>2</quantity>
<line-total>40000</line-total>
</line-item>
<line-item>
<uid>002</uid>
<description>BPEL Process Manager Standard Edition</description>
<price>10000</price>
</line-item>
<line-item>
<uid>003</uid>
<description>BPEL Process Manager Developer Edition</description>
<price>1000</price>
</line-item>
<total>110000</total>
</invoice>
42. Click OK. The Generated Native Format File page is displayed, as shown in
Figure 6–43.
Figure 6–15.
44. Click Finish. The Adapter Configuration Wizard Messages page is displayed,
containing the generated NXSD, as shown in Figure 6–16.

6.4.4 Removing or Adding Namespaces to XML with No Namespace
When the native data is XML and that XML has no namespace, the Native Format
Translator can be used to add a namespace to an inbound XML document and remove
the namespace from an outbound XML document.
The XML has no namespace when either of the following is true:
■ The XML has a corresponding XML schema, and there is no target namespace
specified in that XML schema.
■ The XML has a corresponding DTD, which was converted to the XML schema.
In both cases, you must create a wrapper schema with targetNamespace specified,
and the wrapper schema must include the actual schema. In addition, the wrapper
schema must also have the nxsd:version attribute set to DTD. For example:
--wrapper.xsd
targetNamespace="myNamespace"
nxsd:version="DTD">
<include schemaLocation="actual.xsd"/>
</schema>
Using this wrapper.xsd file in place of the original .xsd file would add the
myNamespace namespace to the inbound XML and would remove the myNamespace
namespace from the outbound XML.
6.4.5 Defining the Choice Condition Schema for a Complex File Structure
In this use case, the Native Format Builder uses order.txt, a complex type file, which
contains multiple record types such as order, customer, and items. Also, using this use
case you can generate the NXSD and test it. Perform the following steps to run this use
case:
1. The data in a sample text file, order.txt, appears as below:
Item1, GigaWidget, 60, $75
Item2, MegaBucket, 48, $125
Cust1, Hopkins Associates, ID26490
Item3, Rt.Clopper, 40, $100
Item4, Lt.Clopper, 50, $100
Cust2, Jersey WebInovaters, ID46786
2. Create the following complex types by dragging one row each of order, customer,
and item native data:
■ OrderType
■ ItemType
■ CustomerType
Note: Ensure that elementFormDefault="qualified" is
specified in the actual schema.

For more information about creating a complex type, see Section 6.4.3, "Defining
the Schema for a Complex File Structure".
The Native Format Builder Design Schema page is displayed as shown in
Figure 6–46.
Figure 6–46 Native Format Builder Design Schema Page
3. Click Add Choice Node. The Choice Option Type dialog is displayed.
4. Set the options in the Choice Option Type dialog as shown in Figure 6–47, and
then click OK.
Figure 6–47 The Choice Option Type Dialog
5. Select choice and click the Add Element icon. A <new_element> is added to the
choice node.
6. Rename the newly added element to OrderChoice, and then drag and drop the
OrderType complex type element to OrderChoice.

7. Select OrderChoice - string and click the Edit Node icon. The Element Details
dialog is displayed.
8. Enter Order in the Choice Value field, as shown in Figure 6–48, and then click
OK.
Figure 6–48 The Element Details Dialog
9. Follow Step 5 to 8 to create the ItemChoice choice complex type with ItemType
data type and CustomerChoice choice complex type with CustomerType data
type. The Native Format Builder Design Schema dialog is displayed as shown in
Figure 6–49.
Note: You should specify four characters in Choice Value field as the
Length field has the value 4 in it.

Figure 6–50 Generated Native Format Schema File Page
Native Schema
defined as follows:
xmlns:tns="http://TargetNamespace.com/test"
targetNamespace="http://TargetNamespace.com/test"
nxsd:version="NXSD"
nxsd:stream="chars"
>
<xsd:complexType>
nxsd:choiceCondition="fixedLength" nxsd:length="4">
<xsd:element name="OrderChoice" type="tns:OrderType"
nxsd:conditionValue="Orde" />
<xsd:element name="ItemChoice" type="tns:ItemType"
nxsd:conditionValue="Item" />
<xsd:element name="CustomerChoice" type="tns:customerType"
nxsd:conditionValue="Cust" />
</xsd:choice>
</xsd:complexType>
</xsd:element>
<xsd:complexType name="customerType">
<xsd:sequence>

</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="ItemType">
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="OrderType">
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
11. Click Test. The Test NXSD Schema dialog is displayed.

<Root-Element xmlns="http://TargetNamespace.com/test">
<OrderChoice>
<C1>r</C1>
<C2> ID41678</C2>
<C3> 20May2000</C3>
</OrderChoice>
<ItemChoice>
<C1>1</C1>
<C2> GigaWidget</C2>
<C3> 60</C3>
<C4> $75</C4>
</ItemChoice>
<ItemChoice>
<C1>2</C1>
<C2> MegaBucket</C2>
<C3> 48</C3>
<C4> $125</C4>
</ItemChoice>
<CustomerChoice>
<C1>1</C1>
<C2> Hopkins Associates</C2>
<C3> ID26490</C3>
</CustomerChoice>
<OrderChoice>
<C1>r</C1>
<C2> ID41680</C2>
<C3> 20May2000</C3>
</OrderChoice>
<ItemChoice>
<C1>3</C1>
<C2> Rt.Clopper</C2>
<C3> 40</C3>
<C4> $100</C4>
</ItemChoice>
<ItemChoice>
<C1>4</C1>
<C2> Lt.Clopper</C2>
<C3> 50</C3>
<C4> $100</C4>
</ItemChoice>
<CustomerChoice>
<C1>2</C1>
<C2> Jersey WebInovaters</C2>
<C3> ID46786</C3>
</CustomerChoice>
</Root-Element>
13. Click OK. The Generated Native Format File page is displayed.
14. Click Next. The Native Format Builder Finish page is displayed.
6.4.6 Defining Choice Condition With LookAhead for a Complex File Structure
In this use case, the Native Format Builder uses address.txt, a complex type file,
which contains multiple records with different addresses. In this use case, you would
build a schema which has 2 record types. The RecOne record takes data for records

ending with text “YES” and the RecTwo record takes data for records ending with text
“NO ”.
Also, using this use case you can generate the NXSD and test it. Perform the following
steps to run this use case:
1. The data in a sample text file, address.txt, appears as below:
2. Launch the Adapter Configuration Wizard and navigate to the Messages page,
and click Define Schema For Native Format. The Native Format Builder Welcome
page is displayed.
4. Select Complex Type and click Next. The Native Format Builder File Description
page is displayed.
5. Click Browse and select the address.txt file, and enter Address in the Root Element
field.
6. Click Next. The Native Format Builder Design Schema page is displayed.
7. Click the Add Complex Type icon. A Complex Type, <new_complex_type> is
created in the Schema Tree under Address.
8. Select the first row of the sample text from the right-hand pane of the Sample File
section, and drag and drop it on the <new_complex_type> node. The Complex
Type Details dialog is displayed.
9. Enter RECORD1 in the Complex Type Name field and select Comma (,) in the
Delimited By list.
10. Click OK. The Native Format Builder Design Schema page is displayed, as shown
in Figure 6–52.

11. Similarly, create another complex type node called RECORD2. The Native Format
Builder Design Schema page is displayed, as shown in Figure 6–53.
12. Click Add Choice Node. The Choice Option Type dialog is displayed.
13. Set the options in the Choice Option Type dialog, as shown in Figure 6–54, and
then click OK.
Figure 6–54 The Choice Option Type Dialog
14. Select choice and click the Add Element icon. A <new_element> is added to the
choice node.
15. Click the Edit Node icon. The Element Details dialog is displayed.
16. Enter RECONE in the Element Name field and select RECORD1 as the Data Type
set choice condition as “YES”, and then click OK.

17. Follow Step 14 to 16 to create the RECTWO choice element for the choice node and
set choice condition as “NO ”.
The Native Format Builder Design Schema dialog is displayed as shown in
Figure 6–55.
18. Drag and drop the RECORD1 complex type to the RECONE element under choice
and the RECORD2 complex type to the RECTWO element under choice. The
Native Format Builder Design Schema dialog is displayed.
Note: There is one space after chars “NO”, since you need to match
the total no. of characters to three.

Native Schema
defined as follows:
xmlns:tns="http://TargetNamespace.com/tesNew"
targetNamespace="http://TargetNamespace.com/tesNew"
nxsd:version="NXSD"
nxsd:stream="chars"
>
<xsd:complexType>
nxsd:choiceCondition="${X}" nxsd:lookAhead="70" nxsd:scanLength="3"
nxsd:assignTo="${X}">
<xsd:element name="RECTWO" type="tns:RECORD2" nxsd:conditionValue="NO "
/>
<xsd:element name="RECONE" type="tns:RECORD1" nxsd:conditionValue="YES"
/>
</xsd:choice>
</xsd:complexType>
</xsd:element>
<xsd:complexType name="RECORD2">
<xsd:sequence>

</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="RECORD1">
<xsd:sequence>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<Root-Element xmlns="http://TargetNamespace.com/tesNew">
<RECONE>

<C1>Name1</C1>
<C2>2 Old Street, Old Town,Manchester</C2>
<C3>20-08-1954</C3>
<C4>0161-499-1718</C4>
<C5> YES</C5>
</RECONE>
<RECTWO>
<C1>Name2</C1>
<C3>20-08-1954</C3>
<C4>0161-499-1718</C4>
<C5> NO </C5>
</RECTWO>
<RECTWO>
<C1>Name3</C1>
<C3>20-08-1954</C3>
<C4>0161-499-1718</C4>
<C5> NO </C5>
</RECTWO>
<RECONE>
<C1>Name4</C1>
<C3>20-08-1954</C3>
<C4>0161-499-1718</C4>
<C5> YES</C5>
</RECONE>
</Root-Element>
6.4.7 Defining Array Type Schema for a Complex File Structure
In this use case, the Native Format Builder uses array.txt, a complex type file, which
contains an array of items. The sample data has four names which are separated by a
semicolon and ending with a period. In this use case, you would create a schema with
array type which has member names separated by a semicolon and array terminated
by a period. Also, using this use case you can generate the NXSD and test it.
Perform the following steps to run this use case:
1. The data in a sample text file, array.txt, appears as below:
John;Steve;Paul;Todd.
2. Launch the Adapter Configuration Wizard and navigate to the Messages page and
click Define Schema For Native Format. The Native Format Builder Welcome
page is displayed.
4. Select Complex Type and click Next. The Native Format Builder File Description
page is displayed.
Note: There are 2 recordtypes: RECONE and RECTWO. RECONE
takes records that end with character YES and RECTWO takes records
that end with character NO.

5. Click Browse and select the array.txt file, as shown in Figure 6–58. The Native
Format Builder File Description page is displayed.
Figure 6–58 Native Format Builder File Description Page
6. Click Next. The Native Format Builder Design Schema Page is displayed.
7. Create a global element called NewArray and drag and drop the native data to the
newly created global element.
8. Select NewArray, as shown in Figure 6–59, and click the Edit Node icon. The
Element Details dialog is displayed.
9. Set the options in the Element Details dialog, as shown in Figure 6–60, and then
click OK.

Figure 6–60 Element Details Dialog
The Native Format Builder Design Schema dialog is displayed.
Native Schema
defined as follows:
xmlns:tns="http://TargetNamespace.com/testnewArray"
targetNamespace="http://TargetNamespace.com/testnewArray"

nxsd:version="NXSD"
nxsd:stream="chars"
>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="NewArray" type="xsd:string" maxOccurs="unbounded"
nxsd:style="array" nxsd:cellSeparatedBy=";" nxsd:arrayTerminatedBy="." />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
<Root-Element xmlns="http://TargetNamespace.com/testnewArray">
<NewArray>John</NewArray>
<NewArray>Steve</NewArray>
<NewArray>Paul</NewArray>
<NewArray>Todd</NewArray>
</Root-Element>

6.4.8 Defining the Schema for a DTD File Structure
This use case takes you through the procedure for defining the schema for the native
data type, DTD file.
Use the DTD to be converted to XSD option in the Native Format Builder wizard
when creating the XML schema for this native file.
In this use case, the Native Format Builder uses a DTD file type db.dtd. Every
element in this db.dtd native file has a fixed length. You can generate the
1. Use any sample DTD file, for example, the db.dtd file. The db.dtd file can be
copied from the following location:
4. Select DTD to be converted to XSD. The Choose Type page is displayed, as shown
in Figure 6–63.
5. Click Next. The Native Format Builder DTD Description page is displayed.
6. Click Browse and select the db.dtd file, and select DatabaseInventory from the
Root Element list, as displayed in Figure 6–64.

7. Click Next. The Generated Native Format File page is displayed, as shown in
Figure 6–65.
The following is the sample native schema that is generated:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://TargetNamespace.com/ReadUI"
xmlns="http://TargetNamespace.com/ReadUI" nxsd:version="DTD"
xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd">
<xs:element name="GlobalDatabaseName" type="xs:string"/>

<xs:element name="DatabaseAttributes">
<xs:complexType>
<xs:attribute name="Type" use="required">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="Production"/>
<xs:enumeration value="Development"/>
<xs:enumeration value="Testing"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="Version" use="optional" default="9i">
<xs:simpleType>
<xs:restriction base="xs:NMTOKEN">
<xs:enumeration value="7"/>
<xs:enumeration value="8"/>
<xs:enumeration value="8i"/>
<xs:enumeration value="9i"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name="Comments" type="xs:string"/>
<xs:element name="Administrator">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="EmailAlias" use="required"
type="xs:string"/>
<xs:attribute name="Extension" use="optional" type="xs:string"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="OracleSID" type="xs:string"/>
<xs:element name="DatabaseName">
<xs:complexType>
<xs:sequence>
<xs:element ref="GlobalDatabaseName"/>
<xs:element ref="OracleSID"/>
<xs:element ref="DatabaseDomain"/>
<xs:element maxOccurs="unbounded" ref="Administrator"/>
<xs:element ref="DatabaseAttributes"/>
<xs:element ref="Comments"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="DatabaseDomain" type="xs:string"/>
<xs:element name="DatabaseInventory">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" ref="DatabaseName"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>

9. Click Finish. The Adapter Configuration Wizard Messages page is displayed
containing the generated NXSD.
6.4.9 Defining the Schema for a COBOL Copybook File Structure
This use case shows how the Oracle File and FTP Adapters process a file in COBOL
Copybook format (through use of the Native Format Builder Wizard) to create a native
schema file for translation.
The following COBOL Copybook examples are provided:
■ Multiple Root Levels
■ Single Root Level, Virtual Decimal, Fixed-Length Array
■ Variable Length Array
■ Numeric Types
Multiple Root Levels
A COBOL Copybook can have multiple root levels. If all root levels are at 01 level,
then each such group implicitly redefines the other.
In this use case, the Native Format Builder uses a fixed-length file type, po-ccb.cpy,
that contains the purchase order details such as buyer name, address, and items. Every
element in this po-ccb.cpy native file has a fixed length. You can generate the
1. The data in a sample text file, po-ccb.cpy, appears as follows:
05 PO-RECORD.
10 PO-BUYER.
15 PO-UID PIC 9(7).
15 PO-NAME PIC X(15).
15 PO-ADDRESS.
20 PO-STREET PIC X(15).
20 PO-CITY PIC X(10).
20 PO-ZIP PIC 9(5).
20 PO-STATE PIC X(2).
10 PO-ITEM.
15 POITEM OCCURS 3 TIMES.
20 PO-LINE-ITEM.
25 PO-ITEM-ID PIC 9(3).
25 PO-ITEM-NAME PIC X(40).
25 PO-ITEM-QUANTITY PIC 9(2).
25 PO-ITEM-PRICE PIC 9(5)V9(2).
10 PO-TOTALPIC 9(7)V9(2).
Also, copy the po-ebcdic.data file from
code/products/adapters) to your samples directory.
4. Select Cobol Copybook to be converted to native format. The Choose Type page

5. Click Next. The Native Format Builder Cobol Copybook Description page is
displayed.
6. Click Browse and select the po-ccb.cpy file, as shown in Figure 6–67.
7. Enter PurchaseOrder in the Root-Element field, and click Next. The Generated
Native Format File page is displayed, as shown in Figure 6–68.

The top level payroll records are enclosed in a choice model group. Each payroll
record also has two attributes, nxsd:lookAhead and nxsd:lookFor that help
identify the type of record during run-time processing of the data file. So, you
must add values for these attributes. For example, assume PAYROLL-F-RECORD
occurs when the PAYROLL-F-TRANS-CODE field has a value of FR. The record
element then looks as follows:
<xsd:element name="PAYROLL-F-RECORD" nxsd:lookAhead="10" nxsd:lookFor="FR">
The value 10 indicates the position of the lookahead field. The following COBOL
Copybook has multiple root elements at the 05 level:
05 ORG-NUM PIC 99.
05 EMP-RECORD.
10 EMP-SSN PIC 9(4)V(6).
10 EMP-WZT PIC 9(6).
Native Schema

xmlns:extn="http://xmlns.oracle.com/pcbpel/nxsd/extensions"
targetNamespace="http://TargetNamespace.com/Read"
xmlns:tns="http://TargetNamespace.com/Read" elementFormDefault="qualified"
attributeFormDefault="unqualified" nxsd:version="NXSD" nxsd:encoding="cp037"
nxsd:byteOrder="bigEndian" nxsd:stream="chars">
<xsd:element name="PurchaseOrder">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="PO-RECORD" minOccurs="1" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="PO-BUYER">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="PO-UID" type="xsd:long"
nxsd:style="fixedLength" nxsd:padStyle="head"
nxsd:paddedBy="0"
nxsd:length="7"/>

<xsd:element name="PO-NAME" type="xsd:string"
nxsd:style="fixedLength" nxsd:padStyle="tail"
nxsd:paddedBy=" "
nxsd:length="15"/>

<xsd:element name="PO-ADDRESS">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="PO-STREET"
type="xsd:string"
nxsd:padStyle="tail"
nxsd:paddedBy=" " nxsd:length="15"/>

<xsd:element name="PO-CITY"
type="xsd:string"

<xsd:element name="PO-ZIP"
type="xsd:long"
nxsd:padStyle="head"
nxsd:paddedBy="0" nxsd:length="5"/>

<xsd:element name="PO-STATE"
type="xsd:string"
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="PO-ITEM">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="POITEM" minOccurs="3"
maxOccurs="3">
<xsd:complexType>

<xsd:sequence>

<xsd:element name="PO-LINE-ITEM">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="PO-ITEM-ID"
type="xsd:long"

<xsd:element name="PO-ITEM-NAME"
type="xsd:string"
nxsd:paddedBy="
" nxsd:length="40"/>

<xsd:element name="PO-ITEM-QUANTITY"
type="xsd:long"
nxsd:paddedBy="0"
nxsd:length="2"/>

<xsd:element name="PO-ITEM-PRICE"
type="xsd:decimal"
nxsd:style="virtualDecimal"
extn:assumeDecimal="5" extn:picSize="7"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="PO-TOTAL"
type="xsd:decimal"
nxsd:style="virtualDecimal" extn:assumeDecimal="7"
extn:picSize="9"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
9. Click Browse and select the po-ebcdic.data file in the File Name field. The
Test NXSD Schema dialog is displayed, as shown in Figure 6–69.

The native data using the corresponding native schema format is translated to the
following XML:
<PurchaseOrder xmlns="http://TargetNamespace.com/Read">
<PO-RECORD>
<PO-BUYER>
<PO-UID>6335722</PO-UID>
<PO-NAME>Company One</PO-NAME>
<PO-ADDRESS>
<PO-STREET>First Street</PO-STREET>
<PO-CITY>San Jose</PO-CITY>
<PO-ZIP>95129</PO-ZIP>
<PO-STATE>CA</PO-STATE>
</PO-ADDRESS>
</PO-BUYER>
<PO-ITEM>
<POITEM>
<PO-LINE-ITEM>
<PO-ITEM-ID>1</PO-ITEM-ID>
<PO-ITEM-NAME>BPEL Process Manager Enterprise
Edition</PO-ITEM-NAME>
<PO-ITEM-QUANTITY>2</PO-ITEM-QUANTITY>
<PO-ITEM-PRICE>40000.0</PO-ITEM-PRICE>
</PO-LINE-ITEM>
</POITEM>
<POITEM>
<PO-LINE-ITEM>
<PO-ITEM-NAME>BPEL Process Manager Standard
</PO-LINE-ITEM>
</POITEM>
<POITEM>
<PO-LINE-ITEM>
<PO-ITEM-NAME>BPEL Process Manager Developer
</PO-LINE-ITEM>
</POITEM>
</PO-ITEM>
<PO-TOTAL>730000.0</PO-TOTAL>
</PO-RECORD>
</PurchaseOrder>
In this (non-01 level) case, an unbounded sequence of the root level items is
generated.
13. Click Finish. The Adapter Configuration Wizard Messages page is displayed,
containing the generated NXSD.

Single Root Level, Virtual Decimal, Fixed-Length Array
The following COBOL Copybook has a single root level item PO-RECORD. In a single
root level case, the level number does not matter because the converter works in the
same way. This COBOL Copybook also shows an example of a field declared as a
virtual decimal (PO-ITEM-PRICE).
05 PO-RECORD.
10 PO-BUYER.
15 PO-UID PIC 9(7).
15 PO-NAME PIC X(15).
15 PO-ADDRESS.
20 PO-STREET PIC X(15).
20 PO-CITY PIC X(10).
20 PO-ZIP PIC 9(5).
20 PO-STATE PIC X(2).
10 PO-ITEM.
15 POITEM OCCURS 3 TIMES.
20 PO-LINE-ITEM.
25 PO-ITEM-ID PIC 9(3).
25 PO-ITEM-NAME PIC X(40).
25 PO-ITEM-QUANTITY PIC 9(2).
25 PO-ITEM-PRICE PIC 9(5)V9(2).
10 PO-TOTAL PIC 9(7)V9(2).
The generated schema looks as follows:

targetNamespace="http://TargetNamespace.com/ccb/singleRoot"
xmlns:tns="http://TargetNamespace.com/ccb/singleRoot"
nxsd:version="NXSD" nxsd:encoding="cp037" nxsd:byteOrder="bigEndian"
nxsd:stream="chars">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="PO-RECORD" minOccurs="1" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="PO-BUYER">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="PO-UID" type="xsd:long"

<xsd:element name="PO-NAME" type="xsd:string"

<xsd:element name="PO-ADDRESS">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="PO-STREET" type="xsd:string"
nxsd:padStyle="tail" nxsd:paddedBy=" "
nxsd:length="15"/>

<xsd:element name="PO-CITY" type="xsd:string"
nxsd:length="10"/>

<xsd:element name="PO-ZIP" type="xsd:long"
nxsd:padStyle="head" nxsd:paddedBy="0"
nxsd:length="5"/>

<xsd:element name="PO-STATE" type="xsd:string"
nxsd:length="2"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="PO-ITEM">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="POITEM" minOccurs="3" maxOccurs="3">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="PO-LINE-ITEM">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="PO-ITEM-ID" type="xsd:long"

<xsd:element name="PO-ITEM-NAME"
type="xsd:string"

<xsd:element name="PO-ITEM-QUANTITY"
type="xsd:long"

<xsd:element name="PO-ITEM-PRICE"
type="xsd:decimal"
nxsd:style="virtualDecimal"
extn:assumeDecimal="5"

extn:picSize="7"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

<xsd:element name="PO-TOTAL" type="xsd:decimal"
extn:picSize=" "/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
Variable Length Array
05 EMP-RECORD .
10 EMP-NAME PIC X(30).
10 EMP-DIV-NUM PIC 9(5).
10 DIV-ENTRY OCCURS 1 TO 50 TIMES
DEPENDING ON EMP-DIV-NUM.
20 DIV-CODE PIC X(30).

targetNamespace="http://TargetNamespace.com/ccb/varLengthArray"
xmlns:tns="http://TargetNamespace.com/ccb/varLengthArray"
nxsd:stream="chars">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="EMP-RECORD" minOccurs="1" maxOccurs="unbounded">
<xsd:annotation>
<xsd:appinfo>
<nxsd:variables>
<nxsd:variable name="DIV-ENTRY_var0"/>
</nxsd:variables>
</xsd:appinfo>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>

<xsd:element name="EMP-NAME" type="xsd:string"

<xsd:element name="EMP-DIV-NUM" type="xsd:long"
nxsd:paddedBy="0" nxsd:length="5">
<xsd:annotation>
<xsd:appinfo>
<nxsd:variables>
<nxsd:assign name="DIV-ENTRY_var0" value="${0}"/>
</nxsd:variables>
</xsd:appinfo>
</xsd:annotation>
</xsd:element>

<xsd:element name="DIV-ENTRY" nxsd:style="array"
nxsd:arrayLength="${DIV-ENTRY_var0}" minOccurs="1"
maxOccurs="50">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="DIV-CODE" type="xsd:string"
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
Numeric Types
01 NUMERIC-FORMATS.
05 Salary PIC 9(5) COMP-3.
05 Rating PICTURE S9(5).
05 Age PIC 9(3) USAGE COMP.
05 Revenue PIC 9(3)V9(2).
05 Growth PIC S9(3) SIGN IS LEADING.
05 Computation COMP-1.

targetNamespace="http://TargetNamespace.com/ccb/numeric"
xmlns:tns="http://TargetNamespace.com/ccb/numeric"
nxsd:stream="bytes">
<xsd:element name="Numerics">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="NUMERIC-FORMATS" minOccurs="1" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>

<xsd:element name="Salary" type="xsd:long" nxsd:style="comp3"
extn:sign="unticked" extn:picSize="5"/>

<xsd:element name="Rating" type="xsd:string"
nxsd:style="signZoned" extn:sign="ticked"
extn:picSize="5" extn:signPosn="tailUpperNibble"/>

<xsd:element name="Age" type="xsd:long" nxsd:style="comp"
extn:picSize="3" extn:sign="unticked"/>

<xsd:element name="Revenue" type="xsd:decimal"
extn:picSize="5"/>

<xsd:element name="Growth" type="xsd:string"
nxsd:style="signZoned" extn:sign="ticked"
extn:picSize="3" extn:signPosn="headUpperNibble"/>

<xsd:element name="Computation" type="xsd:float"
nxsd:style="comp1" extn:sign="ticked"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
In this case, all the numeric types follow formats specified according to IBM COBOL
formats. If the data file originates from a different system by using different layouts,
then the generated schema requires modification.

Part IIPart II
Message Adapters
Part II contains the following chapters:
■ Oracle JCA Adapter for AQ
■ Oracle JCA Adapter for JMS
■ Oracle JCA Adapter for Database
■ Oracle JCA Adapter for MQ Series
■ Troubleshooting and Workarounds

7
Oracle JCA Adapter for AQ 7-1
7Oracle JCA Adapter for AQ
This chapter describes how to use the Oracle JCA Adapter for AQ (Oracle AQ
Adapter), which enables an Oracle BPEL Process Manager or an Oracle Mediator to
interact with a single consumer or a multiconsumer queue.
■ Section 7.1, "Introduction to the Oracle AQ Adapter"
■ Section 7.2, "Oracle AQ Adapter Features"
■ Section 7.3, "Oracle AQ Adapter Use Cases"
7.1 Introduction to the Oracle AQ Adapter
Oracle Streams Advanced Queuing (AQ) provides a flexible mechanism for
bidirectional, asynchronous communication between participating applications.
Advanced queues are an Oracle database feature, and are therefore scalable and
reliable. Other features of Oracle database, such as backup and recovery (including
any-point-in-time recovery), logging, transactional services, and system management,
are also inherited by 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.
This section includes the following sections:
■ Section 7.1.1, "Oracle AQ Adapter Integration with Oracle BPEL Process Manager"
■ Section 7.1.2, "Oracle AQ Adapter Integration with Oracle Mediator"
7.1.1 Oracle AQ Adapter Integration with Oracle BPEL Process Manager
JCA Binding Component is used for the bidirectional integration of the JCA 1.5
resource adapters with Oracle BPEL Process Manager. JCA Binding Component is
based on standards and employs the Web service Invocation Framework (WSIF)
technology for exposing the underlying JCA interactions as Web services.
For more information about Oracle AQ Adapter architecture, adapter integration with
Oracle BPEL Process Manager, and adapter deployments, see Chapter 3, "Adapter
Integration with Oracle Application Server Components."
7.1.2 Oracle AQ Adapter Integration with Oracle Mediator
The Mediator Server supports Oracle AQ Adapter and enables you to define inbound
and outbound adapter services for each. An inbound adapter service receives data
from an Oracle AQ Adapter and transforms it into an XML message. An outbound

Oracle AQ Adapter Features
adapter service sends data to a target application by transforming an XML message
into the native format of the given adapter.
Using the Mediator Server, you can send or receive messages from Oracle Advanced
Queuing single or multiconsumer queues.
7.2 Oracle AQ Adapter Features
The Oracle AQ Adapter is both a producer and a consumer of AQ messages. The
enqueue operation is exposed as a JCA outbound interaction. The dequeue operation
is exposed as a JCA inbound interaction.
The Oracle AQ Adapter supports ADT (Oracle object type), XMLType, and RAW queues
as payloads. It also supports extracting a payload from one ADT member column.
The Oracle AQ Adapter supports normalized properties for enqueue and dequeue
operations.
For more information about the properties supported by Oracle AQ Adapter, see
Appendix A.3, "Oracle AQ Adapter Properties."
For Oracle AQ Adapter samples, go to
■ Section 7.2.1, "Enqueue-Specific Features (Message Production)"
■ Section 7.2.2, "Dequeue and Enqueue Features"
■ Section 7.2.3, "Supported ADT Payload Types"
■ Section 7.2.4, "Native Format Builder Wizard"
■ Section 7.2.5, "Normalized Message Support"
■ Section 7.2.6, "Is DOM 2 Compliant"
■ Section 7.2.7, "Is Message-Size Aware"
■ Section 7.2.8, "Multiple Receiver Threads"
■ Section 7.2.9, "DequeueTimeout Property"
■ Section 7.2.10, "Control Dequeue Timeout and Multiple Inbound Polling Threads"
■ Section 7.2.11, "Stream Payload Support"
■ Section 7.2.12, "Oracle AQ Adapter Inbound Retries"
■ Section 7.2.13, "Error Handling Support"
7.2.1 Enqueue-Specific Features (Message Production)
The Oracle AQ Adapter supports the following features of Oracle Streams AQ:
■ Correlation Identifier
Note: Oracle BPEL Process Manager pre-dates Mediator and most of
this guide and the samples implicitly assume use with Oracle BPEL
Process Manager. However, the Oracle AQ Adapter works equally
well with either Oracle BPEL Process Manager or Mediator. For any
mention of Oracle BPEL Process Manager here, you may substitute
Mediator, instead.

In the Adapter Configuration Wizard, you can specify a correlation identifier
when defining an enqueue operation, which you use to retrieve specific messages.
■ Multiconsumer Queue
In Oracle Streams AQ, more than one consumer can process and consume a single
message. To use this feature, you must create multiconsumer queues and enqueue
the messages into these queues. In this configuration, a single message can be
consumed by more than one AQ consumer (dequeue operation), either through
the default subscription list or with an override recipient list. Under this scenario,
a message remains in the queue until it is consumed by all of its intended
consumer agents. The Oracle AQ Adapter enqueue header property
(jca.aq.RecipientList) enables you to specify the override recipient list
(string values separated by commas) that can retrieve messages from a queue. All
consumers that are added as subscribers to a multiconsumer queue must have
unique values for the Recipient parameter. This means that two subscribers
cannot have the same values for the NAME, ADDRESS, and PROTOCOL attributes.
■ Message Priority
If you specify the priority of enqueued messages, then the messages are dequeued
in priority order. If two messages have the same priority, then the order in which
they are dequeued is determined by the enqueue time. You can also create a
first-in, first-out (FIFO) priority queue by specifying the enqueue time priority as
the sort order of the messages. This priority is a property of the Oracle AQ
Adapter enqueue header. The enqueue time is set automatically by the underlying
AQ application.
Here is an example of how to create the FIFO queue:
EXECUTE DBMS_AQADM.CREATE_QUEUE_TABLE(
queue_table => 'OE_orders_pr_mqtab',
sort_list =>'priority,enq_time',
comment => 'Order Entry Priority
MultiConsumer Orders queue table',
multiple_consumers => TRUE,
queue_payload_type => 'BOLADM.order_typ',
compatible => '8.1',
primary_instance => 2,
secondary_instance => 1);
EXECUTE DBMS_AQADM.CREATE_QUEUE (
queue_name => 'OE_bookedorders_que',
queue_table => 'OE_orders_pr_mqtab');
■ Time Specification and Scheduling
In Oracle Streams AQ, you can specify a delay interval and an expiration interval.
The delay interval determines when an enqueued message is marked as available
to the dequeuers after the message is enqueued. When a message is enqueued
with a delay time set, the message is marked in a WAIT state. Messages in a WAIT
state are masked from the default dequeue calls. The expiration time property is
used to specify an expiration time, and the message is automatically moved to an
exception queue if the message is not consumed before its expiration.
7.2.2 Dequeue and Enqueue Features
Oracle Streams AQ provides the following dequeuing options:
■ Poll option
■ Notification option

The poll option involves processing the messages as they arrive and polling repeatedly
for messages. The Oracle AQ Adapter supports a polling mechanism for consuming
AQ messages.
The Oracle AQ Adapter supports the following features of Oracle Streams AQ:
■ Multiconsumer Queue
The Oracle AQ Adapter can retrieve messages from a multiconsumer queue.
■ Navigation of Messages for Dequeuing
Messages do not have to be dequeued in the same order in which they were
enqueued. You can use a correlation identifier to specify dequeue order. The
Adapter Configuration Wizard defines the correlation ID for the dequeue
operation.
■ Retries with Delays
The number of retries is a property of the Oracle AQ Adapter dequeue header. If
the number of retries exceeds the limit, then the message is moved to an exception
queue that you specify. The exception queue is a property of the Oracle AQ
Adapter enqueue header.
■ Rule-Based Subscription
Oracle Streams AQ provides content-based message filtering and subject-based
message filtering. A rule defines one or more consumers’ interest in subscribing to
messages that conform to that rule. For a subject-based rule, you specify a Boolean
expression using syntax similar to the WHERE clause of a SQL query. This Boolean
expression can include conditions on message properties (current priority and
correlation ID), user data properties (object payloads only), and functions (as
specified in the WHERE clause of a SQL query).
■ Oracle AQ Adapter Header Properties
For more information about Oracle AQ Adapter header properties, see
Appendix A.3, "Oracle AQ Adapter Properties."
■ Dequeue Condition
The Dequeue condition is an advanced queuing product feature that Oracle AQ
Adapter uses. If a dequeue condition is specified and no messages meet the
specified condition, then no dequeue will happen.
A dequeue condition element is a Boolean expression using syntax similar to the
WHERE clause of a SQL query. This Boolean expression can include conditions on
message properties, user object payload data properties, and PL/SQL or SQL
functions. Message properties include priority, corrid, and other columns in
the queue table.
For more information about Oracle AQ Adapter architecture, adapter integration with
Oracle BPEL Process Manager, and adapter deployments, see Chapter 1, "Introduction
to Oracle JCA Adapters."
7.2.3 Supported ADT Payload Types
The Oracle AQ Adapter supports the following RAW types:
■ BLOB
■ CHAR
■ CLOB

■ DATE
■ DECIMAL
■ DOUBLE PRECISON
■ FLOAT
■ INTEGER
■ NUMBER
■ REAL
■ SMALLINT
■ TIMESTAMP
■ VARCHAR2
In addition to the RAW types mentioned in the preceding list, the Oracle AQ Adapter
supports primitive types and varrays of objects.
If you choose a payload field instead of the whole ADT, then choose only one of the
following data types as the payload field:
■ CLOB, either XSD or opaque schema
■ VARCHAR2, either XSD or opaque schema
■ BLOB, opaque schema only
■ XMLTYPE, either XSD or opaque schema
7.2.4 Native Format Builder Wizard
JDeveloper BPEL Designer provides the Native Format Builder Wizard to define XSD
files of various formats, including for the AQ RAW payload.
For more information about the Native Format Builder Wizard, see Chapter 6, "Native
Format Builder Wizard."
For Native Format Builder examples, go to
Payload Schema
The payload schemas depend on the payload type. In the whole ADT case, the schema
is completely generated by the Adapter Configuration Wizard. In an ADT case where
the payload case selected is BLOB, an opaque schema as defined in the following
example must be used:
<element name="opaqueElement" type="base64Binary" />
In all other cases, you can either provide a schema or use an opaque schema, as shown
in Table 7–1.
Note: The Oracle AQ Adapter does not currently support the
following data types for ADT columns: TIMESTAMP WITH LOCAL
TIMEZONE and TIMESTAMP WITH TIMEZONE.

If you do not have an XSD file but the payload data is formatted in some way (for
example, in a comma-delimited value (CSV) format), then the Native Format Builder
Wizard can be used to generate an appropriate XSD. The Adapter Configuration
Wizard is integrated with the Native Format Builder Wizard. In the Adapter
Configuration Wizard Messages window, click Define Schema for Native Format to
access the Native Format Builder Wizard.
7.2.5 Normalized Message Support
Header manipulation and propagation is a key business integration messaging
requirement. Oracle BPEL Process Manager, Mediator, Oracle JCA, and B2B rely
extensively on header support to solve customers’ integration needs. For example, you
can preserve a file name from the source directory to the target directory by
propagating it through message headers. In Oracle BPEL Process Manager and
Mediator, you can access, manipulate, and set headers with varying degrees of UI
support.
Propagating Headers in a Normalized Message:
A normalized message is simplified to have only two parts, properties and payload.
Typically, properties are name-value pairs of scalar types. To fit the existing complex
headers into properties, properties will be flattened into scalar types.
Manipulating Headers in Design Time:
The user experience is simplified while manipulating headers in design time, because
the complex properties are predetermined. In the Mediator or BPEL designer, you can
manipulate the headers with some reserved key words. For example, currently in
Mediator, you can access an inbound File adapter, fileName header using the following
expression:
$nmproperty.InboundFileHeaderType.fileName
However, this method does not address the properties that are dynamically generated
based on your input. For example, in the AQ Adapter Wizard, you are allowed to
propagate some of the fields from an AQ object as headers. Based on your choice, the
header definitions are defined. These definitions are not predetermined and hence
Table 7–1 Payload Schema
Payload Type Supported Schema
RAW User-provided schema or opaque schema.
Whole ADT Must use a schema generated by the Adapter
Configuration Wizard, which is based on the queue
structure.
ADT with VARCHAR2 picked as payload User-provided schema or opaque schema.
ADT with CLOB picked as payload
user-provided schema or opaque schema
User-provided schema or opaque schema.
ADT with BLOB picked as payload opaque
schema
Opaque schema.
XMLTYPE User-provided schema or opaque schema.
Note: AQ Adapter inbound and outbound headers supported in the
10.1.3 release are supported in 11g through normalized message
properties.

cannot be accounted for in the list of predetermined property definitions. You cannot
design header manipulation of the dynamic properties before they are defined. To
address this limitation, you must generate all the necessary services (composite entry
points) and references. This restriction applies to services that are expected to generate
dynamic properties. Once dynamic properties are generated, they must be stored for
each composite. Only then you can manipulate the dynamic properties in Mediator or
BPEL designer.
Identifying Properties That Must Be Propagated over the Life Cycle of the
Normalized Message:
Some properties must be propagated across the life cycle of the message, whereas
some must not be propagated. The properties that must be propagated are referred to
as propagatable properties, whereas properties that must not be propagated are referred
to as non-propagatable properties.
7.2.6 Is DOM 2 Compliant
Oracle AQ Adapter is Document Object Model Level 2 (DOM 2) compliant, that is, the
AQ adapter is able to process and generate document objects that are compliant with
DOM2 specification.
7.2.7 Is Message-Size Aware
Oracle AQ Adapter is message-size aware, that is, Oracle AQ Adapter calculates the
message size and reports the size back to JCA Binding Component. The API, related to
size, exposed by JCA Binding Component can be used for reporting purposes.
7.2.8 Multiple Receiver Threads
Oracle AQ Adapter supports an activation endpoint property,
"adapter.aq.dequeue.threads". Setting this property is a preferred way to
spawn multiple threads for the inbound message flow between the adapter and the
Enterprise Information System (EIS). Earlier versions of the Oracle AQ Adapter relied
on the activationInstances endpoint property, which was used by JCA Binding
Component to initiate multiple endpoints.
7.2.9 DequeueTimeout Property
The DequeueTimeOut property supports multiple inbound dequeue threads. The
value for this property determines how many seconds the dequeue() API waits for
messages before it returns and the next polling cycle begins.
Add this property to the composite.xml file, as shown in the following example:
<service name="Inbound" ui:wsdlLocation="Inbound.wsdl">
<interface.wsdl interface="http://xmlns.oracle.com/pcbpel/adapter/aq/AQ_
InboundRetry_Mediator/AQ2JMSInboundRetry/Inbound%2F#wsdl.interface(Dequeue_ptt)"/>
<binding.jca config="Inbound_aq.jca">
<property name="DequeueTimeOut" type="xs:integer" many="false"
override="may">10</property>
</binding.jca>
</service>

7.2.10 Control Dequeue Timeout and Multiple Inbound Polling Threads
Oracle AQ Adapter provides system properties to control dequeue timeout and
multiple inbound polling threads for each Java Virtual Machine (JVM), systemwide,
instead of for each process.
The system property provided by Oracle AQ Adapter to control dequeue timeout is
oracle.adapter.aq.wait, and the property that controls inbound polling threads
is adapter.aq.dequeue.threads.
7.2.11 Stream Payload Support
Oracle AQ Adapter provides support to stream payload. When you enable this
feature, the payload is streamed to a database instead of getting manipulated in SOA
run time as in a memory DOM. You use this feature while handling large payloads. To
enable support to stream payload, you must select the Enable Streaming check box
while defining the dequeue operation parameters in Oracle JDeveloper. When you
select the Enable Streaming check box, a corresponding Boolean property
StreamPayload is appended to the ActivationSpec properties defined in the
respective .jca file, as shown in the following example. If the StreamPayload
property does not exist, then the default value false is assumed. The property is
applicable when processing Raw messages, XMLType messages, and ADT type
messages for which a payload is specified though an ADT attribute.
<activation-spec
className="oracle.tip.adapter.aq.inbound.AQDequeueActivationSpec">
<property name="QueueName" value="RAW_IN_QUEUE"/>
<property name="DatabaseSchema" value="SCOTT"/>
<property name="StreamPayload" value="true"/>
</activation-spec>
7.2.12 Oracle AQ Adapter Inbound Retries
If you configure the Oracle AQ Adapter inbound retries to retry for more than 5 times
by using the jca.retry.count service binding property for a retryable exception,
then ensure that the queue is created with max_retries value that is greater then the
value used for jca.retry.count. If nothing is specified, then the queue is created
with a max_retries value of 5 which would mean that the message will end up in
exception queue after 5 retries and will not be delivered to adapter for further
processing. If jca.retry.count is specified with a value of 5 or less, then you do
not have to change the queue max_retries property.
Use the following code to change the max_retries property when creating a queue:
begin
DBMS_AQADM.CREATE_QUEUE_TABLE ( queue_table => 'RAW_IN_QUEUE_TABLE',
queue_payload_type => 'RAW');
DBMS_AQADM.CREATE_QUEUE ( queue_name => 'RAW_IN_QUEUE',queue_table=> 'RAW_IN_
QUEUE_TABLE', max_retries=>1500);
DBMS_AQADM.START_QUEUE ( queue_name => 'RAW_IN_QUEUE');
DBMS_AQADM.CREATE_QUEUE_TABLE ( queue_table => 'RAW_OUT_QUEUE_TABLE', queue_
payload_type => 'RAW');
DBMS_AQADM.CREATE_QUEUE ( queue_name => 'RAW_OUT_QUEUE', queue_table => 'RAW_OUT_
QUEUE_TABLE');
DBMS_AQADM.START_QUEUE ( queue_name => 'RAW_OUT_QUEUE');
end;

Oracle AQ Adapter Use Cases
7.2.13 Error Handling Support
For information about error handling, see Section 2.10, "Error Handling."
7.3 Oracle AQ Adapter Use Cases
■ Section 7.3.1, "Generic Use Case"
■ Section 7.3.2, "Oracle AQ Adapter ADT Queue"
■ Section 7.3.3, "Oracle AQ Adapter RAW Queue"
7.3.1 Generic Use Case
The following use cases include a general walkthrough of the Adapter Configuration
Wizard, followed by examples of how you can modify the general procedure in
different situations. Each example shows relevant parts of the generated WSDL and
JCA files.
■ Section 7.3.1.1, "Adapter Configuration Wizard Walkthrough"
■ Section 7.3.1.2, "Dequeuing and Enqueuing Object and ADT Payloads"
■ Section 7.3.1.3, "Dequeuing One Column of the Object Payload"
■ Section 7.3.1.4, "Using Correlation ID for Filtering Messages During Dequeue"
■ Section 7.3.1.5, "Enqueuing and Dequeuing from Multisubscriber Queues"
■ Section 7.3.1.6, "Rule-Based Subscription for Multiconsumer Queues"
7.3.1.1 Adapter Configuration Wizard Walkthrough
The following use cases include configuring an Oracle AQ Adapter, followed by
examples of how you modify the generic procedure in different situations. Each
example shows relevant parts of the generated WSDL and JCA files.
In this example, you will create an Oracle AQ Adapter service that dequeues messages
to the service_in_queue queue, with a payload that is one field within the
service_type object, and with a user-defined schema.
This section describes the tasks required to configure Oracle AQ Adapter by using the
Adapter Configuration Wizard in Oracle JDeveloper.
■ Section 7.3.1.1.1, "Meeting Prerequisites"
■ Section 7.3.1.1.2, "Creating an Application and an SOA Project"
■ Section 7.3.1.1.3, "Defining an Oracle AQ Adapter Service"
■ Section 7.3.1.1.4, "Generated WSDL and JCA Files"
7.3.1.1.1 Meeting Prerequisites
This example assumes that you are familiar with basic BPEL constructs, such as
activities and partner links, and Oracle JDeveloper environment for creating and
deploying BPEL Process. Besides this, you must meet the following prerequisites:
■ Access to SCOTT schema in some database.

■ Create queues by using the following stored procedures:
– setup_user.sql
– create_queues.sql
– dequeue_service.sql
– enqueue_service.sql
Copy these SQL files from the following location:
http://www.oracle.com/technology/sample_
code/products/adapters
7.3.1.1.2 Creating an Application and an SOA Project
You must create an Oracle JDeveloper application to contain the SOA composite.
Perform the following steps to create a new application, an SOA project:
1. Open Oracle JDeveloper.
2. In the Application Navigator, click New Application. The Create Generic
Application Name your application page is displayed, as shown in Figure 7–1.
3. Enter a name for the application in the Application Name field.
4. In the Application Template list, choose Generic Application.
Figure 7–1 The Create Generic Application Name your application Page
5. Click Next.
The Create Generic Application Name your project page is displayed, as shown in
Figure 7–2.
6. In the Project Name field, enter a descriptive name.
For example, SOAComposite.
7. In the Available list in the Project Technologies tab, double-click SOA to move it
to the Selected list.

Figure 7–2 The Create Generic Application Name your Generic project Page
8. Click Next.
The Create Generic Application Configure SOA settings page is displayed, as
Figure 7–3 The Create Generic Application Configure SOA settings Page
9. Select Composite With BPEL from the Composite Template list, and then click
Finish.
You have created a new application and an SOA project. This automatically creates
an SOA composite.

The Create BPEL Process page is displayed, as shown in Figure 7–4.
Figure 7–4 The Create BPEL Process Page
10. Enter a name for the BPEL process in the Name field. For example,
CustomerDetails.
11. Select Define Service Later in the Template list, and then click OK.
You have created the CustomerDetails BPEL process.
7.3.1.1.3 Defining an Oracle AQ Adapter Service
The next step is to define an Oracle AQ Adapter service. Perform the following steps
to create an Oracle AQ Adapter service:
1. In the Component Palette, select SOA.
2. Drag and drop AQ Adapter from the Service Adapters list to the Exposed Services
swim lane in the composite.xml page.
The Adapter Configuration Wizard Welcome page is displayed.
3. Click Next.
The Adapter Configuration Wizard Service Name page is displayed, as shown in
Figure 7–5.

Figure 7–5 The Adapter Configuration Wizard Service Name Page
4. Specify a service name, and then click Next.
The Adapter Configuration Wizard Service Connection page is displayed, as
Figure 7–6 Adapter Configuration Wizard Service Connection Page
5. Click the plus icon to create a new database connection.
The Create Database Connection page is displayed.

6. Enter the following information:
a. For Create Connection In, choose Application Resources.
b. In the Connection Name field, specify a unique name for the database
connection.
In this example, type DBConnection1.
c. From the Connection Type box, select Oracle (JDBC).
d. In the UserName field, specify the user name to be authorized for access to the
database.
In this example, type scott.
e. In the Role field, enter a role, if applicable.
This must be a specific database role, such as SYSDBA, as defined in the
database. This field is optional. In this example, leave the Role field blank.
f. In the Password field, specify the password to be associated with the specified
user name.
In this example, type tiger.
g. Select Save Password and Deploy Password.
h. From the Driver list, select Thin.
i. In the Host Name field, enter a value to identify the computer running the
Oracle server.
Use an IP address or a host name that can be resolved by TCP/IP, for example,
myserver. The default value is localhost.
j. In the JDBC Port field, enter a value to identify the TCP/IP port. The default
is 1521.
k. In the SID field, enter a value for the unique system identifier (SID) of an
Oracle database instance.
The default is XE.
l. Click Test Connection to determine whether the specified information
establishes a connection with the database.
A Success message is displayed.
m. Click OK.
The Connection you created is displayed in the Connection field in the Service
Name page.
Notice that the Java Naming and Directory Interface (JNDI) name in the JNDI
Name field is populated after you have created the database connection. The
JNDI name acts as a placeholder for the connection used when your service is
deployed to the BPEL server. This enables you to use different databases for
development and later production.
The value specified in the JNDI name must exist in the Oracle AQ Adapter
weblogic-ra.xml file to ensure that the adapter runs in managed mode. A
Note: You must connect to the database where Oracle Applications is
running.

default connection instance eis/AQ/aqSample is shipped and can be used as
the default value for this field. To use this connection instance, it would still
require that a data source is created with the JNDI name jdbc/aqSample.
7. Click Next.
The Adapter Configuration Wizard Adapter Interface page is displayed, as shown
in Figure 7–7.
8. In the Adapter Interface page, choose Define from operation and schema
(specified later).
Figure 7–7 The Adapter Configuration Wizard Adapter Interface Page
9. Click Next.
The Operation page is displayed.
10. Oracle AQ Adapter supports three operations:
■ Dequeue: Polls for incoming messages from a queue.
■ Enqueue: Puts outgoing messages in a queue.
■ Enqueue/Dequeue: Puts outgoing messages in a queue and expects response
messages in a queue.
In this example, select Dequeue, as shown in Figure 7–8.
The operation is automatically named after the operation that you selected.
However, you can edit the Operation Name field.

11. Click Next.
The Adapter Configuration Wizard Queue Name page is displayed, as shown in
Figure 7–9.
Note: When creating an SOA composite that uses Oracle AQ
Adapter with ADT data type if the SchemaValidation property is
set to TRUE, then any NULL data type in dequeue message will result
in AQ_INVALID_PAYLOAD error further resulting in message
rejection. To avoid message rejection, you must set the
SchemaValidation property to false.

Figure 7–9 The Adapter Configuration Wizard Queue Name Page
12. Select a database schema from the Database Schema list, or click Browse to browse
for the schema. In this example, click Browse.
The Select Queue dialog is displayed, as shown in Figure 7–10.
Figure 7–10 The Select Queue Dialog

13. Select the required queue, and then click OK.
In this example, select SERVICE_IN_QUEUE. The Queue Name page is displayed
again with the Queue Name field populated with SERVICE_IN_QUEUE, as shown
in Figure 7–11.
14. Click Next.
The Adapter Configuration Wizard Queue Parameters page is displayed, as

Figure 7–12 The Adapter Configuration Wizard Queue Parameters Page
15. Enter values for the parameters, and then click Next.
■ Correlation ID: Enter an optional correlation ID from 1 to 30 characters in
length. This is used to identify messages that can be retrieved at a later time by
a dequeue activity using the same correlation ID.
The value to enter is agreed upon between the enqueuing sender and the
dequeuing receiver for asynchronous conversations. The correlation ID maps
to an AQ header property. Correlation IDs in the inbound direction enable you
to be selective about the message to dequeue. This field is optional. If you do
not enter a value, then all the messages in the queue are processed.
If you enter a value for the Correlation ID in the outbound direction, then all
outbound messages have the correct ID set to the value entered. You can
override this value on a per message basis in the correlation field of the
outbound header.
■ Dequeue Condition: Displayed only when you select dequeue in the
Operation page.
Enter a Boolean expression similar to the WHERE clause of a SQL query. This
expression can include conditions on message properties, user data properties
(object payloads only), and PL/SQL or SQL functions. If more than one
message satisfies the dequeue condition, then the order of dequeuing is
indeterminate, and the sort order of the queue is not honored.
This field is displayed for inbound single consumer and multiconsumer
queues.
16. Click Next.
The Adapter Configuration Wizard Object Payload page is displayed, as shown in
Figure 7–13.

Figure 7–13 The Adapter Configuration Wizard Object Payload Page
a. In Business Payload, select Field within the Object.
b. Click Browse in the Payload Fields Options section to select a field that will
contain the business payload.
The Select Payload Field dialog is displayed, as shown in Figure 7–14.
Figure 7–14 The Select Payload Field Dialog
17. Select a field, and then click OK.

In this example, select PAYLOAD (CLOB).
The Object Payload field is displayed with all the payload details filled up, as
Figure 7–15 The Adapter Configuration Wizard Object payload Page
18. Select Access to non-payload fields also needed, and then click Next.
The Messages page is displayed.
The Message page has the following options:
■ Native format translation is not required (Schema is Opaque): Select this
option if you do not want to specify a schema. Selecting this option disables all
the other fields under Message Schema.
■ Define Schema for Native Format: Click this to start the Native Format
Builder Wizard, which guides you through the process of defining the native
format.
■ URL: You can enter the path for the schema file URL or click Browse to
browse for the path.
■ Schema Element: The name of the schema element.
19. In this example, click the Browse for schema file icon to browse for the schema
file URL.
The Type Chooser dialog is displayed, as shown in Figure 7–16.

20. Select SERVICE from the list, as shown in Figure 7–16, and then click OK.
The Messages page reappears, with the Schema Location and Schema Element
fields populated, as shown in Figure 7–17.
Figure 7–17 The Adapter Configuration Wizard Messages Page
21. Click Next.
The Finish screen is displayed. This page shows the path and name of the adapter
file that the wizard creates.

22. Click Finish.
You have created an AQ Adapter service with dequeue operation.
23. Click OK.
7.3.1.1.4 Generated WSDL and JCA Files
The adapter service generates a WSDL and a JCA file to serve as the defined adapter
interface.
The following is the WSDL file generated for the dequeue operation:
<definitions name="Inbound"
targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/"
xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
xmlns:obj1="http://xmlns.oracle.com/xdb/SCOTT"
xmlns:imp1="http://www.oracle.com/service/contract">
<types>
xmlns:hdr="http://xmlns.oracle.com/pcbpel/adapter/aq/inbound/"
xmlns:obj1="http://xmlns.oracle.com/xdb/SCOTT">
<import namespace="http://xmlns.oracle.com/xdb/SCOTT"
schemaLocation="xsd/SCOTT_SERVICE_TYPE.xsd"/>
<import namespace="http://xmlns.oracle.com/pcbpel/adapter/aq/inbound/"
schemaLocation="xsd/aqAdapterInboundHeader.xsd"/>
<complexType name="HeaderCType">
<sequence>
<element name="QueueHeader" type="hdr:HeaderType"/>
<element name="PayloadHeader" type="obj1:SERVICE_TYPE"/>
</sequence>
</complexType>
<element name="Header" type="tns:HeaderCType"/>
</schema>
<schema xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://www.oracle.com/service/contract"
schemaLocation="xsd/service.xsd"/>
</schema>
</types>
<message name="SERVICE_msg">
<part name="SERVICE" element="imp1:SERVICE"/>
</message>
<message name="Header_msg">
<part name="Header" element="tns:Header"/>
</message>
<portType name="Dequeue_ptt">
<operation name="Dequeue">
<input message="tns:SERVICE_msg"/>
</operation>
</portType>
<plt:partnerLinkType name="Dequeue_plt">
<plt:role name="Dequeue_role">
<plt:portType name="tns:Dequeue_ptt"/>
</plt:role>
</plt:partnerLinkType>
</definitions>

7.3.1.2 Dequeuing and Enqueuing Object and ADT Payloads
Dequeuing and enqueing is covered in Section 7.3.2, "Oracle AQ Adapter ADT
Queue".
To enqueue or dequeue the entire object as the payload, perform the following:
■ Select Enqueue or Dequeue in Step 10.
■ Select Whole Object CUSTOMER_TYPE, and skip to Step 16.
For a working example of ADT payload use case, go to
7.3.1.3 Dequeuing One Column of the Object Payload
The walkthrough is an example of dequeuing one field or column within an object
payload.
To create an Oracle AQ Adapter that dequeues one field in an object, you must
perform the following steps in the Adapter Configuration Wizard Object Payload
page:
1. Select Field within the Object.
2. Click Browse at the end of the Field Name field.
The Select Payload Field dialog is displayed.
3. Select a field that will contain the business payload, and then click OK.
The Adapter Configuration Wizard Object Payload page with Field Name field
populated with the field that you selected is displayed, as shown in Figure 7–18.
Note: If you create an ADT type queue and drop both the queue and
the data types created for that queue and redeploy the process, then it
throws a SQL exception and you must restart the Database. To avoid
this, you must drop only the queues and not the data types.

Figure 7–18 The Adapter Configuration Wizard Object Payload Page
4. Select Access to non-payload fields also needed, and then click Next.
The following segment of the generated JCA file specifies that one field, in this case the
PAYLOAD or information on Oracle AQ Adapter architecture, adapter integration with
Oracle BPEL Process Manager, and adapter deployments is dequeued.
<adapter-config name="Inbound" adapter="AQ Adapter"
<connection-factory location="eis/AQ/aqSample" UIConnectionName="Connection1"
adapterRef=""/>
<endpoint-activation portType="Dequeue_ptt" operation="Dequeue">
<activation-spec
<property name="QueueName" value="SERVICE_IN_QUEUE"/>
<property name="ObjectFieldName" value="PAYLOAD"/>
<property name="PayloadHeaderRequired" value="true
"/>
<property name="SchemaValidation" value="false"/>
</activation-spec>
</adapter-config>
For a working example of the ADT_with_CLOB_Payload use case where one field or
column within an object payload is dequeued, go to
7.3.1.4 Using Correlation ID for Filtering Messages During Dequeue
Perform the following steps to set up an adapter that dequeues messages with a
certain correlation ID only.
■ Select Dequeue operation in Step 10.
■ Enter the correlation ID in Step 15.

The adapter dequeues messages enqueued with that same correlation ID only.
For a working example of this use case where an Oracle AQ Adapter dequeues
messages enqueued with that same correlation ID, go to
7.3.1.5 Enqueuing and Dequeuing from Multisubscriber Queues
Multisubscriber queues are accessible by multiple users, and sometimes, those users
are concerned only with certain types of messages within the queue. For example, you
may have a multiuser queue for loan applications where loans below $100,000 can be
approved by regular loan-approval staff, whereas loans over $100,000 must be
approved by a supervisor. In this case, the BPEL process can use one adapter to
enqueue loan applications for big loans for supervisors, and another adapter to
enqueue loan applications for smaller loans for regular staff in the same
multisubscriber queue.
Specify an adapter that enqueues to a multisubscriber queue, and include queue
parameters in the Recipients field and the Correlation ID field.
In Step 15, specify Bob in the Recipients field.
The following code is from a JCA file generated by defining an Oracle AQ Adapter
that enqueues with a recipient list of Bob:
<adapter-config name="Inbound" adapter="AQ Adapter"
<connection-factory location="eis/AQ/aqSample" UIConnectionName="aqSample"
adapterRef=""/>
<endpoint-interaction portType="Enqueue_ptt" operation="Enqueue">
<interaction-spec
className="oracle.tip.adapter.aq.outbound.AQEnqueueInteractionSpec">
<property name="QueueName" value="PURCHASEORDER_APPROVAL"/>
<property name="RecipientList" value="Bob"/>
</interaction-spec>
</adapter-config>
When dequeuing from a multisubscriber queue, the Queue Parameters window is
displayed.
The Consumer field is where you specify the consumer name, or the name of the
queue subscriber. This must match the Recipient entry on the enqueue process for the
message to be dequeued. When subscribing to a multiconsumer queue, this field is
required.
The following code is from a JCA file generated by defining an Oracle AQ Adapter
with a consumer name:
<adapter-config name="Dequer_Bob" adapter="AQ Adapter"
<connection-factory location="eis/AQ/manas" UIConnectionName="aqSample"
adapterRef=""/>
<endpoint-activation portType="Dequeue_ptt" operation="Dequeue">
<activation-spec
<property name="QueueName" value="PURCHASEORDER_APPROVAL"/>
<property name="Consumer" value="Bob"/>
<property name="SchemaValidation" value="false"/>
</activation-spec>

</adapter-config>
For a working example of this use case which demonstrates enqueuing and dequeuing
from multisubscriber queues, go to
7.3.1.6 Rule-Based Subscription for Multiconsumer Queues
When a dequeue is performed from a multisubscriber queue, it is sometimes necessary
to screen the messages and accept only those that meet certain conditions. These
conditions may concern header information, such as in selecting messages of only
priority 1, or some aspect of the message payload, such as in selecting only loan
applications above $100,000.
The Message Selector Rule field is displayed in Step 15 if you select a multisubscriber
queue. Enter a subscription rule in the form of a Boolean expression using syntax
similar to a SQL WHERE clause, such as priority = 1, or TAB.USER_DATA.amount
> 1000. The adapter dequeues only those messages for which this Boolean expression
is true.
You must select the Access to non-payload fields also needed check box to access
header information.
When this check box is selected, the generated WSDL file has additional code in the
type section:
<?binding.jca Inbound_aq.jca?>
xmlns:obj1="http://xmlns.oracle.com/xdb/SCOTT"
xmlns:imp1="http://www.oracle.com/ipdemo">
<types>
xmlns:hdr="http://xmlns.oracle.com/pcbpel/adapter/aq/inbound/"
xmlns:obj1="http://xmlns.oracle.com/xdb/SCOTT">
<import namespace="http://xmlns.oracle.com/xdb/SCOTT"
schemaLocation="xsd/SCOTT_MAGAZINE_TYPE.xsd"/>
<import namespace="http://xmlns.oracle.com/pcbpel/adapter/aq/inbound/"
schemaLocation="xsd/aqAdapterInboundHeader.xsd"/>
<complexType name="HeaderCType">
<sequence>
<element name="QueueHeader" type="hdr:HeaderType"/>
<element name="PayloadHeader" type="obj1:MAGAZINE_TYPE"/>
</sequence>
</complexType>
<element name="Header" type="tns:HeaderCType"/>
</schema>
<import namespace="http://www.oracle.com/ipdemo"
schemaLocation="xsd/simpleMagazine.xsd"/>
</schema>
</types>

<message name="simpleMagazine_msg">
<part name="simpleMagazine" element="imp1:simpleMagazine"/>
</message>
<message name="Header_msg">
<part name="Header" element="tns:Header"/>
</message>
<portType name="Dequeue_ptt">
<operation name="Dequeue">
<input message="tns:simpleMagazine_msg"/>
</operation>
</portType>
<plt:partnerLinkType name="Dequeue_plt">
<plt:role name="Dequeue_role">
<plt:portType name="tns:Dequeue_ptt"/>
</plt:role>
</plt:partnerLinkType>
</definitions>
Note that PayloadHeader is the type for the whole ADT of the queue. The payload
contains only the chosen payload field. If you selected Access to non-payload fields
also needed, then the PayloadHeader (. jca.aq.HeaderDocument) contains the
whole ADT (including the payload field, which is also present in the header, but
ignored by the adapter.)
For working examples of rule-based subscription using header and payload
information, go to
7.3.2 Oracle AQ Adapter ADT Queue
In this sample, the business process receives a message from the AQ Adapter, copies
the payload to an outbound message, and invokes the AQ Adapter with the outbound
message.
The queues involved are ADT queues. In this scenario, where the user has chosen the
use whole ADT as the payload, the AQ Adapter Wizard has generated the schema in
SCOTT_CUSTOMER_TYPE.xsd, according to the queue structure. During run time, an
XML file that matches the schema will be created by the adapter for each message.
■ Section 7.3.2.1, "Meeting Prerequisites"
■ Section 7.3.2.2, "Creating an Application and an SOA Project"
■ Section 7.3.2.3, "Creating an Inbound Oracle AQ Adapter"
■ Section 7.3.2.4, "Creating an Outbound Oracle AQ Adapter"
■ Section 7.3.2.6, "Configuring Routing Service"
■ Section 7.3.2.7, "Configuring the Data Sources in the Oracle WebLogic Server
Administration Console"
7.3.2.1 Meeting Prerequisites
You must meet the following prerequisites before you create the sample service:
1. Access SCOTT schema in some database.

2. Execute the following SQL scripts:
■ setup_user.sql
■ create_queues.sql
■ dequeue_customer.sql
■ enqueue_customer.sql
Copy these files from the adapters-aq-102-adt folder available at:
7.3.2.2 Creating an Application and an SOA Project
You must create an Oracle JDeveloper application to contain the SOA composite. Use
the following steps to create a new application and an SOA project:
1. In the Application Navigator of Oracle JDeveloper, click New Application.
The Create Generic Application Name your application page is displayed.
2. Enter ADT in the Application Name field, and click Next.
The Create Generic Application Name your project page is displayed.
3. Enter ADT in the Project Name field.
4. In the Available list in the Project Technologies tab, double-click SOA to move it to
the Selected list.
5. Click Next.
The Create Generic Application Configure SOA settings page is displayed.
6. Select Composite With Mediator from the Composite Template list, and then click
Finish.
You have created a new application and an SOA project.
The Create Mediator page is displayed, as shown in Figure 7–19.
Figure 7–19 The Create Mediator Page

7. Enter a name for the Mediator component in the Name field. In this example,
retain the default name Mediator1.
8. Select Define Interface Later in the Template list, and then click OK.
You have created a mediator component.
7.3.2.3 Creating an Inbound Oracle AQ Adapter
The following are the steps to create an inbound Oracle AQ Adapter service:
2. Drag and drop AQ Adapter from the Service Adapters list in the Component
Palette to the Exposed Services swim lane in the composite.xml page.
The Adapter Configuration Wizard is displayed.
3. Click Next.
The Service Name page is displayed.
4. Specify a name for the service in the Service Name page. In this example, type
dequeue.
5. Click Next.
The Service Connection page is displayed. A database connection is required to
configure an Oracle AQ Adapter. You can either create a new connection or select
an existing database connection.
6. Click the Create a new database connection icon to create a new database
connection.
The Create Database Connection page is displayed.
7. Create a database connection, as mentioned in Step 6 of Section 7.3.1.1.3, "Defining
an Oracle AQ Adapter Service."
8. Click OK to complete the process of creating a new database connection.
The Service Connection page is displayed, providing a summary of the database
connection.
9. Click Next.
The Adapter Interface page is displayed.
10. In the Adapter Interface page, select Define from operation and schema
(specified later).
11. Click Next.
12. Select Dequeue.
13. Accept the default operation name, and then click Next.
The Queue Name page is displayed.
14. Select a database schema from the list, or click Browse to browse for the schema.
In this example, click Browse.
The Select Queue dialog is displayed.
15. In the Select Queue dialog, perform the following steps:
a. For Queue Type, select all types.

b. For Database Schema, select Scott.
c. Retain the default values for the other fields.
d. Under Queues, select CUSTOMER_IN_QUEUE.
Figure 7–20 shows the Select Queue dialog.
Figure 7–20 Selecting a Queue for the Inbound Operation
16. Click OK.
The Queue Name dialog with all the fields populated is displayed, as shown in
Figure 7–21.

Figure 7–21 The Queue Name Page
17. Click Next.
The Queue Parameters page is displayed.
18. In the Queue Parameters page, leave the fields empty, and then click Next.
The Object Payload page is displayed.
19. Select a business payload: either the entire object, or just one field within the
object.
In this example, select Whole Object CUSTOMER_TYPE.
20. Click Next.
21. Click Finish.
You have defined an inbound Oracle AQ Adapter
7.3.2.4 Creating an Outbound Oracle AQ Adapter
The following are the steps to create an outbound Oracle AQ Adapter service:
3. Click Next.
4. In the Service Name field, enter enqueue and click Next.
The Service Connection page is displayed.

5. For Connection, select MyConnection, and then click Next.
(specified later), and then click Next.
7. In the Operation page, select Enqueue, and accept the default operation name.
8. Click Next.
9. In the Queue Name page, select a database schema from the list, or click Browse to
browse for the schema. In this example, click Browse.
The Select Queue dialog is displayed.
10. In the Select Queue dialog, perform the following steps:
a. For Queue Type, select all types.
b. For Database Schema, select Scott.
c. Retain the default values for the other fields.
d. Under Queues, select CUSTOMER_OUT_QUEUE, as shown in Figure 7–22.
Figure 7–22 Selecting a Queue for the Outbound Operation
11. Click OK.
The Queue Name page with all the fields populated is displayed, as shown in
Figure 7–23.

Figure 7–23 The Queue Name Page
12. Click Next.
13. In the Queue Parameters page, leave the fields empty, and then click Next.
The Object Payload page is displayed.
14. Select a business payload, either the entire object, or just one field within the
object. In this example, select Whole Object CUSTOMER_TYPE.
15. Click Next.
16. In the Finish window, click Finish.
You have defined an outbound Oracle AQ Adapter.
You must assemble or wire the three components that you have created: Inbound
adapter service, Mediator component, and Outbound adapter reference. Perform the
following steps to wire the components together:
1. Drag the small triangle in the Inbound adapter in the Exposed Services area to the
drop zone that appears as a green triangle in the Mediator component in the
Components area.
2. Drag the small triangle in the Mediator component in the Components area to the
drop zone that appears as a green triangle in the Outbound adapter in the External
References area.
The Oracle JDeveloper composite.xml is displayed, as shown in Figure 7–24.

Figure 7–24 The Oracle JDeveloper composite.xml
7.3.2.6 Configuring Routing Service
The following are the steps to configure the routing service:
1. Double-click Mediator1.
The Mediator1.mplan window is displayed.
2. Click the Select an existing mapper file or create a new one... icon that is
displayed at the end of the Transform Using field.
The Request Transformation Map dialog is displayed, as shown in Figure 7–25.
Figure 7–25 The Request Transformation Map Dialog
3. Select Create New Mapper File, and then click OK.
The Transformation window is displayed, as shown in Figure 7–26.

Figure 7–26 The Transformation Window
4. Select the source root elements on the left-hand side of the mapper and drag them
over to the destination root elements on the right-hand side to set the map
preferences.
The Auto Map Preferences dialog is displayed, as shown in Figure 7–27.
Figure 7–27 The Auto Map Preferences Dialog
5. Click OK.
The middle pane of the application window will resemble, as shown in
Figure 7–28.

Figure 7–28 The Application Window After Setting the Map Preferences
6. Save and close the tab for the mapper.
7. Save and close the tab for the routing service.
7.3.2.7 Configuring the Data Sources in the Oracle WebLogic Server
Administration Console

Figure 7–29 Oracle WebLogic Server Administration Console Home Page
3. Under Domain Structure, select Services, JBDC, and then click DataSources.
The Summary of JDBC Data Sources page is displayed, as shown Figure 7–30.
Figure 7–30 The Summary of JDBC Data Sources Page
5. Enter the values for the properties to be used to identify your new JDBC data
source, as shown in Figure 7–31.

Figure 7–31 The Create a New JDBC Data Source Page
Figure 7–32 The Create a New JDBC Data Source Transaction Options Page

Figure 7–33 The Create a New JDBC Data Source Connection Properties Page
8. Enter the connection properties in the Connection Properties page.
9. Click Next. The Create a New JDBC Data Source Test Database Connection page is
Figure 7–34 The Create a New JDBC Data Source Test Database Connection Page
Connection page.

11. Click Next. The Create a New JDBC Data Source Select Targets page is displayed,
Figure 7–35 The Create a New JDBC Data Source Select Targets Page
12. Select a target, and then click Finish.
The Summary of JDBC Data Sources page is displayed, as shown in Figure 7–36.
This page summarizes the JDBC data source objects that have been created in this
domain. The data source that you created appears in this list.

Figure 7–36 The Summary of JDBC Data Sources Page
13. Close the Oracle WebLogic Server Administration Console.
created in the preceding steps.
The following are the steps to deploy the application profile by using Oracle
JDeveloper:
1. Create an application server connection by using the procedure described in
Chapter 2.16, "Creating an Application Server Connection for Oracle JCA
Adapters."
2. Deploy the application by using the procedure described in Section 2.17,
"Deploying Oracle JCA Adapter Applications from Oracle JDeveloper."

7.3.2.9 Monitoring Using the Oracle Enterprise Manager Console
You can monitor the deployed composite by using the EM Console. Perform the
following steps:
deployed is displayed in the Applications Navigation tree.
2. In the Last 5 Instances pane, there is an entry of a new instance. This new instance
is the instance that was triggered when you enqueued a message.
3. Click one of the instances. The Flow Trace page is displayed.
4. Click the Mediator1 component instance. The Audit page is displayed.
5. Click the Flow-Debug tab to debug the instance.
7.3.3 Oracle AQ Adapter RAW Queue
This use case demonstrates how to use Oracle AQ Adapter to dequeue from and
enqueue to an AQ RAW queue.
■ Section 7.3.3.3, "Creating an Inbound Adapter Service"
■ Section 7.3.3.4, "Creating an Outbound Adapter Service"
■ Section 7.3.3.6, "Configuring the Data Sources in the Oracle WebLogic Server
Administration Console"
■ Section 7.3.3.8, "Monitoring Using the Oracle Enterprise Manager Console"
To perform the AQ RAW queue use case:
■ You must have access to SCOTT schema in a database. Run the script setup_
user.sql with the SYS user as SYSDBA. The script is available here:
■ Execute the following SQL scripts:
– setup_user.sql
– create_queues.sql
– dequeue_raw.sql
– enqueue_raw.sql
You must create an Oracle JDeveloper application to contain the SOA composite. To
create a new application and an SOA project, perform the following steps:

2. In the Application Navigator, click New Application.
The Create Generic Application Name your Application page is displayed.
3. Enter Rawqueue in the Application Name field.
4. In the Application Template list, select Generic Application.
5. Click Next.
The Create Generic Application Name your project page is displayed.
6. In the Project Name field, enter a descriptive name, for example, Raw.
8. Click Next.
The Create Generic Application Configure SOA settings page is displayed.
Finish.
an SOA composite.
The Create BPEL Process page is displayed.
10. Enter a name for the BPEL process in the Name field. For example,
BPELRawqueue.
The Rawqueue application and the Raw project appear in the design area.
12. Copy the emp.xsd file from the link,
to the XSD folder in your project.
7.3.3.3 Creating an Inbound Adapter Service
Perform the following steps to create an inbound Oracle AQ Adapter service that will
dequeue the message to a queue:
3. Click Next.
4. In the Service Name field, enter Raw-Dequeuer, and then click Next.
5. Create a database connection, as mentioned in Step 6 of Section 7.3.1.1.3, "Defining
an Oracle AQ Adapter Service."
6. Click Next.

(specified later), and then click Next.
8. In the Operation page, select Dequeue, as shown in Figure 7–37.
9. Accept the default operation name, and click Next.
10. In the Queue Name page, select SCOTT as Database Schema and RAW_IN_
QUEUE as Queue Name, as shown in Figure 7–38.

11. Click Next.
12. Enter the Correlation ID and a Dequeue condition, and then click Next.
13. Click Browse at the end of the URL field.
14. Select Project Schema Files, emp.xsd, and then AQRaw_End2End, as shown in
Figure 7–39.

15. Click OK.
The emp.xsd schema file is displayed in the URL field in the Message dialog, as
Figure 7–40 The Adapter Configuration Wizard Messages Page
17. Click Finish. You have configured the Oracle AQ Adapter service, and the
composite.xml page is displayed, as shown in Figure 7–41.

Figure 7–41 The Oracle JDeveloper Window Composite.xml Page
7.3.3.4 Creating an Outbound Adapter Service
Perform the following steps to create an adapter service that will enqueue the request
messages and dequeue the corresponding response messages (report) from a queue:
3. Enter Raw-Enqueuer in the Service Name field, and click OK.
4. Select XA Datasource, and then click Next.
5. Select Enqueue.
6. Accept the default operation name, and click Next.
7. Select SCOTT as Database Schema and RAW_OUT_QUEUE as Queue Name, as

8. Click Next.
9. Enter the Correlation ID, and then click Next.
10. Click Browse for schema file at the end of the URL field.
11. Select Project Schema Files, emp.xsd, and AQRaw_End2End, as shown in
Figure 7–39.
12. Click Next.
The emp.xsd schema file is displayed in the URL field in the Message dialog, as
13. Click Next.
The Finish page is displayed.
14. Click Finish.
You have configured the Oracle AQ Adapter service, and the composite.xml page

Figure 7–43 The Oracle JDeveloper Window Composite.xml Page
You must assemble or wire the three components that you have created: Inbound
adapter service, BPEL process, and Outbound adapter reference. Perform the
following steps to wire the components together:
1. Drag the small triangle in the Raw-Dequeuer in the Exposed Services area to the
area.
zone that appears as a green triangle in Raw-Enqueuer in the External References
area.
Similarly, drag the small triangle in the BPEL process in the Components area to
the drop zone in OutboundService in the External References.
The Oracle JDeveloper composite.xml file is displayed, as shown in
Figure 7–44.

Figure 7–44 The Oracle JDeveloper- Composite.xml
4. Double-click BPELRawqueue.
The BPELRawqueue.bpel page is displayed.
5. Drag and drop the Receive, Assign, and Invoke activities in the order mentioned,
from the Component Palette to the Components area.
The Oracle JDeveloper BPELRawqueue.bpel page is displayed, as shown in
Figure 7–45.

Figure 7–45 The BPELRawqueue.bpel Page
6. Double-click the Receive activity.
The Receive dialog is displayed.
7. Click the Browse Partner Links icon at the end of the Partner Link field.
The Partner Link Chooser dialog is displayed.
8. Select Raw-Dequeuer, and then click OK.
The Receive dialog is displayed with the Partner Link field populated with the
value Raw-Dequeuer.
9. Click the Auto-Create Variable icon that is displayed at the end of the Variable
field.
The Create Variable dialog is displayed.
10. Accept the default values, and click OK.
11. Check the Create Instance box, as shown in Figure 7–46, and click OK.

12. Double-click the Invoke activity.
The Invoke dialog is displayed.
14. Select Raw-Enqueuer, and then click OK.
The Invoke dialog is displayed with the Partner Link field populated with the
value Raw-Enqueuer.
15. Click the Automatically Create Input Variable icon that is displayed at the end of
the Input Variable field.
16. Accept the default values, and click OK.
The Invoke dialog is displayed, as shown in Figure 7–47.
17. Click OK.
18. Double-click the Assign activity.
The Assign dialog is displayed.

19. Click the plus icon, and select Copy Operation.
The Create Copy Operation dialog is displayed.
20. Select the variables, as shown in Figure 7–48, and click OK.
21. Click OK in the Assign dialog.
The Oracle JDeveloper BPELRawqueue.bpel page is displayed, as shown in
Figure 7–49.

Figure 7–49 The BPELRawqueue.bpel Page
7.3.3.6 Configuring the Data Sources in the Oracle WebLogic Server
Administration Console
3. In the Home page, under Domain Structure, select Services, JBDC, and then click
DataSources.
The Summary of JDBC Data Sources page is displayed.
5. Enter the values for the properties to be used to identify your new JDBC data
source.
displayed.
displayed.
8. Enter the connection properties in the Connection Properties page.
9. Click Next. The Create a New JDBC Data Source Test Database Connection page is
displayed.
Connection page.
11. Click Next. The Create a New JDBC Data Source Select Targets page is displayed.

12. Select a target, and then click Finish.
The Summary of JDBC Data Sources page is displayed. This page summarizes the
JDBC data source objects that have been created in this domain. The Data Source
that you created is displayed in this list.
13. Close the Oracle WebLogic Server Administration Console.
created in the preceding steps.
The following are the steps to deploy the application profile using Oracle JDeveloper:
Adapters."
You can monitor the deployed EM Composite by using the EM Console. Perform the
following steps:
The composite you deployed is displayed in the Applications Navigation tree.
2. In the Last 5 Instances pane, there is an entry of a new instance.
This is the instance that triggered when you enqueued a message.
3. Click one of the instances.
The Flow Trace page is displayed.
4. Click the BPELRawqueue component instance.
The Audit page is displayed.

8
Oracle JCA Adapter for JMS 8-1
8Oracle JCA Adapter for JMS
This chapter describes how to use the Oracle JCA Adapter for JMS (Oracle JMS
Adapter), which enables an Oracle BPEL process or an Oracle Mediator component to
interact with JMS.
■ Section 8.1, "Introduction to the Oracle JMS Adapter"
■ Section 8.2, "Oracle JMS Adapter Features"
■ Section 8.3, "Oracle JMS Adapter Concepts"
■ Section 8.4, "Oracle JMS Adapter Use Cases"
8.1 Introduction to the Oracle JMS Adapter
The JMS architecture uses one client interface to many messaging servers. The JMS
model has two messaging domains, point-to-point and publish-subscribe. In the
point-to-point domain, messages are exchanged through a queue and each message is
delivered to only one receiver. In the publish-subscribe model, messages are sent to a
topic and can be read by many subscribed clients.
For JMS adapter sample files, go to
■ Section 8.1.1, "Oracle JMS Adapter Integration with Oracle BPEL Process Manager"
■ Section 8.1.2, "Oracle JMS Adapter Integration with Oracle Mediator"
8.1.1 Oracle JMS Adapter Integration with Oracle BPEL Process Manager
The JCA Binding Component is used for the bidirectional integration of the JCA 1.5
resource adapters with BPEL Process Manager. The JCA Binding Component is based
on standards and employs the Web service Invocation Framework (WSIF) technology
for exposing the underlying JCA interactions as Web services.
For information on Oracle JMS Adapter architecture, adapter integration with Oracle
BPEL Process Manager, and adapter deployments, see Chapter 3, "Adapter Integration
with Oracle Application Server Components."
8.1.2 Oracle JMS Adapter Integration with Oracle Mediator
Mediator supports Oracle JCA Adapters and enables you to define inbound and
outbound adapter services for each. An inbound adapter service receives data from an

Oracle JMS Adapter Features
external messaging system and transforms it into an XML message. An outbound
adapter service sends data to a target application by transforming an XML message
into the native format of the given adapter.
In the case of Oracle JMS Adapter service, by using Mediator, you can send or receive
messages from a JMS queue or topic.
Oracle BPEL Process Manager pre-dates Mediator, and most of this guide and the
samples implicitly assume use with Oracle BPEL Process Manager. However, the
adapters work equally well with either Oracle BPEL Process Manager or Mediator. For
any mention of Oracle BPEL Process Manager in this chapter, you may substitute
Mediator, instead.
8.2 Oracle JMS Adapter Features
The Oracle JMS Adapter includes the following features:
■ Is based on JMS version 1.0.2b
■ Is a generic Oracle JMS Adapter
Works with any JMS provider. It has been certified against AQ JMS (JMS providers
OJMS 8.1.7, 9.0.1.4, and 9.2), TIBCO JMS, IBM Websphere MQSeries (IBM
MQSeries JMS 6.0), Weblogic JMS, Apache, and Active MQ.
■ Supports JMS topics and queues
■ Supports byte, text, and map message types.
Supports these data types only for this release. The Adapter Configuration Wizard
provides the Native Format Builder Wizard for consuming native data payloads at
run time. The Native Format Builder Wizard creates XSD definitions for the
underlying native data.
■ Supports JMS headers and properties
■ Supports the JMS message selector
Supports the JMS message selector for performing filtering while subscribing to
JMS topics and queues. This parameter is based on the SQL 92 language for
filtering messages based on fields present in the JMS header and properties
section.
■ Is DOM2 compliant
The Oracle JMS Adapter can process and generate document objects that are
compliant with DOM2 specification.
■ Supports normalized message.
Header manipulation and propagation is a key business integration messaging
requirement. Oracle BPEL Process Manager, Mediator, Oracle JCA, and Oracle
B2B rely extensively on header support to solve customers’ integration needs. For
example, a user can preserve a file name from the source directory to the target
directory by propagating it through message headers. Another example: the
outbound Oracle JMS Adapter facilitates asynchronous request/response by
propagating the correlationId and the JMSReplyTo address as JMS headers.
In Oracle BPEL Process Manager and Mediator, users can access, manipulate, and
set headers with varying degrees of UI support.
Propagating Headers in a Normalized Message:
Normalized Message is simplified to have only two parts, properties and payload.

Typically, properties are name-value pairs of scalar types. To fit the existing
complex headers into properties, they will be flattened into scalar types.
Manipulating Headers in Design-Time:
The user experience while manipulating headers in design time is simplified,
because the complex properties are predetermined. In Mediator or Oracle BPEL
designer, you can manipulate the headers with some reserved key words. For
example, in Mediator designer, you can access an inbound Oracle File Adapter,
fileName header by using the following expression:
$nmproperty.InboundFileHeaderType.fileName
However, this method does not address the properties that are dynamically
generated based on your input. For example, in the Oracle AQ Adapter Wizard,
you are allowed to propagate some of the fields from an AQ object as headers.
Based on this user choice, the header definitions are generated. These definitions
are not predetermined and hence cannot be accounted for in the list of
predetermined property definitions. The user cannot design header manipulation
of the dynamic properties before they are defined. To address this limitation, you
must generate all the necessary services (composite entry points) and references.
This restriction applies only to those services that are expected to generate
dynamic properties. Once dynamic properties are generated, they must be
captured in some given location for each composite. Only then can the user
manipulate the dynamic properties in the Oracle Mediator or Oracle BPEL
designer.
■ Supports specifying a durable JMS subscriber
■ Supports persistent and nonpersistent modes of a JMS publisher
■ Does not support connection retry functionality for MQ provider
■ Does not support outbound retry functionality for AQJMS on Solaris
■ The JMS API specifies three types of acknowledgments that can be sent by the JMS
publisher:
– DUPS_OK_ACKNOWLEDGE, for consumers that are not concerned about
duplicate messages
– AUTO_ACKNOWLEDGE, in which the session automatically acknowledges the
receipt of a message
– CLIENT_ACKNOWLEDGE, in which the client acknowledges the message by
calling the message's acknowledge method
■ Supports tracking message size
Note: When you use the Oracle JMS Adapter to connect to an
AQ-JMS provider, and if the database that hosts the AQ destination is
10.1.0.4, then the adapter retry mechanism on the outbound direction
will fail to reconnect to the database server if the database server goes
down. This is because of a client JDBC issue with ojdbc14.jar. To
resolve this you must download the 10.1.0.4 JDBC drivers and use
them in the mid tier by replacing the libraries, specifically ojdbc14.jar
in $MIDTIER_ORACLE_HOME/jdbc. For a detailed explanation about
how to resolve this issue, refer to Metalink Note 317385.1.

The Oracle JMS Adapter is message size aware. The Oracle JMS Adapter calculates
the message size and reports the size back to the JCA Binding Component. The
API, related to size, exposed by the JCA Binding Component can be used for
reporting purposes.
■ Supports MapMessage Data Type
A MapMessage is used to send a set of name-value pairs where names are strings
and values are Java primitive types. The entries can be accessed sequentially or
randomly by name. The order of the entries is undefined. It inherits from a
message and adds a map message body.
Oracle JMS adapter provides support for processing MapMessage. It now
supports one new ActivationSpec and InteractionSpec property each namely
JmsMapMessageConsumeActivationSpec and
JmsMapMessageProduceInteractionSpec.
The PayloadEntry property specifies that the MapMessage entry will be used as
the payload. Users have the option to send payload as an attachment if the
AttachmentList property is defined.
All other MapMessage entries are converted to adapter properties identified by
jca.jms.Map.xxxx, where xxxx is name of the MapMessage entry.
If both PayloadEntry and AttachmentList properties are not defined, then
the entire MapMessage is converted to XML and the XML file is transferred as the
payload.
■ Supports Enterprise Information System (EIS) Credentials
The Oracle JMS Adapter supports securing of the Enterprise Information System
(EIS) credentials such as the user name and password, whenever it establishes an
outbound connection with EIS. You can secure the user name and password for
Oracle JMS Adapter by using Oracle WebLogic Server container-managed sign-on.
For more information about support for securing of the Enterprise Information
System (EIS) credentials, see Section 4.2.21, "Securing Enterprise Information
System Credentials."
■ Supports Streaming Large Payload
Oracle JMS Adapter provides support to stream payload. When you enable this
feature, the payload is streamed to a database instead of getting manipulated in
the SOA run time as in a memory DOM. This feature can be used while handling
large payloads. To enable support to stream payload, ensure that you select the
Enable Streaming check box while defining the consume operation parameters on
the Consume Operation Parameters page in Oracle JDeveloper. When the Enable
Streaming check box is selected, a corresponding Boolean property
EnableStreaming is appended to the ActivationSpec properties defined in
the respective .jca file, as shown in the following example. If the
EnableStreaming property does not exist, then the default value of false is
assumed.
<activation-spec
className="oracle.tip.adapter.jms.inbound.JmsConsumeActivationSpec">
<property name="DestinationName" value="jms/DemoInQueue"/>
<property name="UseMessageListener" value="false"/>
<property name="PayloadType" value="TextMessage"/>
<property name="EnableStreaming" value="true"/>
</activation-spec>
■ Supports Error Handling

Oracle JMS Adapter Concepts
For information about error handling, refer to Section 2.10, "Error Handling."
A transaction enables an application to coordinate a group of messages for production
and consumption, treating messages sent or received as a single unit. When an
application commits a transaction, all messages it received within the transaction are
removed by the JMS provider. The messages it sent within the transaction are
delivered as one unit to all JMS consumers. If the application rolls back the transaction,
then the messages it received within the transaction are returned to the messaging
system and the messages it sent are discarded. The Oracle JMS Adapter supports JMS
transactions. A JMS-transacted session supports transactions that are located within
the session. A JMS-transacted session's transaction does not have any effects outside of
the session.
8.3 Oracle JMS Adapter Concepts
Messaging is any mechanism that enables communication between programs.
Messages are structured data that one application sends to another. Message-oriented
middleware (MOM) is an infrastructure that supports scalable enterprise messaging.
MOM ensures fast, and reliable asynchronous communication, guaranteed message
delivery, receipt notification, and transaction control. JMS is a Java interface developed
by Sun Microsystems for producing, sending, and receiving messages of an enterprise
messaging system. JMS is an API that JMS vendors implement. Oracle provides two
implementations of JMS, WLS JMS and Oracle JMS based on Oracle advanced queues.
A JMS producer creates JMS messages and a JMS consumer consumes JMS messages.
JMS supports two messaging paradigms, point-to-point (queues) and
publish/subscribe (topics).
■ Section 8.3.1, "Point-to-Point"
■ Section 8.3.2, "Publish/Subscribe"
■ Section 8.3.3, "Destination, Connection, Connection Factory, and Session"
■ Section 8.3.4, "Structure of a JMS Message"
■ Section 8.3.5, "Oracle JMS Adapter Header Properties"
8.3.1 Point-to-Point
In point-to-point messaging, the messages are stored in a queue until they are
consumed. One or more producers write to the queue and one or more consumers
extract messages from the queue. The JMS consumer sends an acknowledgment after
consumption of a message; this results in purging of the message from the queue.
8.3.2 Publish/Subscribe
In publish/subscribe messaging, producers publish messages to a topic, and the
consumer subscribes to a particular topic. Many publishers can publish to the same
topic, and many consumers can subscribe to the same topic. All messages published to
the topic by the producers are received by all consumers subscribed to the topic. By
default, subscribers receive messages only when the subscribers are active. However,
JMS API supports durable subscriptions that ensure that consumers receive messages
Note: Oracle JMS Adapter cannot be used programmatically inside
an EJB or JMS client.

Oracle JMS Adapter Concepts
that were published even when the subscribers are not up and running. The durable
subscription involves registering the consumer with a unique ID for retrieving
messages that were sent when the consumer was inactive. These messages are
persisted by the JMS provider and are either sent to the consumer when it becomes
active again or purged from storage if the message expires. The JMS producer can be
set either to persistent or nonpersistent mode. The messages are not persisted in the
latter case and can be used only for nondurable subscriptions.
For scenarios that requires you to work with durable subscriptions on Oracle
WebLogic Server, a connector factory with ClientID property defined is required, as
<FactoryProperties>ClientID=uniquename</FactoryProperties>
When defining multiple durable subscriber it would entail you to define multiple
connector factory each with a unique ClientID property specified. You must take
care to not use the same connector factory for any other adapter interaction (such as
outbound interaction if it is used for processing inbound messages) because Oracle
WebLogic Server allows a clientid to be bound only once. For a scenario in which a
connector factory with ClientId defined is used on the inbound to process incoming
messages a different connector factory should be used for the outbound adapter
interactions.
The JMS API supports both synchronous and asynchronous communication for
message consumption. In the synchronous case, the consumer explicitly calls the
receive() method on the topic or queue. In the asynchronous case, the JMS client
registers a message listener for the topic or queue and the message is delivered by
calling the listener's onMessage() method.
8.3.3 Destination, Connection, Connection Factory, and Session
The destination property contains the addressing information for a JMS queue or
topic.
Connections represent a physical connection to the JMS provider. The connection
factory is used to create JMS connections. A session is used to create a destination, JMS
producer, and JMS consumer objects for a queue or topic.
8.3.4 Structure of a JMS Message
The JMS message has a mandatory standard header element, an optional properties
element, and an optional standard payload element. The payload can be a text
message, byte message, map message, stream message, or object message. The
properties element is JMS provider-specific and varies from one JMS provider to
another.
8.3.5 Oracle JMS Adapter Header Properties
For information about the Oracle JMS Adapter header properties, see Appendix A.4,
"Oracle JMS Adapter Properties."
Note: You must manually remove durable subscribers that are not
used by the BPEL partner link. Oracle JMS Adapter does not
automatically remove these durable subscriptions.

Oracle JMS Adapter Use Cases
8.4 Oracle JMS Adapter Use Cases
■ Section 8.4.1, "Configuring Oracle JMS Adapter"
■ Section 8.4.2, "Configuring Oracle JMS Adapter with TIBCO JMS"
■ Section 8.4.3, "Configuring Oracle JMS Adapter with IBM WebSphere MQ JMS"
■ Section 8.4.4, "WLS JMS Text Message"
■ Section 8.4.5, "Accessing Queues and Topics from WLS JMS Server in a Remote
Oracle WebLogic Server Domain"
■ Section 8.4.6, "Synchronous/Asynchronous Request Reply Interaction Pattern"
■ Section 8.4.7, "AQ JMS Text Message"
■ Section 8.4.8, "Accessing Queues and Topics Created in 11g from the OC4J 10.1.3.4
Server"
8.4.1 Configuring Oracle JMS Adapter
The following use case demonstrates the procedure for configuring Oracle JMS
Adapter and examines the resulting WSDL files and associated weblogic-ra.xml
files.
■ Section 8.4.1.2, "Using the Adapter Configuration Wizard to Configure Oracle JMS
Adapter"
■ Section 8.4.1.3, "Generated Files"
■ Section 8.4.1.4, "weblogic-ra.xml file"
■ Section 8.4.1.5, "Produce Message Procedure"
You must first create an Oracle JDeveloper application to contain the SOA composite.
Use the following steps to create a new application and an SOA project:
The Create Generic Application - Name your Application page is displayed, as
3. Enter a name for the application in the Application Name field. For example,
AQQueue2Queue.

Figure 8–1 The Create Generic Application - Name your application Page
5. Click Next.
The Name your project dialog is displayed, as shown in Figure 8–2.
6. In the Project Name field, enter a descriptive name. For example,
AQQueue2Queue.
Figure 8–2 The Create Generic Application - Name your Generic project Page
8. Click Next.

The Create Generic Application - Configure SOA settings page is displayed, as
Figure 8–3 The Create Generic Application - Configure SOA Settings Page
Finish.
You have created a new application, and an SOA project. This automatically
creates an SOA composite.
10. Enter a name for the BPEL process in the Name field. In this example, use the
default name.

You have created a BPEL process.
8.4.1.2 Using the Adapter Configuration Wizard to Configure Oracle JMS Adapter
The following are the steps to configure an Oracle JMS Adapter by using the Adapter
Configuration Wizard:
2. Drag and drop JMS Adapter from the Service Adapters list to the Exposed
Services swim lane in the composite.xml page.
3. Click Next.
The Adapter Configuration Wizard - Service Name page is displayed, as shown in
Figure 8–5.
Figure 8–5 Service Name Page
4. Enter a name for the service, and then click Next.
The Adapter Configuration Wizard - JMS Provider page is displayed, as shown in
Figure 8–6.

Figure 8–6 The Adapter Configuration Wizard - JMS Provider Page
5. Select any one operation. In this example, select Oracle Weblogic JMS.
■ Oracle Enterprise Messaging Service (OEMS): This enables you to integrate
with the Weblogic service or Advanced Queueing messaging service.
■ Third Party: Select this option to integrate with a third party provider.
6. Click Next.
The Adapter Configuration Wizard - Service Connection page is displayed.
7. You must establish connectivity between the design-time environment and the
server you want to deploy it to.
Perform the steps mentioned in Section 2.16, "Creating an Application Server
Connection for Oracle JCA Adapters" to create an application server connection.
8. Click Next. The Adapter Interface page is displayed, as shown in Figure 8–7.
(specified later).

Figure 8–7 The Adapter Configuration Wizard - Adapter Interface Page
10. Click Next.
The Adapter Configuration Wizard- Operation page is displayed.
11. Select Consume Message, Produce Message, or Request/Reply. In this example,
select Consume Message.
The operation name is filled in automatically, as shown in Figure 8–8.
Figure 8–8 The Adapter Configuration Wizard - Operation Page

The Consume Message option enables the adapter to consume (receive) inbound
messages from a JMS destination.
12. Click Next.
The Adapter Configuration Wizard - Consume Operation Parameters page is
Figure 8–9 The Adapter Configuration Wizard - Consume Operation Parameters Page
13. Enter values for the following fields:
■ Destination Name
This is the JNDI name of the JMS queue or topic from which to receive the
message. This is not an editable field. You must click Browse to browse for the
queue or topic. The queue or topic to be chosen is based on the type of JMS
provider you are using.
For more information, see the following sections:
– Section 8.4.2, "Configuring Oracle JMS Adapter with TIBCO JMS"
– Section 8.4.3, "Configuring Oracle JMS Adapter with IBM WebSphere MQ
JMS"
■ Message Body Type
The supported values are TextMessage, BytesMessage, MapMessage. The
StreamMessage message type is not supported in this release.
■ Durable Subscriber ID
This field is optional. If you are setting up a durable subscriber, then the
durable subscriber ID is required. Generally, a subscriber loses messages if the
subscriber becomes disconnected, but a durable subscriber downloads stored
messages when it reconnects.

■ Message Selector
This field is also optional. It filters messages based on header and property
information. The message selector rule is a Boolean expression. If the
expression is true, then the message is consumed. If the expression is false,
then the message is rejected.
For example, you can enter logic, such as:
– JMSPriority > 3. Based on this, messages with a priority greater than 3 are
consumed; all other messages are rejected.
– JMSType = 'car' AND color = 'blue' AND weight > 2500
– Country in ('UK', 'US', 'France')
■ Use MessageListener
This field is always set to False by default.
■ JNDI Name
The value specified in the JNDI name should exist in the Oracle JMS Adapter
weblogic-ra.xml file to ensure that the adapter runs in managed mode.
After you enter the appropriate parameters, click Next.
14. The Adapter Configuration Wizard - Messages page is displayed, as shown in
Figure 8–10. The settings in this page define the correct schema for the message
payload.
You can perform one of the following:
■ Check Native format translation is not required (Schema is Opaque), which
disables the rest of the fields.
■ Click Define Schema for Native Format to start the Native Format Builder
Wizard, which guides you through the process of defining the native format.
■ Enter the path for the schema file URL (or browse for the path).
The following steps demonstrate the last option: browsing for the schema file
URL.
Note: When the JMS provider is Oracle Weblogic JMS or Oracle
Advanced queueing messaging service, then the Durable Subscriber
option will show up only when a topic is selected. However, the
Durable Subscriber option always appears when the JMS provider is a
third party.
Note: This example shows a consume message operation. For a
produce message operation, this page is different. See Section 8.4.1.5,
"Produce Message Procedure" to see how this part of the procedure
differs.

15. Click the Browse button.
The Type Chooser dialog is displayed, with the Type Explorer navigation tree, as
16. Browse the tree and select the appropriate schema type, and then click OK.
Figure 8–11 Selecting a Schema from the Type Chooser Dialog
The Messages page is displayed again, this time with the Schema File URL field
and the Schema Element field filled up, as shown in Figure 8–12.

Figure 8–12 Completed Messages Dialog
17. Click Next.
The Finish page is displayed. This box shows the path and name of the adapter
18. Click Finish.
The composite.xml page is displayed.
8.4.1.3 Generated Files
The following composite file is generated by the Adapter Configuration Wizard:
<composite name="AQQueue2Queue"
revision="1.0"
label="2007-09-04_11-58-50_914"
mode="active"
state="on"
xmlns="http://xmlns.oracle.com/sca/1.0"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:orawsp="http://schemas.oracle.com/ws/2006/01/policy">
<import namespace="http://xmlns.oracle.com/pcbpel/adapter/jms/Inbound/"
location="Inbound.wsdl" importType="wsdl"/>
<import namespace="http://xmlns.oracle.com/pcbpel/adapter/jms/Outbound/"
location="Outbound.wsdl" importType="wsdl"/>
<interface.wsdl
interface="http://xmlns.oracle.com/pcbpel/adapter/jms/Inbound/#wsdl.interface(Cons
ume_Message_ptt)"/>
<binding.jca config="Inbound_jms.jca"/>
</service>
<component name="BPELProcess1">
<implementation.bpel src="BPELProcess1.bpel"/>
</component>
<reference name="Outbound">

<interface.wsdl
interface="http://xmlns.oracle.com/pcbpel/adapter/jms/Outbound/#wsdl.interface(Pro
duce_Message_ptt)"/>
<binding.jca config="Outbound_jms.jca"/>
</reference>
<wire>
<source.uri>Inbound</source.uri>
<target.uri>BPELProcess1/Inbound</target.uri>
</wire>
<wire>
<source.uri>BPELProcess1/Outbound</source.uri>
<target.uri>Outbound</target.uri>
</wire>
</composite>
The following code segment defines the name of the adapter and the locations of
various necessary schemas and other definition files.
<import namespace="http://xmlns.oracle.com/pcbpel/adapter/jms/Inbound/"
location="Inbound.wsdl" importType="wsdl"/>
<import namespace="http://xmlns.oracle.com/pcbpel/adapter/jms/Outbound/"
location="Outbound.wsdl" importType="wsdl"/>
This code segment imports the necessary namespace.
targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/jms/Inbound/"
xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/jms/Inbound/"
xmlns:imp1="http://xmlns.oracle.com/pcbpel/samples/expense">
<types>
<import namespace="http://xmlns.oracle.com/pcbpel/samples/expense"
schemaLocation="xsd/expense.xsd"/>
</schema>
</types>
<message name="ExpenseRecord_msg">
<part name="ExpenseRecord" element="imp1:ExpenseRecord"/>
</message>
<portType name="Consume_Message_ptt">
<operation name="Consume_Message">
<input message="tns:ExpenseRecord_msg"/>
</operation>
</portType>
This code segment defines the message type, name, and the port type for the partner
link.
<adapter-config name="dequeue" adapter="Jms Adapter"
<connection-factory location="eis/wls/Queue" UIConnectionName="wls3"
UIJmsProvider="WLSJMS" adapterRef=""/>
<endpoint-activation portType="Consume_Message_ptt" operation="Consume_Message">
<activation-spec
className="oracle.tip.adapter.jms.inbound.JmsConsumeActivationSpec">
<property name="DestinationName" value="jms/DemoInQueue"/>
<property name="UseMessageListener" value="false"/>
<property name="PayloadType" value="TextMessage"/>
</activation-spec>

</adapter-config>
8.4.1.4 weblogic-ra.xml file
The weblogic-ra.xml file defines the endpoints for the JMS connection factories.
The connection factories include configuration properties for each endpoint. Endpoints
are added to accommodate different types of connections, as demonstrated in the
following sections. The following example is from the generic weblogic-ra.xml file:
<connection-instance>
<jndi-name>eis/wls/Queue</jndi-name>
<connection-properties>
<properties>
<property>
<name>ConnectionFactoryLocation</name>
<value>weblogic.jms.XAConnectionFactory</value>
</property>
<property>
<name>FactoryProperties</name>
<value></value>
</property>
<property>
<name>AcknowledgeMode</name>
<value>AUTO_ACKNOWLEDGE</value>
</property>
<property>
<name>IsTopic</name>
<value>false</value>
</property>
<property>
<name>IsTransacted</name>
</property>
<property>
<name>Username</name>
<value></value>
</property>
<property>
<name>Password</name>
<value></value>
</property>
</properties>
</connection-properties>
</connection-instance>
Note that you can also create a new connection by using the Oracle WebLogic Server
Administration Console.
Creating a New Connection by Using the Oracle WebLogic Server Administration
Console
The following are the steps for creating a new connection by using the Oracle
WebLogic Server Administration Console:

displayed.
3. Select Deployments in the Domain Structure pane.
The Oracle WebLogic Server Administration Console - Summary of Deployments
page is displayed.
4. Under Deployments, click any JMS adapter that you have deployed. For example,
click JmsAdapter.
The Oracle WebLogic Server Administration Console - Settings for JmsAdapter
page is displayed.
5. Click the Configuration tab, and then click the Outbound Connection Pools tab.
The Outbound Connection Pool Configuration Table is displayed.
6. Click Next.
The Create a New Outbound Connection page is displayed.
7. Select the default outbound connection group, and then click Next.
8. Click Next.
9. In the JNDI Name field, enter the JNDI name that you want to use to obtain the
new connection instance. For example, eis/wls/Queue.
Note that you can specify any name for the JNDI field. However, you must ensure
that you use the same JNDI name while defining the consume or produce
operation parameters in Oracle JDeveloper.
10. Click Finish.
The Save Deployment Plan Assistant page is displayed.
The configuration changes that you made must be stored in a new deployment
plan.
11. In the Path field, select or enter the path of a deployment plan file. The path must
end with '.xml'.
12. Click OK.
You have created a new connection. After you have done this, you must verify
whether the properties you have created are correct.
13. In the Settings for JmsAdapter page, click the Configuration tab, and then click
the Properties tab.
The connection that you created is listed in this page. Verify whether this value is
correct. For example, if you are connecting to a third-party JMS server, then ensure
that the Connection Factory Location field has the correct value applicable for a
third-party JMS server.
14. Click Save.
Note: In this example, you created a new connection for Oracle JMS
Adapter by using the Oracle WebLogic Server Administration
Console. To create connection for other adapters, you must follow the
same steps. However, ensure that you select the appropriate adapter
for which you want to create a connection in Step 4.

8.4.1.5 Produce Message Procedure
A produce message operation has certain differences in the definition procedure,
particularly in Step 13 of Section 8.4.1.2, "Using the Adapter Configuration Wizard to
Configure Oracle JMS Adapter." Instead of specifying consume operation parameters,
you specify the following produce operation parameters. This enables the adapter to
produce (send) outbound messages for a JMS destination. The Produce Operation
Parameters page is shown in Figure 8–13.
■ Destination Name:
The JNDI name of the JMS queue or topic to which the message must be delivered.
The name to enter is based on the type of JMS provider you use.
For more information about destination name, see the following:
– Section 8.4.2, "Configuring Oracle JMS Adapter with TIBCO JMS"
– Section 8.4.3, "Configuring Oracle JMS Adapter with IBM WebSphere MQ
JMS"
■ Message Body Type:
The supported values are TextMessage, BytesMessage, and MapMessage.
StreamMessage is not supported in this release.
■ Delivery Mode:
The values are Persistent or Nonpersistent. A persistent delivery mode
specifies a persistent JMS publisher; that is, a publisher that stores messages for
later use by a durable subscriber. A durable subscriber is a consume message with
a durable subscriber ID in the corresponding field in Step 15 of Section 8.4.1.2,
"Using the Adapter Configuration Wizard to Configure Oracle JMS Adapter." A
nondurable subscriber loses any messages that are produced when the adapter is
not active. A durable subscriber downloads messages that have been stored in the
persistent publisher, and therefore does not have to remain active at all time to
receive all the messages.
■ Priority:
Select a priority value, with 9 representing the highest priority and 0 representing
the lowest priority. The default is 4.
■ TimeToLive:
The amount of time before the message expires and is no longer available to be
consumed.

Figure 8–13 Produce Operation Parameters Page
8.4.2 Configuring Oracle JMS Adapter with TIBCO JMS
This section describes how to configure Oracle JMS Adapter with Tibco JMS for direct
connection and nondirect connection.
8.4.2.1 NonDirect Connection
1. Copy the following file to the <SOAInstall_DIR>/user_
projects/domains/<DOMAIN_NAME>/lib folder:
■ /<YOUR-TIBCO-INSTALL-LOCATION>/clients/java/tibjms.jar
2. Configure the connector factory by modifying the weblogic-ra.xml file in
AS11gR1SOA/soa/connectors/JmsAdapter.rar, as shown in the following
example:
<jndi-name>eis/tibjms/Topic</jndi-name>
<properties>
<property>
<value>TopicConnectionFactory</value>
</property>
<property>
<value>java.naming.factory.initial=com.tibco.tibjms.naming.TibjmsInitialContext
Factory;java.naming.provider.url=tibjms
naming://<HOST>:<PORT>;java.naming.security.principal=<USERNAME>;java.naming.se
curity.credentials=<PASSWORD></value>
</property>
<property>

</property>
<property>
<value>true</value>
</property>
<property>
<value>true</value>
</property>
<property>
<value><USERNAME></value>
</property>
<property>
<value><PASSWORD></value>
</property>
</properties>
<jndi-name>eis/tibjms/Queue</jndi-name>
<properties>
<property>
<value>QueueConnectionFactory</value>
</property>
<property>
<value>java.naming.factory.initial=com.tibco.tibjms.naming.TibjmsInitialContext
Factory;java.naming.provider.url=tibjms
naming://<HOST>:<PORT>;java.naming.security.principal=<USERNAME>;java.naming.se
curity.credentials=<PASSWORD></value>
</property>
<property>
</property>
<property>
</property>
<property>
<value>true</value>
</property>
<property>
</property>
<property>
</property>
</properties>

Note that the default <USERNAME> and <PASSWORD> are admin and
password, respectively.
Alternatively, to configure a new connection factory by using the Oracle WebLogic
Server Administration Console, use the steps mentioned in Section 2.4, "Adding an
8.4.2.2 Direct Connection
1. Copy the following file to the <SOAInstall_DIR>/user_
■ /<YOUR-TIBCO-INSTALL-LOCATION>/clients/java/tibjms.jar
example:
<jndi-name>eis/tibjmsDirect/Queue</jndi-name>
<properties>
<property>
<value>com.tibco.tibjms.TibjmsQueueConnectionFactory</value>
</property>
<property>
<value>ServerUrl=tcp://<HOST>:<PORT>;UserName=<USERNAME>;UserPassword=<PASSWORD
></value>
</property>
<property>
</property>
<property>
</property>
<property>
<value>true</value>
</property>
<property>
</property>
<property>
</property>
</properties>
<jndi-name>eis/tibjmsDirect/Topic</jndi-name>
<properties>

<property>
<value>com.tibco.tibjms.TibjmsTopicConnectionFactory</value>
</property>
<property>
<value>ServerUrl=tcp://<HOST>:<PORT>;UserName=<USERNAME>;UserPassword=<PASSWORD
></value>
</property>
<property>
</property>
<property>
<value>true</value>
</property>
<property>
<value>true</value>
</property>
<property>
</property>
<property>
</property>
</properties>
Note that the default <USERNAME> and <PASSWORD> are admin and
8.4.3 Configuring Oracle JMS Adapter with IBM WebSphere MQ JMS
This section describes how to configure Oracle JMS Adapter with IBM WebSphere MQ
JMS for non-XA and XA data sources.
8.4.3.1 Non-XA Data Sources
1. Copy the following files to the <SOAInstall_DIR>/user_
■ /<YOUR-MQSERIES-INSTALL-LOCATION>/java/lib/com.ibm.mq.jar
■ /<YOUR-MQSERIES-INSTALL-LOCATION>/java/lib/com.ibm.mqjms.jar
■ /<YOUR-MQSERIES-INSTALL-LOCATION>/java/lib/dhbcore.jar

example:
<connection-factory connector-name="Jms Adapter"
location="eis/webspheremq/Queue">
<config-property name="connectionFactoryLocation"
value="com.ibm.mq.jms.MQQueueConnectionFactory" encodedcredential="
false"/>
<config-property name="factoryProperties"
value="QueueManager=<QUEUEMANAGER>;TransportType=1;HostName=<YOUR-HOST>;Port=<Y
OURPORT>;
Channel=<CHANNEL>" encoded-credential="false"/>
<config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE"
encoded-credential="false"/>
<config-property name="isTopic" value="false" encoded-credential="false"/>
<config-property name="isTransacted" value="true" encoded-credential="false"/>
<config-property name="username" value="<USERNAME>"
<config-property name="password" value="<PASSWORD>"
</connection-factory>
Note that the default <USERNAME> and <PASSWORD> are MUSR_MQADMIN and
8.4.3.2 XA Data Sources
1. Copy the following files to the <SOAInstall_DIR>/user_
■ /<YOUR-MQSERIES-INSTALL-LOCATION>/java/lib/com.ibm.mq.jar
■ /<YOUR-MQSERIES-INSTALL-LOCATION>/java/lib/com.ibm.mqjms.jar
■ /<YOUR-MQSERIES-INSTALL-LOCATION>/java/lib/dhbcore.jar
■ com.ibm.mqetclient.jar
This is an IBM-extended transactional client, which is an optional component
that requires separate licensing.
example:
<connection-factory connector-name="Jms Adapter"
location="eis/webspheremq/Queue">
value="com.ibm.mq.jms.MQXAQueueConnectionFactory"
value="QueueManager=<QUEUEMANAGER>;TransportType=1;HostName=<YOUR-HOST>;Port=<Y
OURPORT>;
Channel=<CHANNEL>" encoded-credential="false"/>
<config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE"

<config-property name="isTopic" value="false" encoded-credential="false"/>
<config-property name="isTransacted" value="false" encoded-credential="false"/>
<config-property name="username" value="<USERNAME>"
<config-property name="password" value="<PASSWORD>"
</connection-factory>
Note that the default <USERNAME> and <PASSWORD> are MUSR_MQADMIN and
3. Right-click the queue and select Put Test Message to send message by using
WebSphere MQ Explorer.
4. Right-click the queue and select Browse Messages to browse messages in
outbound queue by using WebSphere MQ Explorer.
8.4.4 WLS JMS Text Message
This use case demonstrates how the Oracle JMS Adapter dequeues from and enqueues
to the WLS JMS Queue.
■ Section 8.4.4.2, "Creating an Application Server Connection"
You must perform the following prerequisite for this use case:
8.4.4.1.1 Creating Queues in the Oracle WebLogic Server Administration Console
Perform the following steps to create queues required for this use case:
http://servername:portnumber/console

Figure 8–14 The Oracle WebLogic Server Administration Console Home Page
3. Navigate to Services, Messaging, JMS Modules in the Domain Structure pane.
The Oracle WebLogic Server Administration Console - JMS Modules page is
displayed.
4. Click one of the existing modules. In this example, click SOAJMSModule.
The Oracle WebLogic Server Administration Console - Settings for
SOAJMSModule page is displayed.
5. Under the Summary of Resources section, click New.
The Oracle WebLogic Server Administration Console - Create a New JMS System
Module Resource page is displayed.
6. Select Queue, and then click Next.
7. Enter the following queue details:
■ Name
■ JNDI Name
■ Template
8. Click Next.
9. Select the subdeployment you want to use from the Subdeployments list.
10. Click Finish.
You have created the queue, ReceiveQueue.
11. Repeat steps 1 through 10, and create a queue named SendQueue.
8.4.4.2 Creating an Application Server Connection
you want to deploy to. Perform the steps mentioned in Section 2.16, "Creating an

Application Server Connection for Oracle JCA Adapters" to create an application
server connection.
Application - Name your Application dialog is displayed.
queue2queue.
5. Click Next.
The Name your project page is displayed.
6. In the Project Name field, enter a descriptive name. For example, queue2queue.
displayed.
Finish.
You have created a new application, and an SOA project.
10. Enter a name for the BPEL process in the Name field. For example, queue2queue.
The queue2queue application, queue2queue project, and the SOA composite
appear in the design area.
12. Copy the Q2Qorders.xsd file from the following location to the XSD folder in
your project:
Perform the following steps to create an adapter service that will dequeue the message
to a queue:
Services swim lane in the composite.xml page.
2. Click Next.
3. Enter Inbound in the Service Name field, and click OK.

The JMS Provider page is displayed.
4. Select Oracle Weblogic JMS in the Oracle Enterprise Messaging Service (OEMS)
box, as shown in Figure 8–15, and click Next. The Service Connection page is
displayed.
Figure 8–15 The Adapter Configuration Wizard JMS Provider Page
5. Select the connection created in Section 8.4.4.2, "Creating an Application Server
Connection," as shown in Figure 8–16.
Figure 8–16 The Adapter Configuration Wizard Service Connection Page

8. Select Consume Message, as shown in Figure 8–17, and click Next.
The Consume Operation Parameters page is displayed.
9. Click Browse and select ReceiveQueue in the Destination field.
The Consume Operation Parameters page is displayed.
10. Enter the parameters for the consume operation, and then click Next.
11. Click Browse at the end of the URL field.
12. Select Project Schema Files, Q2Qorders.xsd, and Items, as shown in Figure 8–18.
Note: The value specified in the JNDI name should exist in the
Oracle JMS Adapter weblogic-ra.xml file to ensure that the
adapter runs in managed mode.

13. Click Next. The Q2Qorders.xsd schema file is displayed in the URL in the
Messages page, as shown in Figure 8–19.
Figure 8–19 The Adapter Configuration Wizard - Message Page
15. Click Finish. You have configured a JMS inbound adapter service.

Perform the following steps to create an adapter service to enqueue the request
1. Drag and drop JMS Adapter from the Component Palette into the Exposed
Services swim lane. The Adapter Configuration Wizard Welcome page is
displayed.
3. Enter Outbound in the Service Name field, and click OK. The JMS Provider page
is displayed.
4. Select Oracle Weblogic JMS in the Oracle Enterprise Messaging Service (OEMS)
box, and click Next. The Service Connection page is displayed.
Connection," and click Next. The Adapter Interface page is displayed.
7. Select Produce Message, and click Next. The Produce Operation Parameters page
is displayed.
8. Click Browse and select SendQueue in the Destination field. The Produce
Operation Parameters page is displayed.
10. Click Browse at the end of the URL field. The Type Chooser dialog is displayed.
11. Select Project Schema Files, Q2Qorders.xsd, and Items.
12. Click Next. The Q2Qorders.xsd schema file is displayed in the URL in the Message
dialog.
14. Click Finish. You have configured the JMS adapter service, and the composite.xml
page is displayed.
You must wire the three components that you have created, Inbound adapter service,
BPEL process, and Outbound adapter reference. Perform the following steps to wire
components together:
1. Drag the small triangle in the inbound Oracle JMS Adapter component in the
Exposed Services area to the drop zone that appears as a green triangle in the
BPEL process in the Components area.
zone that appears as a green triangle in the outbound Oracle JMS Adapter in the
The Oracle JDeveloper Composite.xml is displayed, as shown in Figure 8–20.

4. Double-click queue2queue.
The queue2queue.bpel page is displayed.
5. Drag and drop the Receive, Assign, and Invoke activities in the order mentioned
from the Component Palette to the Components area, as shown in Figure 8–21.
Figure 8–21 The queue2queue.bpel Page
6. Double-click Receive.

8. Select Inbound, and then click OK.
value Inbound.
field.
10. Accept the defaults, and click OK.
11. Select the Create Instance box, as shown in Figure 8–22, and click OK.
12. Double-click the Invoke activity.
14. Select Outbound, and then click OK.
value Outbound.
The Invoke dialog is displayed, as shown in Figure 8–23.

17. Click OK.
19. Click the plus icon, and select Copy Operation. The Create Copy Operation dialog
is displayed.
20. Select the variables, as shown in Figure 8–24, and click OK.
JDeveloper, use the following steps:
Adapters."

following steps:
The composite you deployed is displayed in the Applications Navigation tree.
2. In the Last 5 Instances pane, there is an entry of a new instance. This is the instance
that was triggered when you enqueued a message using queue2queue.java.
4. Click the TextMessage component instance. The Audit page is displayed.
8.4.5 Accessing Queues and Topics from WLS JMS Server in a Remote Oracle
WebLogic Server Domain
Oracle JMS Adapter can be used to access remote WLS JMS destinations. Remote
destinations refer to queues or topics that are defined in a WLS JMS server, which is
part of a remote Oracle WebLogic Server domain.
In order to do so, ensure that you use the connector factory configured to interact to
the remote WLS JMS server. You can achieve this by setting the <FactoryProperties>
property of the connector factory defined in weblogic-ra.xml to remote server
configuration, as shown in the following example:
<property>
<value>java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory;java.nami
ng.provider.url= t3://<HOST>:<PORT>;java.naming.security.principal=
<USERNAME>;java.naming.security.credentials=<PASSWORD></value>
</property>
To enable Oracle JMS Adapter to read from a remote queue that is present in a remote
WLS JMS server, you must configure the following:
1. You must have a unique domain name and JMS server name in both the servers.
2. You must enable global trust between the two servers.
Refer to the following link for information about how to enable global trust
between servers:
http://edocs.bea.com/wls/docs100/ConsoleHelp/taskhelp/securit
y/EnableGlobalTrustBetweenDomains.html
This configuration holds good when you connect to queues or topics present in
WLS9.2 server.
8.4.6 Synchronous/Asynchronous Request Reply Interaction Pattern
Oracle JMS Adapter supports both synchronous and asynchronous request reply
interaction pattern.

Asynchronous Request Reply Pattern
You can use the Adapter Configuration Wizard to model a process that allows Oracle
JMS Adapter to be used in an asynchronous request reply interaction pattern.
Basically this pattern allows an Oracle JMS Adapter to send a message to a JMS
destination. When a message is received on the reply queue, the Oracle JMS Adapter is
able to route message to the correct composite or the component instance. The
correlation is done based on the JMS message id of the request message, which
becomes the JMSconversationId of the reply message, and the conversation ID of
the underlying component.
Synchronous Request Reply Pattern
You can use the Adapter Configuration Wizard to model a process that will allow
Oracle JMS Adapter to be used in a synchronous request reply interaction pattern. In
this case, the Oracle JMS Adapter sends a request to the request queue and waits for a
response from the reply queue before further execution continues. Underneath, the
Oracle JMS Adapter uses a new interaction pattern
JmsRequestReplyInteractionSpec. The spec allows for a request and reply
destination name to be configured. A variation, new to 11R1, allows usage of
temporary destination as part of the reply queue. Basically, this pattern allows an
Oracle JMS Adapter to send a message to a JMS destination. In turn, the adapter will
set the JMSReplyTo header to the reply destination. This value is then used by a third
party client to send the message to the reply destination which is then dequeued by
the Oracle JMS Adapter.
When using the Oracle JMS Adapter in a synchronous pattern ensure that you use the
non XA connection factory and also set the connector factory isTransacted
property to true.
When you use with WLS JMS, the connection factory must be
weblogic.jms.ConnectionFactory or any other non XA connection factory defined.
Also, if WLS JMS is running in the local JVM, the same one as the adapter, then you
must ensure that the connector factory isTransacted property should be set to false
instead of true.
8.4.7 AQ JMS Text Message
This use case demonstrates how the Oracle JMS Adapter dequeues from and enqueues
to the AQ JMS Queue.
This sample (AQQueuetoQueue) is available at the following location:
■ Section 8.4.7.2, "Create an Application Server Connection"

You must perform the following prerequisites to complete this use case:
■ Section 8.4.7.1.1, "Configuring AQ JMS in Oracle WebLogic Server Administration
Console"
■ Section 8.4.7.1.2, "Creating Queues in Oracle Database"
8.4.7.1.1 Configuring AQ JMS in Oracle WebLogic Server Administration Console
To configure AQ JMS in Oracle WebLogic Server Administration Console, you must
perform the following steps:
■ Adding an Oracle WebLogic JMS Module
■ Adding an AQJMS Foreign Server to the JMS Module
■ Configuring the AQJMS Foreign Server
■ Adding Connection Factories to the AQ JMS Foreign Server
■ Adding Destinations to the AQJMS Foreign Server
Adding an Oracle WebLogic JMS Module
Note that adding an Oracle WebLogic JMS module is optional. You can also create an
AQJMS foreign server in a preexisting JMS module.
displayed.
3. Navigate to Services, Messaging, JMS Modules in the Domain Structure pane.
The Oracle WebLogic Server Administration Console - JMS Modules page is
displayed.
4. Click New to create a new WebLogic JMS module.
The Oracle WebLogic Server Administration Console - Create JMS System Module
page is displayed.
5. Enter a name for the JMS module, and then click Next.
page is displayed.
6. Select a target server where your SOA component is running, and then click Next.
page is displayed.
7. Click Finish.
You have created a JMS module.
Adding an AQJMS Foreign Server to the JMS Module
The next step is to add an AQ JMS foreign server to the JMS module by performing the
following:
1. Click the JMS module that you created.

The Oracle WebLogic Server Administration Console - Settings for AQJMSModule
page is displayed.
2. Click New in the Summary of Resources table to create a new JMS system module
resource.
3. Under Choose the type of resource you want to create, select Foreign Server, and
then click Next.
4. In the Name field, enter a name for the foreign server, and then click Finish.
The Oracle WebLogic Server Administration Console - Settings for <JMS Module
Name> page is displayed.
Configuring the AQJMS Foreign Server
The next step is to configure the AQJMS foreign server that you created:
1. Click the AQ JMS Foreign Server listed under the Summary of Resources table.
The Oracle WebLogic Server Administration Console - Settings for TestAQJMS_
ForeignServer page is displayed.
2. Enter the following values:
■ JNDI Initial Context Factory:
oracle.jms.AQjmsInitialContextFactory
If the AQJMS Foreign Server is used by the WebLogic server side components,
then you must configure a data source with this AQ JMS Foreign Server, by
specifying the following values:
In the JNDI Properties field, enter datasource=<datasource jndi location>.
Replace the place holder with the JNDI location of your data source.
However, if the AQJMS Foreign Server is used by WebLogic application client,
then you must configure the JDBC URL with the AQ JMS foreign server you
created.
■ JNDI Connection URL: Specify the URL that WebLogic Server will use to
contact the JNDI provider.
This value is required only if the AQJMS foreign server is used by the
WebLogic application client.
■ JNDI Properties Credential: Specify any Credentials that must be set for the
JNDI provider.
This value is required only if the AQJMS foreign server is used by the
Weblogic application client.

Adding Connection Factories to the AQ JMS Foreign Server
To add connection factories to the AQJMS foreign server:
1. In the Connection Factories tab in the Settings for <Foreign Server Name> page,
click the AQJMS foreign server that you created.
2. Click New.
The Oracle WebLogic Server Administration Console - Create a New Foreign JMS
Connection Factory page is displayed.
3. In the Name field, enter a name for this connection factory. This is a logical name
that would be referenced by Oracle WebLogic Server.
4. In the Local JNDI Name field, enter the local JNDI name that you would use in
your application to look up this connection factory.
5. In the Remote JNDI Name field, enter one of the following values depending on
your requirement. If you use this connection factory in a global transaction, then
use an XA-based connection factory, else use non-XA based connection factory.
■ QueueConnectionFactory
■ TopicConnectionFactory
■ ConnectionFactory
■ XAQueueConnectionFactory
■ XATopicConnectionFactory
■ XAConnectionFactory
6. Click OK.
Adding Destinations to the AQJMS Foreign Server
To add destinations to the AQJMS foreign server:
1. Click the Destinations tab in the Settings for <Foreign Server Name> page.
2. Click New and specify a name for this destination. This is a logical name that will
be referenced by the Oracle WebLogic Server and has nothing to do with the
destination name.
Note: If you want to use RAC database as adapter endpoint, then the
datasource pointed by the JNDI property, mentioned in the preceding
step, must point to a multi data source.
Individual data sources and multi data sources used for such
endpoints must use the recommended setting listed in Section 2.21,
"Recommended Setting for Data Sources Used by Oracle JCA
Adapters."
Note: Ensure that you specify
aqjms/XAQueueConnectionFactory for local JNDI name if you
are connecting to a queue with JNDI name eis/aqjms/Queue that is
provided with the sample use case, AQQueuetoQueue.
Else, specify aqjms/XATopicConnectionFactory if you are
connecting to a topic with JNDI name eis/aqjms/Topic.

3. In the Local JNDI Name field, enter the local JNDI name you would use in your
application to look up this destination.
4. In the Remote JNDI Name field, enter Queues/<queue name>if the destination
is a queue, or enter Topics/<topic name> if the destination is a topic.
5. Click OK.
6. Restart the Oracle WebLogic Server Administration Console.
You have configured AQJMS in an Oracle WebLogic Server.
8.4.7.1.2 Creating Queues in Oracle Database
To create queues:
1. Run the setup_user.sql script.
2. Run the createqueues.sql script.
These scripts are available at:
8.4.7.2 Create an Application Server Connection
you want to deploy to. Perform the steps mentioned in Section 2.16, "Creating an
Application Server Connection for Oracle JCA Adapters" to create an application
server connection.
Application - Name your Application dialog is displayed.
AQQueue2Queue.
5. Click Next.
The Name your project page is displayed.
6. In the Project Name field, enter a descriptive name. For example,
AQQueue2Queue.
8. Click Next. The Create Generic Application - Configure SOA Settings page is
displayed.
Finish.
You have created a new application and an SOA project.
10. Enter a name for the BPEL process in the Name field.

The AQQueue2Queue application, the AQQueue2Queue project, and the SOA
composite appear in the design area.
12. Copy the expense.xsd file from the following location to the XSD folder in your
project:
Perform the following steps to create an adapter service to dequeue the message to a
queue:
Services swim lane in the composite.xml page. The Adapter Configuration Wizard
Welcome page is displayed.
3. Enter Inbound in the Service Name field, and click OK. The JMS Provider page is
displayed.
4. Select Oracle Advanced Queueing in the Oracle Enterprise Messaging Service
(OEMS) box, and click Next. The Service Connection page is displayed.
Connection."
8. Select Consume Message, and click Next. The Consume Operation Parameters
page is displayed.
9. Click Browse and select testInQueue in the Destination field.
12. Select Project Schema Files, expense.xsd.
13. Click Next. The expenses.xsd schema file is displayed in the URL field in the
Messages page.
15. Click Finish. You have configured a JMS inbound adapter service.
Perform the following steps to create an adapter service that will enqueue the request
1. Drag and drop JMS Adapter from the Component Palette into the Exposed
Services swim lane. The Adapter Configuration Wizard Welcome page is
displayed.

3. Enter Outbound in the Service Name field, and click OK. The JMS Provider page
is displayed.
4. Select Oracle Advanced Queueing in the Oracle Enterprise Messaging Service
(OEMS) box, and click Next. The Service Connection page is displayed.
Connection," and click Next. The Adapter Interface page is displayed.
7. Select Produce Message, and click Next. The Produce Operation Parameters page
is displayed.
8. Click Browse and select testOutQueue in the Destination field. The Produce
Operation Parameters page is displayed.
11. Select Project Schema Files, expense.xsd.
12. Click Next. The expense.xsd schema file is displayed in the URL field in the
Message dialog.
14. Click Finish. You have configured the JMS adapter service, and the composite.xml
page is displayed.
You must wire the three components that you have created: Inbound adapter service,
BPEL process, and Outbound adapter reference. Perform the following steps to wire
the components together:
1. Drag the small triangle in the inbound Oracle JMS Adapter component in the
Exposed Services area to the drop zone that appears as a green triangle in the
BPEL process in the Components area.
zone that appears as a green triangle in the outbound Oracle JMS Adapter in the
The Oracle JDeveloper Composite.xml is displayed, as shown in Figure 8–25.

Figure 8–25 Oracle JDeveloper - Composite.xml
4. Double-click the BPEL process. The BPELProcess1.bpel page is displayed.
5. Drag and drop the Receive, Assign, and Invoke activities, in the order mentioned,
from the Component Palette to the Components area.
6. Double-click the Receive activity.
8. Select Inbound, and then click OK.
value Outbound.
field. The Create Variable dialog is displayed.
11. Check the Create Instance box.
12. Double-click the Invoke activity to Outbound.
15. Select Outbound, and then click OK.

value Outbound.
17. Click OK.
19. Click the plus icon, and select Copy Operation.
The Create Copy Operation dialog is displayed.
20. Select the variables, and click OK.
created in the preceding steps. To deploy the application profile by using Oracle
Adapters."
following steps:
deployed is displayed in the Applications Navigation tree.
2. In the Last 5 Instances pane, there is an entry of a new instance. This is the instance
that was triggered when you enqueued a message by using
AQQueue2Queue.java.
4. Click the TextMessage component instance. The Audit page is displayed.
Note: When using Oracle JMS Adapter to dequeue from AQ JMS
Topics with durable subscriptions, if you notice that the dequeue
operation exhibits slow performance, then you can speed up the entire
performance by using multiple inbound threads for each adapter
service.
Oracle JMS Adapter allows multiple inbound threads if you specify an
endpoint property adapter.jms.receive.threads.
However, note that this workaround is not applicable when using
non-durable subscriptions because doing so will result in duplicate
messages.

8.4.8 Accessing Queues and Topics Created in 11g from the OC4J 10.1.3.4 Server
This section describes the procedure for accessing queues and topics you created in
Oracle Application Server 11g from OC4J 10.1.3.4. To do this, you must configure
Oracle BPEL Process Manager JMS adapter with Oracle WebLogic Server.
The following are the steps to configure Oracle BPEL Process Manager JMS adapter
with Oracle WebLogic Server:
1. Create the wlfullclient.jar file using the following steps:
a. Change to the server/lib directory, as shown in the following example:
cd WL_HOME/server/lib
b. Use the following command to create the wlfullclient.jar file in the
server/lib directory:
java -jar ../../../modules/com.bea.core.jarbuilder_X.X.X.X.jar
where X.X.X.X is the version number of the jarbuilder module in the WL_
HOME/server/lib directory. For example:
java -jar ../../../modules/com.bea.core.jarbuilder_1.0.1.0.jar
2. Copy the wlfullclient.jar file to the 10.1.3.4. server at the following location:
<ORACLEAS_HOME>/j2ee/<OC4J_INSTANCE>/connectors/JmsAdapter/JmsAdapter
3. Configure the connector factory setting in the oc4j-ra.xml file, as shown in the
following example:
<connector-factory location="eis/wlsjms/Queue" connector-name="Jms Adapter">
value="weblogic.jms.ConnectionFactory"/>
value="java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory;java.n
aming.provider.url=t3://w3.us.oracle.com:
7001;java.naming.security.principal=weblogic;java.naming.security.credentials=
weblogic"/>
<config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE"/>
<config-property name="isTopic" value="false"/>
<config-property name="isTransacted" value="false"/>
<config-property name="username" value=""/>
<config-property name="password" value=""/>
<connection-pooling use="none">
</connection-pooling>
<security-config use="none">
</security-config>
</connector-factory>
4. Modify the server.xml file of the 10.1.3.4 server to include the
environment-naming-url-factory-enabled="true" property, as shown
in the following example:
Note: The isTransacted configuration property value must
typically be set to FALSE. Currently, XA integration with WebLogic
JMS is not supported unless the adapter is deployed on Oracle
WebLogic Server.

<application-server
...
...
environment-naming-url-factory-enabled="true"
...
>
5. Restart the 10.1.3.4 server to make the changes come into effect.

9
Oracle JCA Adapter for Database 9-1
9Oracle JCA Adapter for Database
This chapter describes the Oracle JCA Adapter for Database (Oracle Database
Adapter), which works in conjunction with Oracle BPEL Process Manager and Oracle
Mediator. This chapter also includes support for stored procedures and functions (for
Oracle databases only). In addition, it contains references to use cases for the Oracle
Database Adapter and for stored procedures.
■ Section 9.1, "Introduction to the Oracle Database Adapter"
■ Section 9.2, "Complete Walkthrough of the Adapter Configuration Wizard"
■ Section 9.3, "Oracle Database Adapter Features"
■ Section 9.4, "Oracle Database Adapter Concepts"
■ Section 9.5, "Deployment"
■ Section 9.6, "Third Party JDBC Driver and Database Connection Configuration"
■ Section 9.7, "Stored Procedure and Function Support"
■ Section 9.8, "Oracle Database Adapter Use Cases"
9.1 Introduction to the Oracle Database Adapter
The Oracle Database Adapter enables a BPEL process to communicate with Oracle
databases or third party databases through JDBC. The Oracle Database Adapter
service is defined within a BPEL process partner link by using the Adapter
Configuration Wizard of Oracle BPEL Process Manager.
■ Section 9.1.1, "Oracle Database Adapter Features"
■ Section 9.1.2, "Design Overview"
9.1.1 Oracle Database Adapter Features
The Oracle Database Adapter enables Oracle SOA Suite and Oracle Fusion
Middleware to communicate with database end points. These include Oracle database
servers and any relational databases that comply with ANSI SQL and provide JDBC
drivers. For non-relational and legacy systems (with a few exceptions such as DB2 on
AS/400), application and mainframe adapters are available.
For more information about application and mainframe adapters, see Chapter 1,
"Introduction to Oracle JCA Adapters."

Introduction to the Oracle Database Adapter
To access an existing relational schema, you must create a new application and an SOA
project to use the Adapter Configuration Wizard to perform the following:
■ Import a relational schema (one or more related tables) and map it as an XML
schema (XSD)
For more information, see Section 9.4.1, "Relational-to-XML Mapping."
■ Abstract SQL operations such as SELECT, INSERT, and UPDATE as Web services
For more information, see Section 9.4.2, "SQL Operations as Web Services."
■ Have database events initiate an Oracle Fusion Middleware process.
The principle of the tables and views in the Oracle Database Adapter is to expose to
SOA tables and SQL as transparently and non-intrusively as possible. From an
integration standpoint, tables and SQL are what relational database products have in
common, so a generic solution focused on what is standard has the greatest reach. In
exposing databases to SOA, it is also about combining the technologies of SQL and
XML, the former an ideal language for querying information, the latter an ideal format
for transporting and representing information.
The more specialized AQ Adapter is for Oracle Advanced queues and is a separate
adapter. Stored procedure support is less standard across databases and a sub guide is
presented here.
The Oracle Database Adapter is a JCA 1.5 connector, which runs on the Oracle
Application Server. It relies on an underlying JDBC connector/driver to enact the
database communication. In contrast to JDBC, it is non-programmatic. The interaction
(series of SELECT, UPDATE, INSERT) is loosely modeled using the Adapter
Configuration Wizard. The inputs/outputs are XML, most easily seen as input
parameters and result sets converted to XML. These XML inputs and outputs allow
the Oracle Database Adapter services to be plugged into Oracle Fusion Middleware.
The Oracle Database Adapter can currently be used only within the context of an SOA
process.
9.1.1.1 Oracle Database Adapter Integration with Oracle BPEL Process Manager
When the Oracle Database Adapter is used to poll for database events (usually an
INSERT operation on an input table) and initiate a process, in a Mediator component
or an SOA composite it is called an exposed service. In Oracle BPEL process it is a
partner link tied to a Receive activity. The expression inbound (from database into
SOA) is commonly used.
When the Oracle Database Adapter is used to invoke a one-time DML statement such
as INSERT or SELECT, in a Mediator component or an SOA composite, it is called a
service reference. In Oracle BPEL process, it is a partner link tied to an Invoke activity.
The expression outbound (from SOA out to the database) is used.
9.1.2 Design Overview
Figure 9–1 shows how the Oracle Database Adapter interacts with the various
design-time and deployment artifacts.

Introduction to the Oracle Database Adapter
Figure 9–1 How the Oracle Database Adapter Works
The Oracle Database Adapter is a JCA 1.5 connector, which is deployed to the
application server during installation.
The Oracle Database Adapter consists of multiple instances; each instance represents a
connection to a database end point. Different SOA processes may point to the same
adapter instance (database), while different service endpoints in a SOA process may
point to different adapter instances (databases).
Because each adapter instance points to a single database, there is a one-to-one
correspondence from adapter instances to application server data sources. Out of the
box there is a single Oracle Database Adapter instance named eis/DB/SOADemo,
which points to the data source jdbc/SOADataSource.
The list of adapter instances is stored in a deployment descriptor file,
weblogic-ra.xml on Oracle WebLogic Server. (It is inside of DbAdapter.rar,
which contains also the Java class files in DBAdapter.jar). Configuring an Oracle
Database Adapter instance is more about creating the underlying data source: getting
the correct JDBC driver and connection URL.
For more information, see Section 9.6, "Third Party JDBC Driver and Database
Connection Configuration."
However weblogic-ra.xml entries occasionally have more than simply the name of
the underlying data source. These properties are detailed further under Deployment.
While at run time you have Oracle Database Adapter instances, at design time you
have the Adapter Configuration Wizard (link). You can run it once to generate a single
adapter service end point, and then multiple times in edit mode to make incremental
changes to each. It generates all the adapter related artifacts needed when deploying a
SOA composite. These files are:
JCA
Binding
Component
Data Source
Database
SCA
Runtime
JDeveloper
SOA
Studio
.properties
Application Server
JCA
JNDI MyDBConnection1
eis/DB/SOADemo
Fabric
or_mappings.xml
· WSDL
· _db.JCA
· XSD
Deployment
weblogic-ra.xml
DBAdapter
composite.xml
Adapter
Configuration
Wizard
SOA
sessions.xml
jdbc/SOADemo
JDBC

Complete Walkthrough of the Adapter Configuration Wizard
■ <serviceName>.wsdl
■ <serviceName>_table.xsd
■ <serviceName>_or-mappings.xml
■ <serviceName>_db.jca
■ <serviceName>.properties
<serviceName>.wsdl
This is an abstract WSDL, which defines the service end point in terms of the name of
the operations and the input and output XML elements.
<serviceName>_table.xsd
This contains the XML file schema for these input and output XML elements. Both
these files form the interface to the rest of the SOA project.
<serviceName>_db.jca
This contains the internal implementation details of the abstract WSDL. It has two
main sections, location and operations. Location is the JNDI name of an adapter
instance, that is, eis/DB/SOADemo. Operations describe the action to take against that
end point, such as INSERT, UPDATE, SELECT, and POLL. The contents of the db.jca
file are wholly determined by choices made while running the Adapter Configuration
Wizard.
<serviceName>_or-mappings.xml
This is an internal file. It is a TopLink specific file, which is used to describe the
mapping between a relational schema and the XML schema. It is used at run time.
<seviceName>.properties
This is also an internal file. It is created when tables are imported, and information
about them is saved. It is used only at design time.
At run time, the location is used to look up the adapter instance which executes the
service. Based on the properties in the db.jca file and the linked or-mappings.xml
file, <seviceName>.properties file generates the correct SQL to execute, parses
the input XML, and builds an output XML file matching the XSD file. To execute the
SQL, it obtains a pooled SQL connection from the underlying data source.
9.2 Complete Walkthrough of the Adapter Configuration Wizard
This section describes the Adapter Configuration Wizard and how you can define an
Oracle Database Adapter by using the Adapter Configuration Wizard.
This section describes the various Oracle Database Adapter concepts through a use
case, which is, a complete walkthrough of the Adapter Configuration Wizard. In
addition, this use case also describes how by using the Adapter Configuration Wizard,
you can import tables from the database, specify relationships spanning multiple
tables, generate corresponding XML schema definitions, and create services to expose
the necessary SQL or database operations. These services are consumed to define
partner links that are used in the BPEL process. You use the Adapter Configuration
Wizard to both create and edit adapter services.
■ Section 9.2.1, "Creating an Application and an SOA Project"
■ Section 9.2.2, "Defining an Oracle Database Adapter"

■ Section 9.2.3, "Connecting to a Database"
■ Section 9.2.4, "Selecting the Operation Type"
■ Section 9.2.5, "Selecting and Importing Tables"
■ Section 9.2.6, "Defining Primary Keys"
■ Section 9.2.7, "Creating Relationships"
■ Section 9.2.8, "Creating the Attribute Filter"
■ Section 9.2.9, "Defining a WHERE Clause"
■ Section 9.2.10, "Choosing an After-Read Strategy"
■ Section 9.2.11, "Specifying Polling Options"
■ Section 9.2.12, "Specifying Advanced Options"
■ Section 9.2.13, "Entering the SQL String for the Pure SQL Operation"
9.2.1 Creating an Application and an SOA Project
You must create an Oracle JDeveloper application to contain the SOA composite.
Perform the following steps to create a new application, and an SOA project:
The Create Generic Application - Name your application page is displayed, as
3. Enter a name for the application in the Application Name field.
Figure 9–2 The Create Generic Application - Name your application Page
5. Click Next.

The Create Generic Application - Name your project page is displayed, as shown
in Figure 9–3.
6. In the Project Name field, enter a descriptive name.
Figure 9–3 The Create Generic Application - Name your Generic project Page
Figure 9–4 The Create Generic Application - Configure SOA settings Page

Finish.
an SOA composite.
10. Enter a name for the BPEL process in the Name field.
9.2.2 Defining an Oracle Database Adapter
The next step is to define an Oracle Database Adapter service. Perform the following
steps to create an Oracle Database Adapter service:
2. Drag and drop Database Adapter from the Service Adapters list to the Exposed
components swim lane in the composite.xml page.
3. Click Next. The Service Name page is displayed, as shown in Figure 9–6. Enter the
following information:
Note: To create an Oracle Database Adapter service as part of a BPEL
process, drag and drop a BPEL process from Service Components onto
Components. Double-click it. Then, in the BPEL Component Palette,
drag and drop Database Adapter from BPEL Services onto one of the
Partner Links swim lanes.

Figure 9–6 Specifying the Service Name
4. In the Service Name field, enter a service name, and then click Next. The Service
Connection page is displayed.
See Section 9.2.3, "Connecting to a Database" to continue using the Adapter
Configuration Wizard.
9.2.3 Connecting to a Database
Figure 9–7 shows where you select the database connection that you are using with the
service. This is the database from which you import tables to configure the service.
This is the database from which you import tables to configure the service. You may
need to re-create it here in each new Oracle JDeveloper application you create.
You can provide a Java Naming and Directory Interface (JNDI) name to identify the
database connection, as the default name that is provided is
eis/DB/<ConnectionNameInJDev>.
For more information, see Section 9.5, "Deployment."

Figure 9–7 Adapter Configuration Wizard: Service Connection Page
Note the following:
■ In production environments, it is recommended that you add the JNDI entry to the
adapter deployment descriptor (weblogic-ra.xml). This way, the Oracle
Database Adapter is more performant by working in a managed mode.
For information about creating a data source and an outbound connection pool,
see Section 2.4, "Adding an Adapter Connection Factory."
■ When you click Next, a connection to the database is attempted. If a connection
cannot be made, you will not be able to proceed to the next window, even if you
are editing an existing partner link.
See Section 9.2.4, "Selecting the Operation Type" to continue using the Adapter
9.2.4 Selecting the Operation Type
Figure 9–8 shows where you indicate the type of operation you want to configure for
this service.

Figure 9–8 Adapter Configuration Wizard: Operation Type Page
The following operation types are available:
■ Call a Stored Procedure or Function
Select this option if you want the service to execute a stored procedure or function.
For more information, see Section 9.7, "Stored Procedure and Function Support."
■ Perform an Operation on a Table
Select this option for outbound operations. You can select Insert or Update, Insert
Only, Update Only, Delete, Select, or any combination of the six. These
operations loosely translate to SQL MERGE, INSERT, UPDATE, DELETE, and
SELECT operations.
For more information, see Section 9.4.2.1, "DML Operations."
■ Poll for New or Changed Records in a Table
Select this option for an inbound operation (that is, an operation that is associated
with a Receive activity). This operation type polls a specified table and returns for
processing any new rows that are added. You can also specify the polling
frequency.
For more information, see Section 9.4.2.2, "Polling Strategies."
The following is a list of polling operations that you can perform after the data is
read from the database, as shown in Figure 9–9:
– Delete the Row(s) that were Read
Note: The operation Update Only sometimes performs
inserts/deletes for child records. That is, an update to Master could
involve a new or deleted detail. So if the input to update contains only
one record, then the other records in the table are deleted.

– Update a Field in the [Table_Name] Table (Logical Delete)
– Update a Sequencing Table
– Update an External Sequencing Table on a Different Database
– Control Table Strategy
Figure 9–9 Polling Operations
■ Execute Pure SQL
Useful when dealing with arbitrarily complex statements, aggregate queries
(result is not row-based), and XMLType columns. See Section 9.3.2, "Pure SQL -
XML Type Support" to follow this usage of the Adapter Configuration Wizard.
Otherwise, see Section 9.2.5, "Selecting and Importing Tables" to continue using the
Adapter Configuration Wizard.
9.2.5 Selecting and Importing Tables
Figure 9–10 shows where you select the root database table for your operation. If you
are using multiple related tables, then this is the highest-level table (or highest parent
table) in the relationship tree.
Note: Schema Bound XML tables are not supported.

Figure 9–10 Adapter Configuration Wizard: Select Table
Selecting Import Tables launches a sub-wizard, which lets you search for and select
multiple tables to import from the database. Removing a table removes (or undoes)
any relationships on related tables that remain. If any underlying tables have changed
when running this wizard in edit mode, you get a warning showing you what changes
have occurred. To reconcile, import the tables again. Note that if you click Import
Tables and select multiple tables, then relationships between these tables are inferred
based on the foreign key constraints. However if you launch Import Tables once for
each table imported, then no relationships are inferred.
See Section 9.2.6, "Defining Primary Keys" to continue using the Adapter
9.2.6 Defining Primary Keys
If any of the tables you have imported do not have primary keys defined on the
database, you are prompted to provide a primary key for each one, as shown in
Figure 9–11. You must specify a primary key for all imported tables. You can select
multiple fields to specify a multipart primary key.
Note: If you reimport a table, you lose any custom relationships you
may have defined on that table as well as any custom WHERE clauses
(if the table being imported was the root table).

Figure 9–11 The Adapter Configuration Wizard: Define Primary Keys Page
The primary key that you specify here is recorded on the offline database table and is
not persisted back to the database schema; the database schema is left untouched.
See Section 9.2.7, "Creating Relationships" to continue using the Adapter
9.2.7 Creating Relationships
Figure 9–12 shows the relationships defined on the root database table and any other
related tables. You can click Create Relationships… to create a new relationship
between two tables, or click Remove Relationship to remove it. To rename a
relationship, click Rename Relationship.
Note: Note that Oracle Database Adapter only supports tables where
there is a primary key defined. If primary key constraints have not
been defined on a table explicitly, then you must provide one at
design time while defining the Oracle Database Adapter by using the
Adapter Configuration Wizard. If you do not provide a valid primary
key, then the unique constraint is not guaranteed, and this could result
in possible loss of messages at run time. That is, rows with duplicate
primary key values are likely to be lost.
The following sample describes how to use the row id field as
primary key:

Figure 9–12 The Adapter Configuration Wizard: Relationships Page
Note the following regarding creating relationships:
■ If foreign key constraints between tables already exist on the database, then two
relationships are created automatically when you import the tables, a one-to-one
(1:1) from the source table (the table containing the foreign key constraints) to the
target table, and a one-to-many (1:M) from the target table to the source table.
■ As Figure 9–12 shows, you see only the relationships that are reachable from the
root database table. If, after removing a relationship, other relationships are no
longer reachable from the root table, then they are not shown in the Relationships
window. Consider the following set of relationships:
A --1:1--> B --1:1--> C --1:M--> D --1:1--> E --1:M--> F
(1) (2) (3) (4) (5)
If you remove relationship 3, then you see only:
A --1:1--> B
B --1:1--> C
If you remove relationship 2, then you see only:
A --1:1--> B
If you remove relationship 1, you no longer see any relationships.
Figure 9–13 shows where you can create a new relationship.

Figure 9–13 The Create Relationship Dialog
To create a new relationship:
1. Select the parent and child tables.
2. Select the mapping type (one-to-many, one-to-one, or one-to-one with the foreign
key on the child table).
3. Associate the foreign key fields to the primary key fields.
4. Optionally name the relationship (a default name is generated).
9.2.7.1 What Happens When Relationships Are Created or Removed
When tables are initially imported into the Adapter Configuration Wizard, a TopLink
direct-to-field mapping corresponding to each field in the database is created.
Consider the schemas shown in Figure 9–14 and Figure 9–15:
Figure 9–14 EMPLOYEE Schema
Figure 9–15 ADDRESS Schema
Immediately after importing these two tables, the following mappings in the
Employee descriptor are created:
Employee:
Note: Only tables that are reachable from the root table can be
selected as a parent.

■ id (direct mapping to the ID field, for example, 151)
■ name (direct mapping to the NAME field, for example, Stephen King)
■ addrId (direct mapping to the ADDR_ID field, for example, 345)
When creating a relationship mapping, the direct-to-field mappings to the foreign key
fields are removed and replaced with a single relationship (one-to-one, one-to-many)
mapping. Therefore, after creating a one-to-one relationship between Employee and
Address called homeAddress, the Employee descriptor appears, as shown in the
following example:
Employee:
■ id
■ name
■ homeAddress (one-to-one mapping to the ADDRESS table; this attribute now
represents the entire Address object.)
When a relationship is removed, the direct mappings for the foreign keys are restored.
9.2.7.2 Different Types of One-to-One Mappings
When relationships are auto created, the one-to-many relationship is from the table
without the foreign key. However, you can declare this mapping, which is technically
1-many, as a 1-1. For that, choose 1-1 (foreign key on target).
9.2.7.3 When Foreign Keys Are Primary Keys
Not all tables imported are in the third normal form (3NF). In rare cases, you may have
two or more tables which share the same primary key but no separate foreign key
columns exist. It is recommended to create 1-1 (foreign key on target) relationships
from the root table to all related tables. The reason is two fold. First, if you were to
declare the primary key on the root as a foreign key (1-1, foreign key on source), then
that mapping would be removed, so you would not see the primary key in the root
record, only in the child record. Second, a foreign key can only point to a single table.
Once you declare a column to be part of a foreign key, it is removed, so it cannot be
used again in a new relationship. Creating a 1-1 (foreign key on source) on the root
table not only makes the primary key column disappear but prevents you from joining
the root table to the remaining tables.
9.2.8 Creating the Attribute Filter
Figure 9–16 shows the attribute filter that is created from the imported table
definitions, including any relationships that you may have defined.

Figure 9–16 The Adapter Configuration Wizard: Attribute Filtering Page
If your object filter contains self-relationships (for example, the employee-to-employee
manager relationship), then you see these as loops in the tree. These loops are not
present in the XSD file. This is the descriptor object model, not the XSD file.
In this page, you select those columns that will appear in the XML file, whether for
input (MERGE, INSERT) or output (SELECT). Columns you are not interested in or
which are to be read-only (should not be modified) can be deselected here.
See Section 9.2.9, "Defining a WHERE Clause" to continue using the Adapter
9.2.9 Defining a WHERE Clause
If your service contains a SELECT query (that is, inbound polling services, or
outbound services that contain a SELECT), then you can customize the WHERE clause
of the SELECT statement.
Figure 9–17 shows where you define a WHERE clause for an outbound service.
Note: Incase of polling with Sequencing Table/Update an
External Sequencing Table, ensure that the name of the table in
the SELECT query matches the case of the data in the sequencing
table.

Figure 9–17 The Adapter Configuration Wizard: Define Selection Criteria Page
The most basic expression in a WHERE clause can be one of the following three cases,
depending on what the right-hand side (RHS) is:
1. EMP.ID = 123
In this case, the RHS is a literal value. This RHS is the Literal option shown in
Figure 9–18.
2. EMP.ADDR_ID = ADDR.ID
In this case, the RHS is another database field. This RHS is the Query Key option
3. EMP.ID = ?
In this case, the RHS value must be specified at run time. This is the Parameter
option shown in Figure 9–18.
You can create the parameters that you need in the WHERE clause by clicking Add
before you move on to build the WHERE clause. To build the WHERE clause, click Edit…
to launch the Expression Builder, as shown in Figure 9–18.
Note: The WHERE clause applies to SELECT operations only (that is,
polling for new or changed records or performing a SELECT operation
on a table). It does not apply to INSERT, UPDATE, and DELETE
operations.

Figure 9–18 Expression Builder
To model more complex WHERE clauses (sub selects and functions), and to add ORDER
BY clauses, you can edit the SQL procedure manually and click Next. However, this
creates maintenance overhead later on, due to hard-coded SQL, and you may lose
platform independence.
You can change the columns listed in the FROM clause as long as the number of
columns and the types of each remain unchanged. For more complex changes consider
using the Execute Pure SQL option directly where you can type any SQL.
Return Single Result Set
You must select Use Outer Joins to return a Single Result Set for both Master and
Detail Tables in the Define Selection Criteria page to use an advanced feature that
influences how many total statements TopLink uses when querying against multiple
related tables. The safest method is to use the default (1 per table), and this feature will
attempt 1 total, by outer joining all related tables into a single result set.
See Section 9.2.10, "Choosing an After-Read Strategy" to continue using the Adapter
9.2.10 Choosing an After-Read Strategy
If you selected Perform an Operation on a Table, then you can skip ahead to the
Section 9.2.12, "Specifying Advanced Options.".
When configuring an inbound operation, you have the following options about what
to do after a row or rows have been read:
■ Section 9.2.10.1, "Delete the Rows That Were Read"
■ Section 9.2.10.2, "Update a Field in the Table (Logical Delete)"
■ Section 9.2.10.3, "Update a Sequencing Table"
■ Section 9.2.10.4, "Update an External Sequencing Table on a Different Database"
■ Section 9.2.10.5, "Update a Sequencing File"

Figure 9–19 shows these options.
Figure 9–19 The Adapter Configuration Wizard: After Read Page
See Section 9.4.2.2, "Polling Strategies" to continue using the Wizard.
9.2.10.1 Delete the Rows That Were Read
With this option, the rows are deleted from the database after they have been read and
processed by the adapter service.
9.2.10.2 Update a Field in the Table (Logical Delete)
With this option, you update a field in the root database table to indicate that the rows
have been read. The WHERE clause of the query is updated automatically after you
complete the configuration, as shown in Figure 9–20.

Figure 9–20 The Adapter Configuration Wizard: Logical Delete Page
When you use this approach, your database table appears, as shown in Figure 9–21.
Figure 9–21 Updating Fields in a Table
Note the following:
■ Rows 150 and 153 have been previously read and processed.
■ At the next polling event, row 152 is read and processed because it contains
UNPROCESSED in the Status column. Because an explicit Unread Value was
provided, row 151 is not read.
■ Row 154 has been flagged as LOCKED and is not read. You can use this reserved
value if your table is used by other processes.
9.2.10.3 Update a Sequencing Table
With this option, you are keeping track of the last-read rows in a separate sequence
table. Figure 9–22 shows the information you provide. The WHERE clause of your query
is updated automatically after you complete the configuration.

Figure 9–22 The Adapter Configuration Wizard: Sequencing Table Page
When you use these settings, your sequence table appears, as shown in Figure 9–23.
Figure 9–23 Updating a Sequence Table
Whenever a row is read, this table is updated with the ID that was just read. Then,
when the next polling event occurs, it searches for rows that have an ID greater than
the last-read ID (154).
Typical columns used are event_id, transaction_id, scn (system change
number), id, or last_updated. These columns typically have (monotonically)
increasing values, populated from a sequence number or sysdate.
9.2.10.4 Update an External Sequencing Table on a Different Database
Choose this operation to employ the sequencing table: last updated strategy.
Figure 9–24 shows the Adapter Configuration Wizard - External Sequencing Table
page in which you specify the details required to perform this operation.

Figure 9–24 Adapter Configuration Wizard - External Sequencing Table page
9.2.10.5 Update a Sequencing File
Use this option to update a sequencing file. Figure 9–25 shows the Adapter
Configuration Wizard - Update a Sequencing File page where you specify the details
for performing this operation.
Figure 9–25 Adapter Configuration Wizard - Update a Sequencing File Page

9.2.11 Specifying Polling Options
You can specify additional polling options, if any, in this page. Figure 9–26 shows the
Adapter Configuration Wizard - Polling Options page.
Figure 9–26 Specifying Polling Options
In this page, you specify details about how to poll the database table for new rows or
events.
From the Polling Frequency list, select how frequently to poll for new records or
events.
In the Database Rows per XML Document field, specify the number of rows per XML
document when sending events to Oracle BPEL Process Manager or Oracle Mediator.
This is the batch setting between the database adapter and its consumer: Oracle BPEL
Process Manager or Oracle Mediator.
In the Database Rows per Transaction field, select Unlimited or enter a value to
indicate the number of table rows to process during a single transaction.
When polling the database for events, you can order the returned rows by the selected
column by using the Order By list. The best practice is to choose <No Ordering>, as
message ordering regardless is not guaranteed without extra configuration.
In the SQL field, if the SQL syntax is incorrect, then a message is displayed in red.
For more information about specifying polling options, click Help in the Polling
Options page or press F1.
9.2.12 Specifying Advanced Options
You can specify advanced options, if any. Figure 9–27 shows the Adapter
Configuration Wizard - Advanced Options page. In this page, you can specify
advanced JDBC and DBAdapter options, configure retries, and configure native
sequencing.

Figure 9–27 Specifying Advanced Options
You must specify JDBC options in the JDBC Options section. Set low-level JDBC
options on calls to the database. The operation you selected determines which options
may appear here.
In the Auto-Retries section, specify the value for auto-retry incase of time out. In case
of a connection related fault, the Invoke activity can be automatically retried a limited
number of times. You can specify the following values in the fields in this section:
■ To retry indefinitely, type unlimited in the Attempts field.
■ Interval is the delay between retries.
■ Backoff Factor: x allows you to wait for increasing periods of time between retries.
9 attempts with a starting interval of 1 and a back off of 2 will lead to retries after
1, 2, 4, 8, 16, 32, 64, 128, and 256 (28
) seconds.
In the Interaction Options, specify the interaction options, as follows:
■ GetActiveUnitOfWork is an advanced setting that forces all invoke activities in
the same global transaction to use the same SQL connection if going to the same
database. This makes it easier to guarantee that later invoke activities can see the
changes of earlier invoke activities, but you may not need to set this at all (if using
emulated two-phase commit, it should automatically be the same connection).
Another difference is that for MERGE and INSERT, all changes are not written until
the global transaction commits, so this setting also changes the timing of when
WRITE operations occur.
■ Detect Omissions allows the MERGE and INSERT operations to ignore empty or
missing XML elements in the input payload. For a MERGE operation, this will
prevent valid but unspecified values from being overwritten with NULL. For
INSERT operations, they will be omitted from the INSERT statement, allowing
default values to take effect.
■ Optimize Merge should always be set to true, as it is a general enhancement to
MERGE performance (using an in query for the primary key existence check).

Oracle Database Adapter Features
Native Sequencing (Oracle only) allows you to specify that the primary key will be
assigned from a sequence on any insert. Click Search and then select a sequence from
the Sequence list, or type the name and click Create.
For more information about specifying advanced options, click Help in the Advanced
Options page or press F1.
9.2.13 Entering the SQL String for the Pure SQL Operation
You can enter a SQL string for performing the Execute Pure SQL operation in the
Custom SQL page. Figure 9–28 shows the Adapter Configuration Wizard - Custom
SQL page.
Figure 9–28 Entering a SQL String
In the SQL field, enter a custom SQL string. An XSD schema of your SQL input is
automatically created in the XSD field.
The XSD field displays the XSD schema of the custom SQL string you entered. You
can directly edit the resulting XSD. However, if you make subsequent changes to the
SQL string, then your XSD changes are lost.
For more information about entering a SQL string, click Help in the Custom SQL page
or press F1.
9.3 Oracle Database Adapter Features
This section discusses the Oracle Database Adapter features.

It includes the following topics:
■ Section 9.3.1, "Transaction Support"
■ Section 9.3.2, "Pure SQL - XML Type Support"
■ Section 9.3.3, "Proxy Authentication Support"
■ Section 9.3.4, "Streaming Large Payload"
■ Section 9.3.5, "Schema Validation"
■ Section 9.3.6, "High Availability"
■ Section 9.3.7, "Scalability"
■ Section 9.3.8, "Performance Tuning"
■ Section 9.3.9, "detectOmissions Feature"
■ Section 9.3.10, "OutputCompletedXml Feature"
■ Section 9.3.11, "QueryTimeout for Inbound and Outbound Transactions"
■ Section 9.3.12, "Doing Synchronous Post to BPEL (Allow In-Order Delivery)"
9.3.1 Transaction Support
The Oracle Database Adapter enables transaction support, which, along with the
inherent data processing, ensures that each modification has a clearly defined
outcome, resulting in either success or failure, thus preventing potential corruption of
data, executes independently from other changes, and, once completed, leaves
underlying data in the same state until another transaction takes place.
There are two types of transaction support, XA Transaction support and Local
Transaction support. XA transaction support allows a transaction to be managed by a
transaction manager external to a resource adapter, whereas, a local transaction
support allows an application server to manage resources that are local to the resource
adapter.
To ensure two Oracle Database Adapter invokes commit or rollback as a unit, you
need to perform the following:
■ Both Oracle Database Adapter invokes must be configured to participate in global
transactions.
■ Both Oracle Database Adapter invokes must participate in the same global
transaction.
■ The failure of either invoke must cause the global transaction to roll back.
The transaction support is demonstrated in the following tutorial files:
■ XAInsert
■ InsertWithCatch
■ DirectSQLPerformance
For the tutorial files, go to
Note: You must use a non-XA driver with the
SOALocalTxDataSource parameter. Switching to an XA driver
breaks product functionality.

9.3.1.1 Configuring Oracle Database Adapter for Global Transaction Participation
In the deployment descriptor (weblogic-ra.xml file), you must set the
xADataSourceName parameter. Additionally, the referenced DataSource must be
configured for transaction participation by creating a data source in Oracle WebLogic
Server Console.
You must create a data source and choose one of the XA data sources from the list.
For information about the recommended setting for non-XA and XA data sources used
by Oracle JCA Adapters, see Section 2.21, "Recommended Setting for Data Sources
Used by Oracle JCA Adapters."
Note that you cannot edit the data-sources.xml file in the Oracle WebLogic Server. You
must create a data source by using the Oracle WebLogic Server Administration
Console, as mentioned in Section 2.4.1, "Creating a Data Source."
9.3.1.2 Both Invokes in Same Global Transaction
Once both the Oracle Database Adapter invokes participate in global transactions, to
commit or rollback as a unit, they must be participating in the same global transaction.
In BPEL, this requires the understanding of where the transaction boundaries are, at
what points does a checkpoint have to write to the dehydration store, commit the
current global transaction, and start a new one.
The transaction boundaries in a BPEL process occur either before a Receive activity or
wait activity, or before an onMessage or pick activity. This may also occur when
invoking a synchronous child BPEL process, unless the bpel.config.transaction
property is set on the partnerlink, as shown in the following code sample.
<property name="bpel.config.transaction">required</property>
Otherwise, the parent process is broken into two transactions and the child process
runs in its own transaction.
9.3.1.3 Failure Must Cause Rollback
Finally, even if both Oracle Database Adapter invokes participate in the same global
transaction, the failure of either invoke may not cause the global transaction to
rollback.
The only cases where a failure can actually cause a global rollback are:
■ A Oracle Database Adapter operation that inserts/updates multiple tables as part
of one invoke fails after having succeeded in some writes but not others. In this
case, the Oracle Database Adapter marks the global transaction as rollback only,
because the invoke operation was not atomic and a commit could cause data
corruption.
■ The invoke retries multiple times in a database down scenario, until the global
transaction times out and is rolled back.
■ An explicit bpelx:rollback fault is thrown from within the BPEL process.
9.3.1.3.1 Using the Same Sessions for Both Invokes
Note: True Database XA is only certified on Oracle 10.2.0.4 or
11.1.0.7. For earlier versions, you will be safer picking a non-XA data
source implementation and selecting Emulated Two-phase commit on
the next page.

You must set the GetActiveUnitOfWork JCA parameter to true to enable using the
same sessions or connections for both the Oracle Database Adapter invokes.
GetActiveUnitOfWork is an advanced JCA property you can set on any
DBInteractionSpec. It causes the invoke to register itself with the two-phase
commit callbacks, and all writes to the database are performed as part of the
two-phase commit. By setting this property on any failure, the transaction is
automatically rolled back, as there is no way to handle a fault at this late stage.
Similarly, the same underlying TopLink session is used for both invokes, meaning if
you merge the same object twice, it is inserted/updated once. All merge invokes that
set GetActiveUnitOfWork as true are cumulative.
9.3.1.4 Transaction/XA Support
To make two Oracle Database Adapter invokes commit or roll back as a unit requires
the following: both Oracle Database Adapter invokes must be configured to
participate in global transactions, both invokes must participate in the same global
transaction, and the failure of either invoke must cause the global transaction to
rollback.
9.3.1.4.1 Configuring an Oracle Database Adapter for Global Transaction Participation
In the deployment descriptor (weblogic-ra.xml), you must set xADataSourceName.
The matching data source entry must be configured for global transaction
participation.
True XA: Two-Phase (XA) Versus One-Phase (Emulated) Commit
XA is a two-phase commit protocol, which is more robust than a one-phase commit or
emulated protocol. The difference is that with a one-phase protocol, you may very
rarely still see message loss or other rollback/commit inconsistency, on the order of
one per one thousand generally.
RAC Configuration
For more information about RAC configuration, see the Oracle Database High
Availability Overview guide.
True XA Configuration with Third Party Drivers
When configuring true XA for third party drivers (that is, Microsoft SQL Server, IBM
DB2), see if the driver jars contain a class that implements
javax.sql.XADataSource.
For data direct drivers, the naming happens to be
com.oracle.ias.jdbcx.db2.DB2DataSource, or
com.oracle.ias.jdbcx.sqlserver.SQLServerDataSource.
9.3.1.4.2 Failure Must Cause Rollback
Finally, even if both invokes participate in the same global transaction, the failure of
either invoke may not cause the global transaction to roll back.
The only cases where a failure can actually cause a global roll back are:
■ An Oracle Database Adapter operation that inserts/updates multiple tables as
part of one invoke fails after having succeeded in some writes but not others. In
this case, the adapter marks the global transaction rollback only, as the invoke
operation was not atomic and a commit could cause data corruption.

■ The invoke retries multiple times in a database down scenario, until the global
transaction times out and is rolled back.
■ An explicit bpelx:rollback fault is thrown from within the BPEL process.
GetActiveUnitOfWork="true" in WSDL.
9.3.2 Pure SQL - XML Type Support
Pure SQL Adapter is an option in the Oracle Database Adapter Wizard that allows you
to type the SQL string directly and have an XSD/Web service generated automatically.
The database tables are introspected dynamically in the Adapter Configuration Wizard
to test the SQL and populate the XSD file better (that is, with valid return types.)
The Pure SQL support allows the Oracle Database Adapter to deal with tables/views
as entities and for dealing directly with SQL. You can use Pure SQL:
■ for simple data projection style report queries
■ in cases where the result set is not table oriented, such as select count(*)
■ to perform an update or delete all
■ when working with XMLType columns and xquery
■ when using complex SQL, which are not modeled in the Adapter Configuration
Wizard expression builder
You can use the Pure SQL Adapter with Oracle XMLTypes. It is a natural fit for
inserting XML into XMLType tables and columns, and retrieving XML using xquery
selects. Pure SQL is a natural fit for the Oracle Database Adapter that provides a
relational-xml mapping that parallels XML DB(XDB) support. So, when using XDB the
adapter should be as lightweight and transparent as possible, to let you focus on XDB
and XQuery.
If your data is in XML (unstructured/semi-structured) format, and you have no
relational schema at all that you can map your data to, then you could use XDB. The
conventional Oracle Database Adapter allows you to import an existing relational
schema as an XML schema to be used with Web services. XDBs XML shredding
algorithm can generate a relational schema from an existing XML schema for
persistent storage.
9.3.3 Proxy Authentication Support
You can now connect to your Oracle data store by using Proxy Authentication. On a
per-invoke basis, you can set a combination of the following new header properties:
■ proxyUserName
■ proxyPassword
■ proxyRoles
■ proxyCertificate (base64Binary)
■ proxyDistinguishedName
Note: Use of schema bound XMLTypes requires the oci driver,
which is not certified in the 11g release. Therefore, you must use
non-schema bound XMLTypes at run time, though you can use
schema bound XMLTypes at design time to import a representative
XSD.

■ proxyIsThickDriver
To run the invoke, a proxy connection is obtained from the data source. Note that
proxyIsThickDriver must be configured and set to true if using the OCI driver, as
there is some discrepancy in the JDBC-level API between the thick and thin drivers.
9.3.4 Streaming Large Payload
To enable support to stream payload, you must select the Enable Streaming check box
while specifying polling options, as shown in Figure 9–26. When you enable this
feature, the payload is streamed to a database instead of getting manipulated in SOA
run time as in a memory DOM. You use this feature while handling large payloads.
When you select the Enable Streaming check box, a corresponding Boolean property
StreamPayload is appended to the ActivationSpec properties defined in the
respective .jca file.
9.3.5 Schema Validation
The SchemaValidation [false/true] property is a new activation specification
property that has been added, and this can be configured in a .jca file. When set to
true, all XML files produced by the polling Oracle Database Adapter (for Receive
activities) is validated against the XSD file. On failure, the XML record is rejected but
still marked as processed by the Oracle Database Adapter.
Databases provide structured storage and the XSD file is generated by the Oracle
Database Adapter Wizard itself. However, if you edit the auto generated XSD and add
your own restrictions, you may want to start validation. For instance, if you import a
VARCHAR(50) field, the auto-generated XSD has the max-length 50 restriction.
However, if your BPEL process for some reason can only handle values of fixed length
22, it may want to validate the XML file.
9.3.6 High Availability
The Oracle Database Adapter supports high availability in an active-active setup. In an
active-active setup, distributed polling techniques can be used for inbound Database
Adapters to ensure that the same data is not retrieved more than once. For more
information, see Section 9.3.7.1, "Distributed Polling Best Practice:
MarkReservedValue." Similar to other adapters, an Oracle Database Adapter can also
be configured for singleton behavior within an active-passive setup. This allows a high
performance multithreaded inbound Oracle Database Adapter instance running in an
active-passive setup, to follow a fan out pattern and invoke multiple composite
instances across a cluster. The Oracle Database Adapter also supports the high
availability feature when there is a database failure or restart. The DB adapter picks up
again without any message loss.
For information about how an inbound rejected message is handled by using fault
policy, see Section 2.10.2.2, "Inbound Interaction."
9.3.6.1 Surviving Database Restart
The Oracle Database Adapter can survive a database down scenario and pick up again
without any message loss.
The following are some possibilities of what may be wrong:
9.3.6.1.1 Oracle Database Adapter Gets Stuck on DataSource Closed Exceptions

After a database restart or fail-over, you may get into a cycle of continual
SQLExceptions such as DataSource has been disabled or connection has been
reset/closed. This is generally a data source configuration issue. Ensure that you
configure your data source to be robust in the event of exceptions, by using the
recommended setting for non-XA and XA data sources used by Oracle JCA Adapters.
For information about using recommended setting for non-XA and XA data sources
used by Oracle JCA Adapters, see Section 2.21, "Recommended Setting for Data
Sources Used by Oracle JCA Adapters."
9.3.6.1.2 Auto-Retrying Remote Faults
The Oracle Database Adapter is configured by default to retry a small number of times
in the event of a retryable exception on an outbound one-time invoke. It is configured
to retry indefinitely on a retryable fault on the inbound side. You can configure both of
these behaviors on the Adapter Configuration Wizard - Advanced Options page of the
Wizard.
For information about using the Advanced Options page, see Section 9.2.12,
"Specifying Advanced Options."
9.3.6.1.3 Exception Misclassification
Auto-retries can kick in only if a remote fault is thrown. If instead a binding fault is
thrown, then you may have an issue with exception misclassification. Do this only if
you can see that the wrong flavor of exception is being thrown.
First find out the error code of the SQLException being thrown. For example, if it is
17002, then it is the tns listener not available exception.
Then add the property nonRetriableSQLErrorCodes to weblogic-ra.xml. (You
must declare the property in ra.xml first.) The value is a space or comma separated list
that says what is certainly a binding fault or a remote fault. "1" says 1 is certainly a
binding fault. "+1 -17002" says 1 is certainly a binding fault and 17002 is certainly a
remote fault. Hence, if 17002 were accidentally being classified as a binding fault, then
"-17002" overrides that. Thus, ensure that it is always a remote fault.
9.3.6.1.4 Recoverable Instances
If you configure a set number of times to retry an instance in the event of a retriable
fault, then SOA will mark these instances as processed to allow other instance
processing to continue, once all retries are exhausted. These recoverable instances will
be stored to a database and can later be manually replayed from the Oracle Enterprise
Manager Console.
9.3.6.2 Undying
The DBActivationSpec property Undying instructs the Oracle Database Adapter to
never shut down while polling due to an EIS system exception. The Adapter instead
goes into a special mode where it keeps polling but does not log any messages, until it
is either shut down manually or the original problem is resolved.
It is recommended to set this before going into production, to handle any
SQLExceptions which may be classified incorrectly. In test and development it is
good to leave it as false, as most exceptions classified as non-retryable are genuinely
due to modeling mistakes.
When you execute the Adapter Configuration Wizard for Oracle Database Adapter
and click finish, the Undying property appears in the db.jca file for end point
activations, as shown in following example:

<endpoint-activation portType="poll_ptt" operation="receive">
<activation-spec className="oracle.tip.adapter.db.DBActivationSpec">
<property name="DescriptorName" value="poll.PerfMasterIn"/>
<property name="QueryName" value="pollSelect"/>
<property name="MappingsMetaDataURL" value="poll-or-mappings.xml"/>
<property name="PollingStrategy" value="LogicalDeletePollingStrategy"/>
<property name="MarkReadColumn" value="ATTRIBUTE2"/>
<property name="MarkReadValue" value="READ${weblogic.Name-1}-${IP}"/>
<property name="MarkReservedValue" value="MINE${weblogic.Name-1}-${IP}"/>
<property name="MarkUnreadValue" value="UNREAD"/>
<property name="PollingInterval" value="5"/>
<property name="MaxRaiseSize" value="5"/>
<property name="MaxTransactionSize" value="10"/>
<property name="SequencingColumn" value="PK"/>
<property name="ReturnSingleResultSet" value="false"/>
<property name="Undying" value="false"/>
</activation-spec>
To activate this property, you must set Undying to true.
9.3.7 Scalability
The following sections are example of the scalability feature for the Oracle Database
Adapter:
9.3.7.1 Distributed Polling Best Practice: MarkReservedValue
The best practice for multiple Oracle Database Adapter process instances deployed to
multiple Oracle BPEL Process Manager or Oracle Mediator nodes is essentially using
LogicalDeletePollingStrategy or DeletePollingStrategy with a unique
MarkReservedValue on each polling node, and setting MaxTransactionSize.
Note that MarkReservedValue (MarkUnReadValue, MarkReadFieldName), can
be set for DeletePollingStrategy. However, these options are not available in the
Adapter Configuration Wizard.
In the 11g release, the default MarkReservedValue in the Adapter Configuration
Wizard is now R${IP-2}-${weblogic.Name-2}-${instance}. This gives you a
value that is unique to the cluster (IP host address), to multiple JVMs on a particular
system (WebLogic Server name), and to multiple DBAdapter instances per activation
(if you set activationInstances property in composite.xml.) The only caveat with
a reserved value is making it unique when deploying to a cluster.
You must enter a value using a syntax such as
MINE${IP-2}-${weblogic.Name-1}. This will produce MINE24-1 where 2 and 4
are the last 2 digits of the host IP address and the managed server name ends in 1.
The following is a snippet of the .jca file for using MarkReservedValue with
DeletePollingStrategy:
<adapter-config name="poll" adapter="Database Adapter"
<connection-factory location="eis/DB/SOADemo" UIConnectionName="SOADemo"
Note: You must use the following distributed polling strategy for all
scalable best practices to avoid multiple nodes in a cluster processing
the same records twice.

adapterRef=""/>
<endpoint-activation portType="poll_ptt" operation="receive">
<property name="DescriptorName" value="poll.PerfMasterIn"/>
<property name="QueryName" value="pollSelect"/>
<property name="MappingsMetaDataURL" value="poll-or-mappings.xml"/>
<property name="PollingStrategy" value="DeletePollingStrategy"/>
<property name="MarkReadColumn" value="ATTRIBUTE2"/>
<property name="MarkReservedValue" value="MINE${weblogic.Name-1}-${IP}"/>
<property name="MarkUnreadValue" value="UNREAD"/>
</activation-spec>
</adapter-config>

9.3.7.2 Distributed Polling Second Best Practice: SELECT FOR UPDATE
The second best practice is not to set MarkReservedValue, but to still set
MaxTransactionSize.
The following are some benefits of using SELECT FOR UPDATE:
■ a status column is not needed (when using DeletePollingStrategy)
■ on a rollback no writes occur so it is completely safe. (In MarkReservedValue
rows are reserved first in a separate transaction.)
■ the same process, without any modification, can be deployed to multiple nodes.
Setting a unique MarkReservedValue can be an issue.
■ select for update is ANSI-SQL, so works well on any database.
Note: You can specify MarkReservedValue, and
MarkUnreadValue for the delete polling strategy, and not only for
the logical delete polling strategy. There is no support for these
properties in the Adapter Configuration Wizard, however, you can
create a logical delete in the Adapter Configuration Wizard, and then
edit the JCA file and change LogicalDelete to Delete under
PollingStrategyName.
A use case is outlined in the following steps to demonstrate this point:
1. Create a table using the SQL command:
Create table(test1 number,test2 varchar2(1000))
2. Create an SOA composite using an Oracle Database Adapter with logical
delete as the post-read operation with the corresponding properties, as
<property name="MarkReadColumn" value="TEST2"/>
<property name="MarkReadValue" value="read"/>
<property name="MarkReservedValue" value="reserved"/>
<property name="MarkUnreadValue" value="unread"/>
3. Deploy composite and test. This test successfully.
4. Use the Adapter Configuration Wizard to change the post-read operation
to delete the row(s) that were read.
In the following page, the SQL is generated without any error.
5. Redeploy the SOA composite and perform the following tests:
a. Execute the SQL command, insert
(1,'a') into TEST.
No polling occurs.
b. Execute the SQL command, insert
(2,'unread') into TEST.
Polling occurs, and this entry is deleted after
being read.
This is because entries in corresponding .jca file persists between Delete
and Logical Delete, both of which share the same values of
MarkReadColumn, MarkReservedValue and MarkUnreadValue. So
you must verify and edit the .jca file while switching between Delete
and Logical Delete.

The following are some down sides of using SELECT FOR UPDATE:
■ Concurrency and scalability are less as they holds a lock for a long time, which
tends to serialize access to the table. If you did a synchronous post to BPEL, that
could mean only one Oracle Database Adapter instance processing rows at a time.
One way or the other, a single transaction is not realistic for either approach. If the
time it takes for an Oracle Database Adapter to poll rows and asynchronously post
them to BPEL (default) is much less than the time spent in the BPEL process, then
this approach can still provide scalability.
■ Load balancing and throughput is less predictable. Oracle Database Adapter uses
select for update no wait by default, which really causes some instances
to get rows but others to abort early and come away with nothing. The maximum
throughput is much less than
MaxTransactionSize*#instances/pollingInterval as a result. Used for
crude load balancing, select for update would probably be better. To make this
change, you must edit the or-mappings.xml and change it to:
<toplink:lock-mode>lock</toplink:lock-mode>
■ Though select for update should work on any database, the one database it makes
the least sense for is on Oracle. On Oracle, pessimistic select for update locking is
not recommended: one of its key differentiators is that writers do not block
readers. Not only does this lower concurrency and introduce lock overhead but
interferes with other programs that are updating the table the Oracle Database
Adapter is polling from. To the perspective of non-Oracle Database Adapter
processes, select for update is more intrusive.
9.3.7.3 Distributed Polling Third Best Practice: Tuning on a Single Node First
See the samples MultiTablesPerformance and DirectSQLPerformance in the
following location for tuning on a single node:
For an Oracle Database Adapter intensive process, such as a database-database
integration, performance can be improved by a factor 10 or 100 just by tuning on a
single Java Virtual Machine (JVM) and scaling NumberOfThreads.
You can always add more nodes later, with MarkReservedValue, but try to get the
most out of one node first. If the Oracle Database Adapter polling is more than the
initiator of a far more complex BPEL process, then you may want a true distributed
approach, so you can scale BPEL.
The Oracle Database Adapter is preconfigured with many performance optimizations.
You can, however, make some changes to reduce the number of round trips to the
database by implementing performance tuning.
For information about performance tuning, see the chapter about performance tuning
in adapters in the Oracle Fusion Middleware Performance Guide.
Note:
For Oracle Database Adapter with polling operation in a clustered
environment, you must use the option of distributed polling by
selecting the Distributed Polling check box in the Adapter

9.3.9 detectOmissions Feature
The following are the features of the detectOmission feature:
Available Since
Release 10.1.3
Configurable
Yes
Default Value
Design Time: true, unless explicitly set to false
Use Case
Users may pass incomplete or partial XML to a merge, update, or insert, and see that
every column they left unspecified in XML is set to null in the database.
It allows DBAdapter merge, insert, or update to differentiate between null value and
the absence of a value (omission) in XML documents. On a case by case basis, it
determines which information in XML is meaningful and which is not. In this way
XML is seen as a partial representation of a database row, as opposed to a complete
representation. The following table lists examples for null values, and values that can
be omitted.
A value considered omitted is omitted from UPDATE or INSERT SQL. For an update
operation, existing (meaningful) values on the database are not overwritten. For an
insert operation, the default value on the database is used, as no explicit value is
provided in the SQL string.
A DBAdapter receive is not able to produce XML with omissions, and makes use of
xsi:nil="true". If you are unable to produce input XML with xsi:nil="true",
or are concerned about the difference between <director /> and
<director></director>, then it is best to set DetectOmissions="false" in the
JCA file.
Element Type Omission Null
Column <director></director>
<director />

<director xsi:nil=”true”
/>
1-1  <dept xsi:nil=”true” />
1-M 
</empCollection>
</empCollection> (empty)
Note: The 1-1 representation <dept /> denotes an empty
department object and should not be used.
For 1-M, <empCollection /> actually means a collection of 0
elements and is considered a meaningful value.
For columns, <director></director> is not considered an
omission in cases where it represents an empty string.

To treat all null values as omissions, check out the IgnoreNullsMerge sample,
which comes with a custom TopLink plugin. The plugin works similar to this feature,
but cannot detect subtleties between null and omission.
The IgnoreNullsMerge sample is available at the following location:
When you are expecting an update, you can improve performance, by omitting 1-1
and 1-M relationships. Because the merge operation can skip considering the detail
records completely.
Alternatively, map only those columns that you are interested in, and create separate
mappings for different invokes. If two updates should update two different sets of
columns, create two separate partnernlinks.
Performance
By default, XML is not used as an input to the Oracle Database Adapter containing
omissions. Until an XML with omissions is detected, there is no performance overhead.
Once omissions are detected, a TopLink descriptor event listener is added.
This event listener has some overhead, and every modifyRow about to become a
SQLUpdate or SQLInsert must be iterated over, to check for omissions. Hence,
every column value sent to the database is checked. If the input XML has mostly
omissions, then the cost overhead should be more than compensated by sending fewer
values to the database.
Incompatible Interactions
DirectSQL="true" and DetectOmissions="true" - DetectOmissions takes
precedence. The following are some examples for incompatible interactions:
■ DetectOmissionsMerge
■ IgnoreNullsMerge
■ OptimizeMerge
See the following for more information:
You can also access the forums from Oracle Technology Network at
■ The Oracle BPEL Process Manager forum at
http://forums.oracle.com/forums/forum.jspa?forumID=212
■ The TopLink forum at
http://forums.oracle.com/forums/forum.jspa?forumID=48
This site contains over 2,000 topics, such as implementing native sequencing,
optimistic locking, and JTA-managed connection pools with TopLink
http://www.oracle.com/technology
Note: For migrated old BPEL project, you must re-run the Database
Adapter Wizard in order to regenerate the JCA file. When you do this,
the DetectOmissions and OptimizeMerge options appear in the
JCA file with default values as DetectOmissions="false" and
OptimizeMerge="false".

9.3.10 OutputCompletedXml Feature
OutputCompletedXml is a feature of the outbound insert activity. The following
are some of the features of the OutputCompletedXml feature:
Available Since
Release 10.1.2.0.2
Configurable
OutputCompletedXml appears in the JCA file only when default is true.
Default Value
It is true when TopLink sequencing is configured to assign primary keys on insert
from a database sequence, otherwise it is false.
Issue
You can have primary keys auto-assigned on insert from a database sequence.
However, the usefulness of this feature is diminished, because insert/merge have
no output message, so there is no way to tell which primary keys were assigned.
Performance
An output XML is provided only when the output XML would be significantly
different, so if TopLink sequencing is not used, then this feature is disabled and there
is no performance hit. Further, this feature can be explicitly disabled. Likewise, the
original input XML is updated and returned; a completely new XML is not built. Also
only a shallow update of the XML is performed; if primary keys were assigned to detail
records, then these are not reflected in the output XML.
Incompatible Interactions
DirectSQL="true" and "OutputCompletedXml" - OutputCompletedXml takes
precedence.
9.3.11 QueryTimeout for Inbound and Outbound Transactions
You can configure QueryTimeout from the Adapter Configuration Wizard-
Advanced Options page. This feature exposes the java.sql.Statement level
property of the same name. Essentially, QueryTimeout allows you to configure a
time-out on the call.
9.3.12 Doing Synchronous Post to BPEL (Allow In-Order Delivery)
In this feature, the entire invocation is in a single thread and global transaction. By
default, initiation is asynchronous and the BPEL process is invoked in a separate
global transaction. With Oracle Mediator, it is generally a synchronous invoke so this
is only specific to an Oracle BPEL process.
To enable this feature, click the Do Synchronous Post to BPEL (Allow In-Order
Delivery) option in the Adapter Configuration Wizard - Operation page.
Note: After configuring sequencing (link), run the Adapter
Configuration Wizard again so that the insert/merge WSDL
operations can be regenerated with an output message, and WSDL
property OutputCompletedXml="true".

Oracle Database Adapter Concepts
9.4 Oracle Database Adapter Concepts
■ Section 9.4.1, "Relational-to-XML Mapping"
■ Section 9.4.2, "SQL Operations as Web Services"
9.4.1 Relational-to-XML Mapping
■ Section 9.4.1.1, "Relational Types to XML Schema Types"
■ Section 9.4.1.2, "Mapping Any Relational Schema to Any XML Schema"
■ Section 9.4.1.3, "Querying over Multiple Tables"
For a flat table or schema, the relational-to-XML mapping is easy to see. Each row in
the table becomes a complex XML element. The value for each column becomes a text
node in the XML element. Both column values and text elements are primitive types.
Table 9–1 shows the structure of the MOVIES table. This table is used in the use cases
described in this chapter. See Oracle Database Adapter Use Cases for more
information.
The corresponding XML schema definition (XSD) is as follows:
<xs:schema targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/db/top/ReadS1"
xmlns="http://xmlns.oracle.com/pcbpel/adapter/db/top/ReadS1"
elementFormDefault="qualified" attributeFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="MoviesCollection" type="MoviesCollection"/>
<xs:complexType name="MoviesCollection">
Table 9–1 MOVIES Table Description
Name Null? Type
TITLE NOT NULL VARCHAR2(50)
DIRECTOR -- VARCHAR2(20)
STARRING -- VARCHAR2(100)
SYNOPSIS -- VARCHAR2(255)
GENRE -- VARCHAR2(70)
RUN_TIME -- NUMBER
RELEASE_DATE -- DATE
RATED -- VARCHAR2(6)
RATING -- VARCHAR2(4)
VIEWER_RATING -- VARCHAR2(5)
STATUS -- VARCHAR2(11)
TOTAL_GROSS -- NUMBER
DELETED -- VARCHAR2(5)
SEQUENCENO -- NUMBER
LAST_UPDATED -- DATE

<xs:sequence>
<xs:element name="Movies" type="Movies" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="Movies">
<xs:sequence>
<xs:element name="title">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:maxLength value="50"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="director" minOccurs="0" nillable="true">
<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="starring" minOccurs="0" nillable="true">
<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="synopsis" minOccurs="0" nillable="true">
<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="genre" minOccurs="0" nillable="true">
<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="runTime" type="xs:decimal" minOccurs="0"
nillable="true"/>
<xs:element name="releaseDate" type="xs:dateTime" minOccurs="0"
nillable="true"/>
<xs:element name="rated" minOccurs="0" nillable="true">
<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="rating" minOccurs="0" nillable="true">
<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:element>

<xs:element name="viewerRating" minOccurs="0" nillable="true">
<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="status" minOccurs="0" nillable="true">
<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="totalGross" type="xs:decimal" minOccurs="0"
nillable="true"/>
<xs:element name="deleted" minOccurs="0" nillable="true">
<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="sequenceno" type="xs:decimal" minOccurs="0"
nillable="true"/>
<xs:element name="lastUpdated" type="xs:dateTime" minOccurs="0"
nillable="true"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
As the preceding code example shows, MOVIES is not just a single CLOB or XMLTYPE
column containing the entire XML string. Instead, it is an XML complexType
comprising elements, each of which corresponds to a column in the MOVIES table. For
flat tables, the relational-to-XML mapping is straightforward.
Table 9–2 and Table 9–3 show the structure of the EMP and DEPT tables, respectively.
These tables are used in the MasterDetail use case. See Oracle Database Adapter
Use Cases for more information.
Table 9–2 EMP Table Description
Name Null? Type
EMPNO NOT NULL NUMBER(4)
ENAME -- VARCHAR2(10)
JOB -- VARCHAR2(9)
MGR -- NUMBER(4)
HIREDATE -- DATE
SAL -- NUMBER(7,2)
COMM -- NUMBER(7,2)
DEPTNO -- NUMBER(2)

As the preceding table definitions show, and as is typical of a normalized relational
schema, an employee’s department number is not stored in the EMP table. Instead,
one of the columns of EMP (DEPTNO) is a foreign key, which equals the primary key
(DEPTNO) in DEPT.
However, the XML file equivalent has no similar notion of primary keys and foreign
keys. Consequently, in the resulting XML file, the same data is represented in a
hierarchy, thereby preserving the relationships by capturing the detail record
embedded inside the master.
An XML element can contain elements that are either a primitive type (string,
decimal), or a complex type, that is, another XML element. Therefore, an employee
element can contain a department element.
The corresponding XML shows how the relationship is materialized, or shown inline.
DEPTNO is removed from EMP, and instead you see the DEPT itself.
<EmpCollection>
<Emp>
<comm xsi:nil = "true" ></comm>
<empno >7369.0</empno>
<ename >SMITH</ename>
<hiredate >1980-12-17T00:00:00.000-08:00</hiredate>
<job >CLERK</job>
<mgr >7902.0</mgr
<sal >800.0</sal>
<dept>
<deptno >20.0</deptno>
<dname >RESEARCH</dname>
<loc >DALLAS</loc>
</dept>
</Emp>
...
</EmpCollection>
Materializing the relationship makes XML human readable and allows the data to be
sent as one packet of information. No cycles are allowed in the XML file; therefore, an
element cannot contain itself. This is handled automatically by the Oracle Database
Adapter. However, you may see duplication (that is, the same XML detail record
appearing more than once under different master records). For example, if a query
returned two employees, both of whom work in the same department, then, in the
returned XML, you see the same DEPT record inline in both the EMP records.
Therefore, when you import tables and map them as XML, it is recommended that you
avoid excessive duplication, although the Oracle Database Adapter does not print an
element inside itself. The Oracle Database Adapter prints the following:
<Emp>
<name>Bob</name>
<spouse>
<name>June</name>
</spouse
Table 9–3 DEPT Table Description
Name Null? Type
DEPTNO NOT NULL NUMBER(2)
DNAME -- VARCHAR2(14)
LOC -- VARCHAR2(13)

</Emp>
But not:
<Emp>
<name>Bob</name>
<spouse>
<name>June</name>
<spouse>
<name>Bob</name>
<spouse>
...
</spouse>
</spouse>
</spouse>
</Emp>
To avoid duplication, you can do the following:
■ Import fewer tables. If you import only EMP, then DEPT does not appear.
■ Remove the relationship between EMP and DEPT in the Adapter Configuration
Wizard. This removes the relationship, but the foreign key column is put back.
In both these cases, the corresponding XML is as follows:
<EmpCollection>
<Emp>
<comm xsi:nil = "true" ></comm>
<empno >7369.0</empno>
<ename >SMITH</ename>
<hiredate >1980-12-17T00:00:00.000-08:00</hiredate>
<job >CLERK</job>
<mgr >7902.0</mgr>
<sal >800.0</sal>
<deptno >20.0</deptno>
</Emp>
...
</EmpCollection>
Note that one of the two preceding solutions is feasible only if getting back the foreign
key suffices, as opposed to getting back the complete detail record in its entirety.
9.4.1.1 Relational Types to XML Schema Types
Table 9–4 shows how database data types are converted to XML primitive types when
you import tables from a database.
Table 9–4 Mapping Database Data Types to XML Primitive Types
Database Type XML Type (Prefixed with xs:)
VARCHAR, VARCHAR2, CHAR, NCHAR,
NVARCHAR, NVARCHAR2, MEMO, TEXT,
CHARACTER, CHARACTER VARYING,
UNICHAR, UNIVARCHAR, SYSNAME,
NATIONAL CHARACTER, NATIONAL CHAR,
NATIONAL CHAR VARYING, NCHAR
VARYING, LONG, CLOB, NCLOB,
LONGTEXT, LONGVARCHAR, NTEXT
string

Essentially, NUMBER goes to DECIMAL, the most versatile XML data type for numbers,
VARCHAR2 and CLOB to string, BLOB to base64Binary (to meet the plain-text
requirement), and date types to dateTime.
Any type not mentioned in this discussion defaults to java.lang.String and
xs:string. Time Stamp support is basic, because only the xs:dateTime format is
supported. The BFILE type is specifically not supported.
Because XML is plain text, BLOB and byte values are base 64/MIME encoded so that
they can be passed as character data.
9.4.1.2 Mapping Any Relational Schema to Any XML Schema
The Oracle Database Adapter supports mapping any relational schema on any
relational database to an XML schema, although not any XML schema of your choice,
because the Adapter Configuration Wizard generates the XML schema with no explicit
user control over the layout of the elements. You can control how you map the schema
in both the Adapter Configuration Wizard and later in TopLink Workbench. By pairing
the Oracle Database Adapter with a transformation step, you can map any relational
schema to any XML schema.
9.4.1.3 Querying over Multiple Tables
When executing a SQL select statement against multiple related tables there are the
following three methods to build the SQL. These ways relate to how to pull in the
detail records when the query is against the master record:
BLOB, BINARY, IMAGE,
LONGVARBINARY, LONG RAW,
VARBINARY, GRAPHIC, VARGRAPHIC,
DBCLOB, BIT VARYING
base64Binary
BIT, NUMBER(1) DEFAULT 0, SMALLINT
DEFAULT 0, SMALLINT DEFAULT 0
boolean
TINYINT, BYTE byte
SHORT, SMALLINT short
INT, SERIAL int
INTEGER, BIGINT integer
NUMBER, NUMERIC, DECIMAL, MONEY,
SMALLMONEY, UNIQUEIDENTIFIER
decimal
FLOAT FLOAT16, FLOAT(16), FLOAT32,
FLOAT(32), DOUBLE, DOUBLE PRECIS,
REAL
double
TIME, DATE, DATETIME, TIMESTAMP,
TIMESTAMP(6), SMALLDATETIME,
TIMESTAMPTZ, TIMESTAMPLTZ,
TIMESTAMP WITH TIME ZONE,
TIMESTAMP WITH LOCAL TIME ZONE
dateTime
Note: The user-defined Object, Struct and VARRAY, and REF
types are supported in 11g.
Table 9–4 (Cont.) Mapping Database Data Types to XML Primitive Types
Database Type XML Type (Prefixed with xs:)

■ Section 9.4.1.3.1, "Using Relationship Queries (TopLink Default)"
■ Section 9.4.1.3.2, "Twisting the Original Select (TopLink Batch-Attribute Reading)"
■ Section 9.4.1.3.3, "Returning a Single Result Set (TopLink Joined-Attribute
Reading)"
■ Section 9.4.1.3.4, "Comparison of the Methods Used for Querying over Multiple
Tables"
The following sections contain an outline of these three methods and their
comparison. However, note that when selecting rows from a single table there are no
issues as against selecting from multiple tables.
9.4.1.3.1 Using Relationship Queries (TopLink Default)
Having selected a Master row, TopLink can always query separately to get all the
details belonging to that Master table. These hidden queries (relationship queries) are
cached in the TopLink metadata and need to be prepared only once.
Consider the SQL statement in following sample scenario:
SELECT DIRECTOR, ..., VIEWER_RATING
FROM MOVIES
WHERE RATING = 'A';
For each master, the SQL statement is as follows:
SELECT CRITIC, ..., TITLE
FROM MOVIE_REVIEWS
WHERE (TITLE = ?)
It enables you to bring in all the data with 1 + n query executions, where n is the
number of master rows returned by the first query.
This approach is safe but slow, as a large number of round trips to the database are
required to pull in all the data.
For configuring using the relationship Queries (TopLink default) approach, you must
edit or_mappings.xml outside of Oracle JDeveloper. In addition, change the
batch-reading elements value to false.
9.4.1.3.2 Twisting the Original Select (TopLink Batch-Attribute Reading)
This is a default feature that allows TopLink to alter the original SQL select
statement to read all the details in a second select statement, as shown in the
following example:
SELECT DIRECTOR, ..., VIEWER_RATING
FROM MOVIES
WHERE RATING = 'A'
SELECT DISTINCT t0.CRITIC, ..., t0.TITLE
FROM MOVIE_REVIEWS t0, MOVIES t1
WHERE ((t1.RATING = 'A') AND (t0.TITLE = t1.TITLE))
By considering the original select statement in pulling in the details, a total of two (1
+ 1 = 2) query executions need to be performed.
Advantages
Batch attribute reading has the following advantages:
■ All data read in two round trips to database

■ The is a default feature in the 10.1.2.0.2 release
Disadvantages
Batch attribute reading has the following disadvantages:
■ When using maxTransactionSize (on polling receive) or maxRows (on invoke
select) to limit the number of rows loaded into memory at a time, these settings do
not easily carry over to the batch attribute query. It is easier to work with a
cursored result when there is only a single result set. (Multiple cursors can be used
with difficulty, if the original query has an order by clause).
■ TopLink can alter a SQL statement, only when it is in a format it can understand.
If you use the hybrid SQL approach and set custom SQL for the root select, then
TopLink will not be able to interpret that SQL to build the batch select.
■ The DISTINCT clause is used on the batch query, to avoid returning the same
detail twice if two masters happen to both point to it. The DISTINCT clause
cannot be used when returning LOBs in the resultset.
Configuration
Configuration is on a per 1-1 or 1-M mapping basis. By default, all such mappings
since the 10.1.2.0.2 release have this property set. To configure, edit or_
mappings.xml outside Oracle JDeveloper and edit the <batch-reading> elements to
true (default) or false.
9.4.1.3.3 Returning a Single Result Set (TopLink Joined-Attribute Reading)
The detail tables are outer-joined to the original SQL select statement, returning
both master and detail in a single result set, as shown in the following example:
SELECT DISTINCT t1.DIRECTOR, ..., t1.VIEWER_RATING, t0.CRITIC, ..., t0.TITLE
FROM MOVIE_REVIEWS t0, MOVIES t1
WHERE ((t1.RATING = 'A') AND (t0.TITLE (+) = t1.TITLE))
This requires one query execution in total.
Advantages
The advantages include the following:
■ In case of using maxTransactionSize while polling, the benefits of dealing with
a single cursor can be great.
■ When following the hybrid SQL route and entering custom SQL statements, you
only have to deal with a single SQL statement, whereas TopLink normally uses a
series of additional hidden SQL statements to bring in related rows.
■ read consistency: Enables you to read all related rows at the same time, and not at
different instances in time for the different tables.
■ Performance can be ideal as only a single round trip to the database is required,
whereas batch attribute reading requires one for each table queried.
Disadvantages
There are some drawbacks, however, namely the cost of returning duplicate data. For
example, consider that you read the Master and Detail tables; Master has 100
columns in each row, and Detail has 2 columns in each row. Each row in the table,
Master also, typically has 100 related Detail rows.
With one query in each table, the result sets for the preceding example appears, as

Master
Column1 column2 ….. column100
Master1 ...
Detail
Detail
Column1 column2
Detail1 ...
Detail2
...
Detail100 ...
In this example, 300 column values are returned as shown:
(columns in master + columns in detail x details per master) =
( 100 + 2 x 100
) = 300
With one query for all tables, the result set appears, as shown in the following
example:
Master Detail
Column1 Column2 ... Column100 Column1 Column2
Master1 ... Detail1 ...
Note that, in the case of one query for all tables, 10,200 column values are returned in a
single result set, versus 300 in two result sets, as shown here:
((columns in master + columns in detail) x details per master) =
(( 100 + 2 ) x 100 ) = 10,200
This can have a serious drain on network traffic and computation because 97 percent
of the data returned is duplicate data. Also, if the master had two related tables
detail1 and detail2 and there were 100 each in each master, then the number of
column values returned would be over 10 million per master row.
In general, you can use the following simple formula to estimate the relative cost of
returning all rows in a single result set:
(Master columns + Detail1 columns + Detail2 columns + ... ) x
Detail1s per Master x
Detail2s per Master x ...
bloat = ___________________________________________________________
(Master columns + Detail1 columns X Detail1s per Master +
Detail2 columns X Detail2s per Master + ...)
Note that for 1-1 relationships, this value is always 1, and if in the same example each
master had two columns only and the details had 100 columns instead, and each
master had only 3 or 4 details each, then the bloat would be
(2 + 100) x 4 408
bloat = ____________ = ___________ ~= 1
(2 + 100 x 4) 402
Another disadvantage is that this setting could distort the meaning of the maxRows
setting on an outbound select.

Configuration
To configure, select Use Outer Joins to return a Single Result Set for both Master
and Detail Tables on the Adapter Configuration Wizard - Define Selection Criteria
page.
9.4.1.3.4 Comparison of the Methods Used for Querying over Multiple Tables
On the surface, returning a single result set looks best (1 query), followed by batch
attribute reading (altering the select statement: 2 queries), and finally by default
relationship reading (n + 1 queries). However, there are several pitfalls to both of the
more advanced options, as explained below:
Altering User-Defined SQL
If you specify custom/hybrid SQL, the TopLink cannot alter that SQL string to
build the details select. For this reason, you must avoid using hybrid SQL and
build selects using the wizards' visual expression builder as often as
possible.
Show Me the SQL
The additional queries executed by TopLink in both, the default and the batch
attribute reading cases can be somewhat of a mystery to users. For this reason, the raw
Note:
When you create a SQL query such as the following by using the
TopLink Expression Builder, the result may not be as expected:
SELECT DISTINCT t1.TABLE1_ID, t1.COLUMN_A FROM TABLE2 t0, TABLE1 t1
WHERE ((t0.STATUS = 1) AND (t0.TABLE1_ID = t1.TABLE1_ID))
The expected result for this query is that only rows with Table 1's and
their owned Table 2's with status = 1 be returned.
However, what this query actually translates to is "table 1's, where any
of its table 2's have status = 1," resulting in the return of table 1's that
match the selection criteria, and ALL of the table 2's they own,
including those with other statuses, whether or not their statuses =1.
The DISTINCT keyword ensures the table 1's are not repeated and the
join happens across table 2.
The misunderstanding happens in the way Toplink works. Through
the Expression Builder, you can only specify a selection criteria for
Table 1 and have no control over the Table 2's they own, this part is
automatically done.
However, you can get the expected result by using either of the
following two approaches:
1.) Query directly for table 2 using the selection criteria of status = 1,
that is, do not go through table 1 and get the table 2's they own.
2.) Use direct (custom SQL), as shown in the following example:
SELECT TABLE1.TABLE1_ID, TABLE1.COLUMN_A, TABLE2.STATUS FROM
TABLE2, TABLE1 WHERE TABLE2.STATUS=1 AND TABLE1.TABLE1_ID =
TABLE2.TABLE1_ID

SQL shown to users in the DBAdapter wizard assumes returning a single result set, to
make things clearer and also to improve manageability.
Returning Too Many Rows At Once
Databases can store vast quantities of information, and a common pitfall of select
statements which return too much information at once. On a DBAdapter receive, a
maxTransactionSize property can be set to limit the number of rows which are
read from a cursored result set and processed in memory at a time. A similar
max-rows setting exists for one time invoke select statements. However, this
setting is very risky.
9.4.2 SQL Operations as Web Services
After mapping a relational schema as XML, you must also map basic SQL operations
as Web services. Each operation discussed in the following sections has a
corresponding tutorial and a readme file. It is recommended that you start with these
and try to run one or more as you read this section. As the tutorials demonstrate, some
operations translate directly to the SQL equivalent, while others are more complex.
■ Section 9.4.2.1, "DML Operations"
■ Section 9.4.2.2, "Polling Strategies"
9.4.2.1 DML Operations
Data manipulation language (DML) operations align with basic SQL INSERT,
UPDATE, and SELECT operations. SQL INSERT, UPDATE, DELETE, and SELECT are all
mapped to Web service operations of the same name. The MERGE is either an INSERT
or UPDATE, based on the results of an existence check. A distinction is made between
the data manipulation operations—called outbound writes—and the SELECT
operations—called outbound reads. The connection between the Web service and the
SQL for merge (the default for outbound write) and queryByExample are not as
obvious as for basic SQL INSERT, UPDATE, and SELECT.
■ Merge
■ querybyExample
■ Use Cases for Outbound Invoke Operations
Merge
Merge first reads the corresponding records in the database, calculates any changes,
and then performs a minimal update. INSERT, UPDATE, and MERGE make the most
sense when you are thinking about a single row and a single table. However, your
XML can contain complex types and map to multiple rows on multiple tables. Imagine
a DEPT with many EMPS, each with an ADDRESS. In this case, you must calculate
which of possibly many rows have changed and which to insert, update, or delete. If a
particular row did not change or only one field changed, then the DML calls is
minimal.
querybyExample
Unlike the SELECT operation, queryByExample does not require a selection criteria
to be specified at design time. Instead, for each invoke, a selection criteria is inferred
from an exemplary input XML record.

For instance, if the output xmlRecord is an employee record, and the input is a
sample xmlRecord with lastName = "Smith", then on execution, all employees
with a last name of Smith are returned.
A subset of queryByExample is to query by primary key, which can be implemented
by passing in sample XML records where only the primary key attributes are set.
Use queryByExample when you do not want to create a query using the visual query
builder and want the flexibility of allowing the input record to share the same XML
schema as the output records.
The queryByExample operation is slightly less performant because a new SELECT
must be prepared for each execution. This is because the attributes that are set in the
example XML record can vary each time, and therefore the selection criteria vary.
Input xmlRecord:
<Employee>
<id/>
<lastName>Smith</lastName>
</Employee>
Output xmlRecord:
<EmployeeCollection>
<Employee>
<id>5</id>
....
</Employee>
<Employee>
<id>456</id>
....
</Employee>
</EmployeeCollection>
Use Cases for Outbound Invoke Operations
Outbound invoke operations are demonstrated in the following tutorial files:
■ Insert
■ Update
■ Delete
■ Merge
■ SelectAll
■ SelectAllByTitle
■ PureSQLSelect
■ QueryByExample
For these files, go to
Use Cases for Pure SQL
A new option in 10.1.3.1 enables you to specify any arbitrary SQL string, and an XML
representing the inputs and outputs to the SQL is generated. Pure SQL operations are
demonstrated in the following tutorial files:

■ UpdateAll
■ SelectCount
■ SelectGroupBy
■ SelectStar
Advanced Use Cases for Outbound Invoke Operations
Advanced outbound invoke operations are demonstrated in the following tutorial
files:
■ InsertWithClobs
■ XAInsert
■ NativeSequencingInsert
9.4.2.2 Polling Strategies
The inbound receive enables you to listen to and detect events and changes in the
database, which in turn can be the initiators of a business process. This is not a
one-time action, but rather an activation. A polling thread is started, which polls a
database table for new rows or events.
Whenever a new row is inserted into the MOVIES table, the polling operation raises it
to the SCA Run Time. The strategy is to poll every record once. The initial SELECT has
to be repeated over time, to receive the rows that exist at the start and all new rows as
they are inserted over time. However, a new row once read is not likely to be deleted,
and therefore can possibly be read repeatedly with each polling.
The various ways to poll for events, called polling strategies, also known as after-read
strategies or publish strategies, range from simple and intrusive to sophisticated and
nonintrusive. Each strategy employs a different solution for the problem of what to do
after reading a row or event so as not to pick it up again in the next polling interval.
The simplest (and most intrusive) solution is to delete the row so that you do not
query it again.
This section discusses the following polling operations that you can perform after the
data is read from the database. This section also discusses the strategies and factors to
help you determine which strategy to employ for a particular situation:
■ Delete the Row(s) that were Read
■ Update a Field in the [Table_Name] Table (Logical Delete)
■ Update a Sequencing Table
■ Update an External Sequencing Table on a Different Database
■ Control Table Strategy
■ Update a Sequencing File

Delete the Row(s) that were Read
Choose this operation to employ the physical delete polling strategy. This operation
polls the database table for records and deletes them after processing. This strategy can
be used to capture events related to INSERT operations and cannot capture database
events related to DELETE and UPDATE operations on the parent table. This strategy
cannot be used to poll child table events. This strategy allows multiple adapter
instances to go against the same source table. There is zero data replication.
Preconditions: You must have deletion privileges on the parent and associated child
tables to use the delete polling strategy. Table 9–5 describes the requirements for using
the delete polling strategy.
Configuration: You can configure the delete polling strategy to delete the top-level
row, to cascade all, or to cascade on a case-by-case basis. This enables deleting only the
parent rows and not the child rows, cascaded deletes, and optional cascaded deletes,
determined on a case-by-case basis. You can configure the polling interval for
performing an event publish at design time.
Delete Cascade Policy: The optional advanced configuration is to specify the cascade
policy of the DELETE operation. For instance, after polling for an employee with an
address and many phone numbers, the phone numbers are deleted because they are
privately owned (default for one-to-many), but not the address (default for
one-to-one). This can be altered by configuring or_mappings.xml, as in the
following example:
<database-mapping>
<attribute-name>orders</attribute-name>
<reference-class>taxonomy.Order</reference-class>
<is-private-owned>true</is-private-owned>
You can also configure the activation itself to delete only the top level (master row) or
to delete everything.
A receive operation appears in an inbound JCA as follows:
Table 9–5 Delete Polling Strategy Preconditions
Requirements Met Conflicts With
Poll for inserts No delete on source
Shallow delete No updates on source
Cascading delete Poll for updates
Minimal SQL Poll for deletes
Zero data replication Poll for child updates
Default --
Allows raw SQL --
Concurrent polling --
Note: In Shallow delete and Cascading delete, the delete operation can
be configured to delete the top-level row, to cascade all, or to cascade
on a case-by-case basis.
Concurrent polling can be configured for both delete and logical delete
polling strategies.

<connection-factory location="eis/DB/Connection1" UIConnectionName="Connection1"
adapterRef=""/>
<endpoint-activation portType="dd_ptt" operation="receive">
<property name="DescriptorName" value="dd.Emp"/>
<property name="QueryName" value="ddSelect"/>
<property name="MappingsMetaDataURL" value="dd-or-mappings.xml"/>
<property name="PollingStrategy" value="LogicalDeletePollingStrategy"/>
<property name="MarkReadColumn" value="STATUS"/>
<property name="MarkReadValue" value="PROCESSED"/>
<property name="MarkReservedValue" value="RESERVED-1"/>
<property name="MarkUnreadValue" value="UNPROCESSED"/>
</activation-spec>
</adapter-config>
Update a Field in the [Table_Name] Table (Logical Delete)
Choose this operation to employ the logical delete polling strategy. This strategy
involves updating a special field on each row processed and updating the WHERE
clause at run time to filter out processed rows. It mimics logical delete, wherein
applications rows are rarely deleted but instead a status column isDeleted is set to
true. The status column and the read value must be provided, but the modified WHERE
clause and the post-read update are handled automatically by the Oracle Database
Adapter.
Preconditions: You must have the logical delete privilege or a one-time alter schema
(add column) privilege on the source table. Table 9–6 describes the requirements for
using the logical delete polling strategy.
Table 9–6 Logical Delete Polling Strategy Preconditions
Poll for inserts No updates on source
No delete on source Poll for deletes
Minimal SQL --
Zero data replication --
Minimal configuration --
Allows raw SQL --
Poll for updates --
Poll for child updates --
Concurrent polling --

Configuration: The logical delete polling strategy requires minimal configuration. You
must specify the mark read column and the value that indicates a processed record.
A receive operation appears in an inbound WSDL as follows:
<operation name="receive">
<jca:operation
ActivationSpec="oracle.tip.adapter.db.DBActivationSpec"
…
PollingStrategyName="LogicalDeletePollingStrategy"
MarkReadField="STATUS"
MarkReadValue="PROCESSED"
Given the configuration for logical delete, the Oracle Database Adapter appends the
following WHERE clause to every polling query:
AND (STATUS IS NULL) OR (STATUS <> 'PROCESSED')
Database Configuration: A status column on the table being polled must exist. If it
does not exist already, you can add one to an existing table.
Support for Polling for Updates: Given that rows are not deleted with each read, it is
possible to repetitively read a row multiple times. You must add a trigger to reset the
mark read field whenever a record is changed, as follows:
create trigger Employee_modified
before update on Employee
for each row
begin
:new.STATUS := 'MODIFIED';
end;
Support for Concurrent Access Polling: Just as a single instance should never process
an event more than once, the same applies to a collection of instances. Therefore,
before processing a record, an instance must reserve that record with a unique value.
Again, the status column can be used:
<operation name="receive">
<jca:operation
ActivationSpec="oracle.tip.adapter.db.DBActivationSpec"
…
PollingStrategyName="LogicalDeletePollingStrategy"
MarkReadField="STATUS"
MarkUnreadValue="UNPROCESSED"
MarkReservedValue="RESERVED${IP-2}-${weblogic.Name-1}-${instance}"
MarkReadValue="PROCESSED"
The polling query instead appears, as shown in the following example:
Update EMPLOYE set STATUS = 'RESERVED65-1-1' where (CRITERIA) AND (STATUS =
'UNPROCESSED');
Note: The requirements of the following are met, as follows:
■ Poll for updates: By adding a trigger
■ Poll for child updates: By adding a trigger
■ Concurrent polling: By specifying additional mark unread and
reserved values.

Select … from EMPLOYEE where (CRITERIA) AND (STATUS = 'RESERVED65-1-1');
The after-read UPDATE is faster because it can update all:
Update EMPLOYEE set STATUS = 'PROCESSED' where (CRITERIA) AND (STATUS =
'RESERVED65-1-1');
Update a Sequencing Table
Choose this operation to employ the sequencing table: last-read Id strategy. This
polling strategy involves using a helper table to remember a sequence value. The
source table is not modified; instead, rows that have been read in a separate helper
table are recorded. A sequence value of 1000, for example, means that every record
with a sequence less than that value has already been processed. Because many tables
have some counter field that is always increasing and maintained by triggers or the
application, this strategy can often be used for noninvasive polling. No field on the
processed row must be modified by the Oracle Database Adapter.
Native sequencing with a preallocation size of 1 can ensure that rows are inserted with
primary keys that are always increasing over time.
This strategy is also called a nondestructive delete because no updates are made to the
source rows, and a sequencing strategy such as the sequence field can be used to
order the rows in a sequence for processing. When the rows are ordered in a line, the
Oracle Database Adapter knows which rows are processed and which are not with a
single unit of information.
Preconditions: You must have a sequencing table or create table privilege on the
source schema. The source table has a column that is monotonically increasing with
every INSERT (an Oracle native sequenced primary key) or UPDATE (the last-modified
timestamp). Table 9–7 describes the requirements for using the sequencing polling
strategy.
Configuration: A separate helper table must be defined. On the source table, you must
specify which column is ever increasing.
<adapter-config name="ReadS" adapter="Database Adapter"
<connection-factory location="eis/DB/DBConnection1"
UIConnectionName="DBConnection1" adapterRef=""/>
<endpoint-activation portType="ReadS_ptt" operation="receive">
<property name="DescriptorName" value="ReadS.PerfMasterIn"/>
Table 9–7 Sequencing Polling Strategy Preconditions
Poll for inserts Poll for deletes
Poll for updates Allows raw SQL
No delete on source Concurrent polling
No updates on source --
One extra SQL select --
Zero data replication --
Moderate configuration --
Poll for child updates --

<property name="QueryName" value="ReadSSelect"/>
<property name="MappingsMetaDataURL" value="ReadS-or-mappings.xml"/>
<property name="PollingStrategy" value="SequencingPollingStrategy"/>
<property name="SequencingTable" value="PC_SEQUENCING"/>
<property name="SequencingTableKeyColumn" value="TABLE_NAME"/>
<property name="SequencingTableValueColumn" value="LAST_READ_ID"/>
<property name="SequencingTableKey" value="PERF_MASTER_IN"/>
</activation-spec>
</adapter-config>
The sequencing field type can be excluded if it is actually a number.
Database Configuration: A sequencing table must be configured once for a given
database. Multiple processes can share the same table. Given the ActivationSpec
specified in the preceding example, the CREATE TABLE command looks as follows:
CREATE TABLE SEQUENCING_HELPER
(
TABLE_NAME VARCHAR2(32) NOT NULL,
LAST_READ_DATE DATE
)
;
Polling for Updates: In the preceding example, the polling is for new objects or
updates, because every time an object is changed, the modified time is updated.
A sample trigger to set the modified time on every insert or update is as follows:
create trigger Employee_modified
before insert or update on Employee
for each row
begin
:new.modified_date := sysdate;
end;
Using a Sequence Number: A sequence number can be used for either insert or
update polling. Native sequencing returns monotonically increasing primary keys, as
long as an increment by 1 is used. You can also use the sequence number of a
materialized view log.
Update an External Sequencing Table on a Different Database
Choose this operation to employ the sequencing table: last updated strategy. This
polling strategy involves using a helper table to remember a last_updated value. A
last_updated value of 2005-01-01 12:45:01 000, for example, means that
every record last updated at that time or earlier has already been processed. Because
many tables have rows with a last_updated or creation_time column
maintained by triggers or the application, this strategy can often be used for
noninvasive polling. No fields on the processed row ever need to be modified by the
Oracle Database Adapter.
This strategy is also called a nondestructive delete because no updates are made to the
source rows, and a sequencing strategy such as the last_updated field can be used
to order the rows in a sequence for processing. When the rows are ordered in a line,

the Oracle Database Adapter knows which rows are processed and which are not with
a single unit of information.
See Update a Sequencing Table for information about preconditions and configuration.
Update a Sequencing File
This strategy works similar to Update an External Sequencing Table on a Different
Database, the only difference being that the control information is stored in a file
instead of a table.
Control Table Strategy
Choose this operation to employ the control table polling strategy. This polling
strategy involves using a control table to store the primary key of every row that has
yet to be processed. With a natural join between the control table and the source table
(by primary key), polling against the control table is practically the same as polling
against the source table directly. However, an extra layer of indirection allows the
following:
■ Destructive polling strategies such as the delete polling strategy can be applied to
rows in the control table alone while shielding any rows in the source table.
■ Only rows that are meant to be processed have their primary key appear in the
control table. Information that is not in the rows themselves can be used to control
which rows to process (a good WHERE clause may not be enough).
■ The entire row is not copied to a control table, and any structure under the source
table, such as detail rows, can also be raised without copying.
Streams and materialized view logs make good control tables.
Preconditions: You must have the create/alter triggers privilege on the source table.
Table 9–8 describes the requirements for using the control table polling strategy.
Using triggers, whenever a row is modified, an entry is added to a control table,
containing the name of the master table, and the primary keys. At design time, the
control table is defined to be the root

Xavier technology adapters

More Related Content

What's hot (19)

Viewers also liked (13)

Similar to Xavier technology adapters (20)

More from prathap kumar (20)

Xavier technology adapters