37 Getting Started with Binding Components

This chapter describes the supported service and reference binding component types and technologies that you can integrate in a SOA composite application. Supported binding components include web services, HTTP binding, JCA adapters, Oracle Business Activity Monitoring (BAM), Oracle B2B, Oracle Healthcare, ADF-BC services, EJB services, and direct binding services. Creation of tokens for use in the binding URLs of external references is also described.

This chapter includes the following sections:

For more information, see Section 2.3, "Adding Service Binding Components" and Section 2.4, "Adding Reference Binding Components."

37.1 Introduction to Binding Components

Binding components establish the connection between a SOA composite application and the external world. There are two types of binding components:

  • Services

    Provide the outside world with an entry point to the SOA composite application. The WSDL file of the service advertises its capabilities to external applications. 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, SOAP/HTTP or a JCA adapter).

  • References

    Enable messages to be sent from the SOA composite application to external services in the outside world.

Figure 37-1 shows the OrderBookingComposite project in the Fusion Order Demo in which a service (UpdateOrderStatus) in the Exposed Services swimlane provides the entry point to the composite and a reference (BAM_OrderDO) in the External References swimlane enables information to be sent to an Oracle Business Activity Monitoring (BAM) Server in the outside world.

Figure 37-1 Service and Reference Binding Components

Description of Figure 37-1 follows
Description of "Figure 37-1 Service and Reference Binding Components"

Binding components enable you to integrate the following types of technologies with SOA composite applications:

  • Web services

  • HTTP binding

  • JCA adapters

  • Oracle BAM

  • Oracle B2B

  • Oracle Healthcare

  • ADF-BC services

  • EJB services

  • Direct binding services

These technologies are described in the following sections.

37.1.1 Web Services

This service enables you to integrate applications with a standards-based web service using SOAP over HTTP. Web services are described in the WSDL file.

Dragging a web service into a swimlane of the SOA Composite Editor invokes the Create Web Service dialog for specifying configuration properties.

For more information about web services, see Section 2.3.2, "How to Define the Interface (WSDL) for a Web Service."

For information about adding Message Transmission Optimization Mechanism (MTOM) attachments to web services, see Section 45.1.1.3, "Sending and Receiving MTOM-Optimized Messages to SOA Composite Applications."

37.1.1.1 WS-AtomicTransaction Support

The Create Web Service dialog also enables you to configure support for WS-Coordination and WS-AtomicTransaction (WS-AT) transactions. WS-AT provides transaction interoperability between Oracle WebLogic Server and other vendors' transaction services. Interoperability is provided at two levels:

  • Exporting transactions from the local Java Transaction API (JTA) environment for a web service request.

  • Importing transactions from a web service request into the local JTA environment. This allows for distributed transaction processing between multiple nodes in the web services environment.

Figure 37-2 shows the support for WS-AT at the bottom of the Create Web Service dialog.

Figure 37-2 WS-AT Support in Create Web Service Dialog

Description of Figure 37-2 follows
Description of "Figure 37-2 WS-AT Support in Create Web Service Dialog"

Table 37-1 describes the WS-AT fields. For a description of the remaining fields in the Create Web Service dialog, see Section 2.3.2, "How to Define the Interface (WSDL) for a Web Service."

Table 37-1 WS-AT Fields of the Create Web Service Dialog

Property Description

Transaction Participation

Select a value. If you added the web service to the Exposed Services swimlane, this action enables external transaction managers to coordinate resources hosted on Oracle WebLogic Server over WS-AT. If you added the web service to the External References swimlane, this addition enables Oracle WebLogic Server transactions to coordinate resources hosted in external environments over WS-AT.

  • Never

    No transaction context is imported (for services) or exported (for references). This is the default value if you add the web service as a service binding component in the Exposed Services swimlane.

  • Supports

    If a transaction exists, a transaction context is imported (for services) or exported (for references). This information is added to the composite.xml file.

  • Mandatory

    A transaction context is imported (for services) or exported (for references). This information is added to the composite.xml file. For exports, a web service exception message is thrown if there is no active transaction. For imports, a fault is returned to the client if there is no transaction context in the request.

  • WSDLDriven

    This property only displays if you add the web service as a reference binding component in the External References swimlane. This is the default value.

Version

Displays the WS-AT supported version (1.0, 1,1, 1,2, or default). By default, this list is only enabled if you select Supports or Mandatory from the Transaction Participation list.

When complete, the composite.xml file displays your WS-AT selections, as shown in Example 37-1.

Example 37-1 WS-AT Syntax in composite.xml File

  <service name="Service1" ui:wsdlLocation="BPELProcess1.wsdl">
    <interface.wsdl interface="http://xmlns.oracle.com/Application5_
jws/Project1/BPELProcess1#wsdl.interface(BPELProcess1)"
                    callbackInterface="http://xmlns.oracle.com/Application5_
jws/Project1/BPELProcess1#wsdl.interface(BPELProcess1Callback)"/>
    <binding.ws port="http://xmlns.oracle.com/Application5_
jws/Project1/BPELProcess1#wsdl.endpoint(Service1/BPELProcess1_pt)">
      <property name="weblogic.wsee.wsat.transaction.flowOption"
                type="xs:string" many="false">SUPPORTS</property>
      <property name="weblogic.wsee.wsat.transaction.version" type="xs:string"
                many="false">WSAT11</property>
    </binding.ws>

If you want to edit your changes, you can right-click the service and select Edit or double-click the service in the SOA Composite Editor.

After deployment, you can modify the transaction participation and version values through the System MBean Browser. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

For more information about WS-AT and WS-Coordination, see Oracle Fusion Middleware Developer's Guide for Oracle Infrastructure Web Services and the WS-AT and WS-Coordination specifications, which are available at the following URL:

http://www.oasis-open.org
37.1.1.1.1 Ensuring Participation of BPEL Processes in WS-AT

In addition to setting the WS-AT participation property, if a client calls a web service that is a BPEL process, for that web service to be enlisted in the caller's transaction, the callee BPEL process must have the transaction property set in its composite.xml file.

<property name="bpel.config.transaction">required</property>

This setting ensures that, if an error occurs (such as a database adapter invocation failing due to an integrity constraint violation), a transaction rollback is successfully completed.

For more information about setting the transaction property, see Section 4.1.1, "How to Add a BPEL Process Service Component," Section C.1.1, "How to Define Deployment Descriptor Properties in the Property Inspector," and Section 13.1.1, "Oracle BPEL Process Manager Transaction Semantics."

37.1.1.1.2 WS-AT Transactions are Not Supported When Optimization is Enabled

You can configure a web service binding component as either a service or reference to support WS-AT transactions from the Transaction Participation dropdown list of the Create Web Service dialog. WS-AT transactions are supported in composite-to-web service environments, or vice-versa, with the oracle.webservices.local.optimization property set to false.

WS-AT transactions are not supported in composite-to-composite calls, even with the oracle.webservices.local.optimization property set to false.

For more information about the oracle.webservices.local.optimization property, see Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

37.1.2 HTTP Binding Service

The HTTP binding service enables you to integrate SOA composite applications with HTTP binding.

You drag the HTTP Binding service from the Component Palette into a swimlane of the SOA Composite Editor to invoke the HTTP Binding Wizard. This addition enables you to configure HTTP binding as follows:

  • As a service binding component in the Exposed Services swimlane to invoke SOA composite applications through HTTP POST and GET operations

  • As a reference binding component in the External References swimlane to invoke HTTP endpoints through HTTP POST and GET operations

Note:

Note the following details about using HTTP binding in a SOA composite application.

  • An outbound HTTP binding reference supports only XML as a response from an external HTTP endpoint. The response should contain the correct XML part name according to outbound expectations.

  • You cannot change the httpBinding property for the HTTP binding component during runtime in Oracle Enterprise Manager Fusion Middleware Control.

37.1.2.1 Supported Interactions

Table 37-2 shows the supported verbs, payloads, and operations for the inbound and outbound directions.

Table 37-2 Supported Verbs, Payloads, and Operations

Direction Verb Payload Type Operation Supported?

Inbound

GET

URL-encoded

One-way

Yes

Inbound

GET

URL-encoded

Request-response

Yes

Inbound

GET

XML

One-way

No

Inbound

GET

XML

Request-response

No

Inbound

POST

URL-encoded

One-way

Yes

Inbound

POST

URL-encoded

Request-response

Yes

Inbound

POST

XML

One-way

Yes

Inbound

POST

XML

Request-response

Yes

Outbound

GET

URL-encoded

One-way

No

Outbound

GET

URL-encoded

Request-response

Yes

Outbound

GET

XML

One-way

No

Outbound

GET

XML

Request-response

Yes

Outbound

POST

URL-encoded

One-way

No

Outbound

POST

URL-encoded

Request-response

Yes

Outbound

POST

XML

One-way

No

Outbound

POST

XML

Request-response

Yes

Table 37-3 shows the supported types in XSDs for the inbound and outbound directions.

Table 37-3 Supported Types in XSDs

Direction Types in XSDs Type Is Supported?

Inbound

Simple

Yes

Inbound

Complex

POST requests are supported

GET requests are not supported

Inbound

Native

No

Outbound

Simple

Yes

Outbound

Complex

POST requests are supported

GET requests are not supported

Outbound

Native

No

The following HTTP headers are not supported in either the inbound or outbound direction (that is, you cannot access HTTP headers in the composite and set them in the composite):

  • User-agent

  • Content-type

  • Content-length

  • Server

  • Server-port

  • Referrer

  • Authorization

  • MIME-Version

  • Location

37.1.2.2 How to Configure the HTTP Binding Service

To configure the HTTP binding service:

  1. Invoke the HTTP Binding Wizard to configure HTTP binding by dragging the HTTP Binding icon from the Component Palette.

  2. Provide appropriate responses on the Welcome, Service Name, and Adapter Interface pages.

    The HTTP Binding Component page of the wizard enables you to specify the operation type, verb, and payload type. Figure 37-3 provides details.

    Figure 37-3 Create HTTP Binding Wizard - HTTP Binding Configuration Page

    Description of Figure 37-3 follows
    Description of "Figure 37-3 Create HTTP Binding Wizard - HTTP Binding Configuration Page"

  3. Select the following operation types for inbound HTTP binding:

    • A one-way operation that sends or receives messages to or from an HTTP endpoint

    • A synchronous request-response operation that sends and receives input and output messages to and from an HTTP endpoint

    For HTTP POST request methods, you can select a payload type of either URL-encoded (ampersand-separated name-value pairs) or XML.

    For HTTP GET request methods, the payload type is URL-encoded.

    For HTTP GET or POST request methods for reference binding components, you are also prompted to specify the endpoint URL. Support for HTTP authentication and secure socket layer (SSL) is also provided.

    Note:

    Secure HTTP (HTTPS) is supported in both the inbound and outbound directions.

  4. Click OK.

  5. Browse for an existing request message schema or define your own schema with the links to the right of the URL field on the Messages page. Figure 37-4 provides details.

    Figure 37-4 Create HTTP Binding Wizard - Messages Page

    Description of Figure 37-4 follows
    Description of "Figure 37-4 Create HTTP Binding Wizard - Messages Page"

  6. Click OK.

  7. If you select to define your own schema, you are prompted to specify the element names, data types, minimum occurrence value, and maximum occurrence value in the Create Schema dialog. Figure 37-5 provides details.

    Figure 37-5 Create HTTP Binding Wizard - Create Schema Page

    Description of Figure 37-5 follows
    Description of "Figure 37-5 Create HTTP Binding Wizard - Create Schema Page"

  8. Click OK.

    At runtime, the concrete WSDL is generated with an HTTP binding and a SOAP binding; this is because the SOAP endpoint is used to provide HTTP support.

37.1.2.3 How to Enable Basic Authentication for HTTP Binding

Inbound and outbound HTTP binding supports basic authentication. If you want to enable basic authentication for inbound HTTP binding, you must attach a security policy. Inbound HTTP binding can also be used without enabling basic authentication.

To enable basic authentication:

  1. Right-click the created HTTP binding service in the Exposed Services swimlane and select Configure WS Policies.

  2. In the Configure SOA WS Policies dialog, click the Add icon in the Security section.

  3. Select the oracle/wss_http_token_service_policy policy, and click OK.

  4. In the Configure SOA WS Policies dialog, click OK.

37.1.3 JCA Adapters

JCA adapters enable you to integrate services and references with the following technologies:

  • Databases

  • File systems

  • FTP servers

  • Message systems such as Advanced Queueing (AQ) and Java Messaging Systems (JMS)

  • IBM WebSphere MQ

  • TCP/IP sockets

  • Oracle User Messaging Service

  • Third-party adapters (SAP, PeopleSoft, and others)

Dragging a JCA adapter into a swimlane of the SOA Composite Editor invokes the Adapter Configuration Wizard for specifying configuration properties.

37.1.3.1 AQ Adapter

The AQ adapter enables you to interact with a single consumer or multiconsumer queue.

Oracle Streams 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. Multiple queues can also service a single application, partitioning messages in a variety of ways and providing another level of scalability through load balancing.

For more information, see Oracle Fusion Middleware User's Guide for Technology Adapters.

37.1.3.2 Database Adapter

The database adapter enables a BPEL process to communicate with Oracle databases or third-party databases through JDBC.

For more information, see Oracle Fusion Middleware User's Guide for Technology Adapters.

37.1.3.3 File Adapter

The file adapter enables a BPEL process or Oracle Mediator to exchange (read and write) files on local file systems. The file contents can be in both XML and non-XML data formats.

Note:

When calling the file adapter, Oracle BPEL Process Manager may process the same file twice when run against Oracle Real Application Clusters planned outages. This is because a file adapter is a non-XA compliant adapter. Therefore, when it participates in a global transaction, it may not follow the XA interface specification of processing each file only once.

For more information, see Oracle Fusion Middleware User's Guide for Technology Adapters.

37.1.3.4 FTP Adapter

The FTP adapter enables a BPEL process or Oracle Mediator to exchange (read and write) files on remote file systems through use of the file transfer protocol (FTP). The file contents can be in both XML and non-XML data formats.

For more information, see Oracle Fusion Middleware User's Guide for Technology Adapters.

37.1.3.5 JMS Adapter

The JMS adapter enables an Oracle BPEL process or Oracle Mediator to interact with a Java Messaging System (JMS).

The JMS architecture uses one client interface to many messaging servers. The JMS model has two messaging domains:

  • Point-to-point: Messages are exchanged through a queue and each message is delivered to only one receiver.

  • Publish-subscribe: Messages are sent to a topic and can be read by many subscribed clients.

For more information, see Oracle Fusion Middleware User's Guide for Technology Adapters.

37.1.3.6 MQ Adapter

The MQ adapter provides message exchange capabilities between BPEL processes and Oracle Mediator and the WebSphere MQ queuing systems.

The Messaging and Queuing Series (MQ Series) is a set of products and standards developed by IBM. The MQ Series provides a queuing infrastructure that provides guaranteed message delivery, security, and priority-based messaging.

For more information, see Oracle Fusion Middleware User's Guide for Technology Adapters.

37.1.3.7 Socket Adapter

The socket adapter enables you to create a client or a server socket, and establish a connection. This adapter enables you to model standard or nonstandard protocols for communication over TCP/IP sockets. The transported data can be text or binary in format.

For more information, see Oracle Fusion Middleware User's Guide for Technology Adapters.

37.1.3.8 Third Party Adapter

The third party adapter enables you to integrate third-party adapters such as PeopleSoft, SAP, and others into a SOA composite application. These third-party adapters produce artifacts (WSDLs and JCA files) that can configure a JCA adapter.

For more information, see Oracle Fusion Middleware User's Guide for Technology Adapters.

37.1.3.9 Oracle User Messaging Service Adapter

The Oracle User Messaging Service supports messaging channels such as email, secure messaging service (SMS), instant messaging, and voice. The Oracle User Messaging Service provides a messaging proxy between the BPEL processes or Oracle Mediator service component and the external world. The Oracle User Messaging Service provides two-way messaging (inbound and outbound).

For more information, see Oracle Fusion Middleware User's Guide for Technology Adapters.

37.1.4 Oracle Applications Adapter

The Oracle applications adapter provides connectivity to Oracle Applications. The adapter supports all modules of Oracle Applications in Release 12 and Release 11i, including selecting custom integration interface types based on the version of Oracle E-Business Suite.

For more information, see Oracle Fusion Middleware Adapter for Oracle Applications User's Guide.

37.1.5 Oracle BAM Adapter

The Oracle BAM adapter enables you to integrate Java EE applications with Oracle BAM Server to send data.

Dragging an Oracle BAM adapter into a swimlane of the SOA Composite Editor invokes the Adapter Configuration Wizard for specifying configuration properties.

For more information, see Part X, "Using Oracle Business Activity Monitoring" and Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring.

37.1.6 Oracle B2B

The Oracle B2B service enables you to browse B2B metadata in the MDS repository and select document definitions.

Oracle B2B is an e-commerce gateway that enables the secure and reliable exchange of transactions between an organization and its external trading partners. Oracle B2B and Oracle SOA Suite are designed for e-commerce business processes that require process orchestration, error mitigation, and data translation and transformation within an infrastructure that addresses the issues of security, compliance, visibility, and management.

Dragging Oracle B2B into a swimlane of the SOA Composite Editor invokes the B2B Configuration Wizard for specifying configuration properties.

For more information, see Oracle Fusion Middleware User's Guide for Oracle B2B.

37.1.7 Oracle Healthcare Adapter

The Oracle Healthcare adapter enables you to create an end-to-end health care integration process in a SOA composite application. The Healthcare adapter establishes the connection between a SOA composite application and the external health care applications with which data is shared or with an internal topic or queue, where data can be made available internally or to other systems. You can use other Oracle SOA Suite components in your composite application, including BPEL processes, Oracle Mediator components, a variety of adapters, and so on.

The Healthcare Configuration Wizard in Oracle JDeveloper lets you add health care integration binding components to a SOA composite application as follows:

  • The component is used as a service (inbound) to receive messages from external systems and deliver them to SOA composite applications. Oracle SOA Suite for health care integration is the entry point to the SOA composite application.

  • The component is used as a reference (outbound) to send messages from the SOA composite application to external applications.

As you follow the steps in the Healthcare Configuration Wizard, you are prompted to select a document definition created in Oracle SOA Suite for health care integration.

You can launch Oracle SOA Suite for health care integration from the wizard to create a document definition if the right one does not already exist. This is the payload, or message, that you are receiving from or sending to external systems.

For more information, see Oracle Fusion Middleware Healthcare Integration User's Guide for Oracle SOA Suite.

37.1.8 ADF-BC Services

The ADF-BC service enables you to integrate Oracle Application Development Framework (ADF) applications using service data objects (SDOs) with SOA composite applications.

Dragging an ADF-BC Service into a swimlane of the SOA Composite Editor invokes the Create ADF-BC Service dialog for specifying configuration properties.

For more information about Oracle ADF, see the following:

37.1.9 EJB Services

The EJB service enables Enterprise JavaBeans and SOA composite applications to interact by passing SDO parameters (uses a WSDL file to define the interface) or Java interfaces (does not use a WSDL file to define the interface).

SDOs enable you to modify business data regardless of how it is physically accessed. Knowledge is not required about how to access a particular back-end data source to use SDO in a SOA composite application. Consequently, you can use static or dynamic programming styles and obtain connected and disconnected access.

Enterprise JavaBeans are server-side domain objects that fit into a standard component-based architecture for building enterprise applications with Java. These objects become distributed, transactional, and secure components.

Java interfaces eliminate the need for WSDL file definitions. This type of integration provides support with the following objects:

  • Native Java objects

  • Java Architecture for XML Binding (JAXB)

Dragging an EJB service into a swimlane of the SOA Composite Editor invokes the Create EJB Service dialog for specifying configuration properties.

For more information, see Chapter 38, "Integrating Enterprise JavaBeans with SOA Composite Applications."

37.1.10 Direct Binding Services

The direct binding service uses the Direct Binding Invocation API to invoke a SOA composite application in the inbound direction and exchange messages over a remote method invocation (RMI). This option supports the propagation of both identities and transactions across JVMs and uses the T3-optimized path. Both synchronous and asynchronous invocation patterns are supported.

You can also invoke an Oracle Service Bus (OSB) flow or another SOA composite application in the outbound direction.

Dragging a direct binding service into a swimlane of the SOA Composite Editor invokes the Create Direct Binding Service dialog for specifying configuration properties.

For more information about direct binding, see Chapter 39, "Using the Direct Binding Invocation API."

For information about the Direct Binding Invocation API, see Oracle Fusion Middleware Infrastructure Management Java API Reference for Oracle SOA Suite.

For more information about OSB, see Oracle Fusion Middleware Developer's Guide for Oracle Service Bus.

37.2 Introduction to Integrating a Binding Component in a SOA Composite Application

You integrate a binding component with a SOA composite application by dragging it from the Component Palette.

37.2.1 How to Integrate a Binding Component in a SOA Composite Application

To integrate a binding component in a SOA composite application:

  1. From the Service Adapters section of the Component Palette, drag a binding component to the appropriate swimlane. The swimlane in which to drag the component is based on the action you want to perform.

    • If you want to provide the outside world with an entry point to the SOA composite application, drag the binding component to the Exposed Services swimlane.

    • If you want to enable messages to be sent from the SOA composite application to external services in the outside world, drag the binding component to the External References swimlane.

    Figure 37-6 shows a web service being dragged into the composite. This action invokes a dialog for specifying various configuration properties.

Figure 37-6 Integration of a Web Service Binding Component into a Composite

Description of Figure 37-6 follows
Description of "Figure 37-6 Integration of a Web Service Binding Component into a Composite"

For more information about adding binding components, see Section 2.3, "Adding Service Binding Components" and Section 2.4, "Adding Reference Binding Components."

37.2.2 How to Use ADF Binding to Invoke a Composite Application from a JSP/Java Class

If a SOA composite application uses a web service binding to define an endpoint reference, the composite cannot be invoked from a JSP/Java class. Web services binding is defined with the binding.ws port="" location="" tag in the composite.xml file. Example 37-2 provides details.

Example 37-2 WS Binding Definition

<service name="client_ep" ui:wsdlLocation="BPEL.wsdl"> 
    <interface.wsdl interface="http://xmlns.oracle.com/Application/Project/ 
      BPEL#wsdl.interface(BPEL)"/> 
    <binding.ws port="http://xmlns.oracle.com/App/BPELProj/ 
      BPELProcess#wsdl.endpoint(bpel_client_ep/BPELProcess_pt)"/> 
  </service>

Instead, use ADF binding. After deployment of the composite with ADF binding, invocation from a JSP/Java class is successful. Example 37-3 provides details.

Example 37-3 ADF Binding Definition

<service name="client_ep" ui:wsdlLocation="BPEL.wsdl"> 
    <interface.wsdl interface="http://xmlns.oracle.com/Application/Project/ 
     BPEL#wsdl.interface(BPEL)"/> 
    <binding.adf serviceName="bpel_client" registryName=""/>   
  </service>

37.3 Creating Tokens for Use in the Binding URLs of External References

You can create tokens in Oracle JDeveloper for the HTTP protocol, host, and port values in the binding URLs of external references. The values that you assign to the tokens are then substituted in place of the hardcoded HTTP host and port values in the location attribute of the binding.ws element of the composite.xml file.

For example, Example 37-4 shows the location attribute with hardcoded values for protocol (http), host (host.us.example), and port (80).

Example 37-4 Hardcoded Values in location attribute

<binding.ws
port="http://www.globalcompany.example.com/ns/CreditAuthorizationService#wsdl.
endpoint(CreditAuthorizationService/CreditAuthorizationPort)"
location="http://host.us.example:80/apps/FusionOrderDemoShared/services/
creditAuthorization/CreditAuthorizationService.wsdl">

Example 37-5 shows the location attribute after the creation of tokens.

Example 37-5 Use of Tokens in location attribute

<binding.ws
port="http://www.globalcompany.example.com/ns/CreditAuthorizationService#wsdl.
endpoint(CreditAuthorizationService/CreditAuthorizationPort)"
location="${protocol}://${host1}:${port1}/apps/FusionOrderDemoShared/services/
creditAuthorization/CreditAuthorizationService.wsdl">

Notes:

  • You can only use tokens in the location attribute of the binding.ws element of the composite.xml file.

  • You cannot use tokens for the protocol, host, and port values in other files, such as WSDL files, schema files, and so on.

  • Oracle JDeveloper only updates token files on the local file system that include the token values. If you use a local token file at design time, you must move the tokens to the SOA server at runtime. For information about creating tokens during runtime, see Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

37.3.1 How to Create Tokens for Use in the Binding URLs of External References

Follow the steps in this section to create tokens for use in the binding URLs of external references.

To create tokens for use in the binding URLs of external references:

  1. In Oracle JDeveloper, access the SOA composite application in which to create tokens.

  2. Above the SOA Composite Editor, click the Binding URL Tokenizer icon. Figure 37-7 provides details.

    Figure 37-7 Binding URL Tokenizer Icon

    Description of Figure 37-7 follows
    Description of "Figure 37-7 Binding URL Tokenizer Icon"

    The Binding URLs dialog appears, as shown in Figure 37-8.

    Binding URLs of each external reference that has a binding.ws element with a location attribute in the composite.xml file that starts with the following entries are automatically displayed:

    • http

    • https

    • ${ (for a URL that uses tokens in place of the hardcoded HTTP protocol, host, or port values)

    • callbackServerURL

    Figure 37-8 Binding URLs Dialog

    Description of Figure 37-8 follows
    Description of "Figure 37-8 Binding URLs Dialog"

    The Service2 reference in Figure 37-8 also includes an override of the callback location using a reference property such as callbackServerURL:

    <property name="callbackServerURL" type="xs:string" many="false">
${protocol}://${myhost1}:${myport1}/soa-infra/services/default/service/
bpelprocess1_client_ep</property>

    The callbackServerURL property can be tokenized as shown in Figure 37-8.

  3. Double-click a row or select the row and click the Edit icon to create tokens for the HTTP protocol, host, and port values in the binding URLs of external references.

    The Binding URL Tokenization dialog appears, as shown in Figure 37-9.

    Figure 37-9 Binding URL Tokenization Dialog

    Description of Figure 37-9 follows
    Description of "Figure 37-9 Binding URL Tokenization Dialog"

  4. Provide values appropriate to your environment, as described in Table 37-4, and click OK.

    Table 37-4 Binding URL Tokenization Dialog

    Field Description

    Token File

    Perform either of the following options:

    • Click the Browse button to access the Resource Browser dialog for selecting the token file that includes the token names and values. The file can be on the local file system. The names and values specified in this file replace the hardcoded names and values for protocol, host, and port in the binding.ws element. This field is automatically populated with your file selection on subsequent invocations of this dialog. If you specify a token file from the file system, it must be an XML file that follows this format:

      <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM
 "http://java.sun.com/dtd/properties.dtd">
<properties>
   <comment>
      URL Resolver file used by the Metadata
      manager to resolve $<variable> in URLs
    </comment>
    <entry key="protocol">oramds</entry>
    <entry key="host">MyHost</entry>
    <entry key="port">80</entry>
</properties>

    • Skip this field entirely if you want to manually enter new token names and values in the Token and Current Values fields, respectively.

      Tokens that are not saved to a file are only placed in the location attribute of the binding.ws element in the composite. It is expected that you supply a token file at runtime that has tokens matching those manually entered at design time.

    Reference

    Displays the external reference you selected in Step 3.

    Protocol

    Displays the field in which to specify the protocol token name.

    • Click the Browse icon to select the token name to use from the Token Picker dialog. The Token Picker dialog is populated with the token names that appear in the token file you imported in the Token File field. The token name you select (for example, port1) and its default value (for example, 80) are added to the Token and Current Value fields, respectively. If the token file is writable (meaning an unprotected file in the file system), you can change the current value of the token name. See Step 5 for details about accessing the Token Picker dialog. If the file is read-only, you are warned with a message and allowed to cancel the operation and continue.

    • Manually enter the token name and value to use. You can manually enter information in these fields regardless of whether you imported a file in the Token File field. If you imported a file that is writable in the Token File field and manually enter a token name, it is added to the file if it does not already exist. The current value for the new token name defaults to the value in the URL that is being tokenized.

    Host

    Displays the field in which to specify the host token name. See the description of the Protocol field for details about how to specify information.

    Port

    Displays the field in which to specify the port token name. See the description of the Protocol field for details about how to specify information.

    Apply these tokens to other References which have the same Current Values

    Deselect this checkbox if you do not want other external references with the same protocol, host, and port values to be replaced with the same tokens.

    If this checkbox is selected and you tokenize just one or two of the URL objects, then the references for only those objects are modified. For example, if you only tokenize the host (with a current value of host1.us.oracle), all references that have that same host value are updated.

  5. If you selected the Browse button in the Protocol, Host, or Port fields, the Token Picker is displayed, as shown in Figure 37-10. This dialog lists all the tokens that you have defined in the file imported in the Token File field of the Binding URL Tokenization dialog.

    Figure 37-10 Token Picker Dialog

    Description of Figure 37-10 follows
    Description of "Figure 37-10 Token Picker Dialog"

  6. Select the token name to use through one of the following options:

    • Scroll through the list and select the token.

    • Begin entering the name in the Token field until the name is automatically completed and the token is selected in the list.

  7. Click OK.

    You are returned to the Binding URL Tokenization dialog with the selected token name and value displayed in the Token and Current Value fields, respectively.