35 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, Cloud adapters, Oracle Business Activity Monitoring (BAM), Oracle B2B, Oracle Healthcare, ADF-BC services, Enterprise JavaBeans (EJB) services, Managed File Transfer (MFT), Representational State Transfer (REST) 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 Adding Service Binding Components and Adding Reference Binding Components.

35.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 REST binding).

  • References

    Enable messages to be sent from the SOA composite application to external services in the outside world. For REST bindings, a Web Application Description Language (WADL) file advertises the capabilities to external applications.

Figure 35-1 shows an OrderBookingComposite project 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 BAM Server in the outside world.

Figure 35-1 Service and Reference Binding Components

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

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

  • SOAP web services

  • HTTP binding

  • JCA adapters

  • Oracle E-Business Suite

  • Oracle BAM 11g (This adapter can only connect to an Oracle BAM 11g server.)

  • Oracle B2B

  • Oracle Healthcare

  • Oracle Managed File Transfer (MFT)

  • ADF-BC services

  • EJB services

  • Direct binding services

  • REST binding

  • Cloud adapters

These technologies are described in the following sections.

35.1.1 SOAP Web Services

This service enables you to integrate applications with a standards-based web service using the Simple Object Access Protocol (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 How to Define the Interface (WSDL) for a Web Service.

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

35.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 35-2 shows the support for WS-AT at the bottom of the Create Web Service dialog.

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

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

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

Table 35-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 the following example:

  <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 Administering Oracle SOA Suite and Oracle Business Process Management Suite.

For more information about WS-AT and WS-Coordination, see Developing Oracle Infrastructure Web Services and the WS-AT and WS-Coordination specifications, which are available at the following URL:

http://www.oasis-open.org
35.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 How to Add a BPEL Process Service Component, How to Define Deployment Descriptor Properties in the Property Inspector, and Transaction Semantics.

35.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 Administering Oracle SOA Suite and Oracle Business Process Management Suite.

35.1.2 HTTP Binding Service

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

You drag the HTTP service from the Components window 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.

35.1.2.1 Supported Interactions

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

Table 35-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 35-3 shows the supported XSD types for the inbound and outbound directions.

Table 35-3 Supported XSDs

Direction XSD Type Supported?

Inbound

Simple

Yes

Inbound

Complex

No

Inbound

Native

No

Outbound

Simple

Yes

Outbound

Complex

No

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

35.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 icon from the Components window.
  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 35-3 provides details.

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

    Description of Figure 35-3 follows
    Description of "Figure 35-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 of 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 35-4 provides details.

    Figure 35-4 Create HTTP Binding Wizard - Messages Page

    Description of Figure 35-4 follows
    Description of "Figure 35-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 35-5 provides details.

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

    Description of Figure 35-5 follows
    Description of "Figure 35-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.

35.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.

35.1.3 JCA Adapters

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

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

35.1.3.1 Database Adapter

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

For more information, see Oracle JCA Adapter for Database in Understanding Technology Adapters.

35.1.3.2 File Adapter

The file adapter enables a BPEL process or an 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 JCA Adapter for Files/FTP in Understanding Technology Adapters.

35.1.3.3 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 JCA Adapter for Files/FTP in Understanding Technology Adapters.

35.1.3.4 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 JCA Adapter for AQ in Understanding Technology Adapters.

35.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 JCA Adapter for JMS in Understanding Technology Adapters.

35.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 JCA Adapter for MQ Series in Understanding Technology Adapters.

35.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 JCA Adapter for Sockets in Understanding Technology Adapters.

35.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 Connecting with Third-Party Service Providers in Understanding Technology Adapters.

35.1.3.9 Oracle User Messaging Service Adapter

The Oracle User Messaging Service supports messaging channels such as email, secure messaging service (SMS), and instant messaging (IM). 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 JCA Adapter for UMS in Understanding Technology Adapters.

35.1.3.10 LDAP Adapter

The LDAP adapter defines both asynchronous and synchronous interfaces to send requests to and receive responses from LDAP directory servers. The LDAP adapter enables processes to search, compare, and modify LDAP directories using the LDAP protocol.

For more information, see Oracle JCA Adapter for LDAP in Understanding Technology Adapters.

35.1.3.11 Coherence Adapter

A Coherence cache is a collection of data objects that serves as an intermediary between the database and client applications. Database data can be loaded into a cache and made available to different applications. A Coherence cache reduces load on the database and provides faster access to database data. Objects in the cache can be either XML or Plain Old Java Objects (POJOs). The Coherence adapter enables you to perform the following operations against a Coherence cache.

  • Add an item

  • Obtain an item

  • Remove an item

  • Query for an item

For more information, see Oracle JCA Adapter for Coherence in Understanding Technology Adapters and Reading the Shipping Provider from Cache with the Coherence Adapter in Understanding Oracle SOA Suite.

35.1.3.12 JCA Adapter Properties

For information about JCA adapter properties, see Oracle JCA Adapter Properties in Understanding Technology Adapters.

If you are configuring newly created adapters in Reference Configuration mode, you can modify JCA Adapter endpoint properties directly in the Adapter Configuration Wizard. See JCA Endpoint Properties in the Adapter Configuration Wizard.

35.1.4 Oracle E-Business Suite 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.

35.1.5 Oracle BAM 11g Adapter

The Oracle BAM 11g adapter enables you to integrate Java EE applications with an Oracle BAM 11g server to send data. This adapter can only connect to an Oracle BAM 11g server.

Dragging a BAM 11g icon into a swimlane of the SOA Composite Editor invokes the Adapter Configuration Wizard for specifying configuration properties.

35.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 provides for 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 a B2B icon into a swimlane of the SOA Composite Editor invokes the B2B Configuration Wizard for specifying configuration properties.

35.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.

35.1.8 Oracle MFT

Oracle MFT enables you to transfer files to and from many endpoint types, such as the following:

  • Embedded FTP or sFTP server

  • Remote FTP or sFTP server

  • Directories

  • SOAP web service endpoints

  • Oracle SOA Suite SOAP web service endpoints

  • Oracle Service Bus web service endpoints

  • Oracle B2B partners and Oracle Healthcare endpoints

  • Oracle Data Integrator web service endpoints

35.1.9 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 icon 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:

35.1.10 EJB Adapter

The EJB adapter enables Enterprise JavaBeans and SOA composite applications to interact by passing Java interfaces (does not use a WSDL file to define the interface) or SDO parameters (uses 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 icon into a swimlane of the SOA Composite Editor invokes the Create EJB Service dialog for specifying configuration properties.

For more information, see Integrating Enterprise JavaBeans with Composite Applications.

35.1.11 Direct Binding Adapter

The direct binding adapter 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 flow or another SOA composite application in the outbound direction.

Dragging a Direct icon into a swimlane of the SOA Composite Editor invokes the Create Direct Binding dialog for specifying configuration properties.

For more information about direct binding, see Using Direct Binding to Invoke Composite Services.

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

For more information about Oracle Service Bus, see Developing Services with Oracle Service Bus.

35.1.12 REST Binding

REST is an architecture for designing network applications. RESTful applications use HTTP requests to post data (create and update), get data (for example, make queries), and delete data. REST provides an alternative to using web services. A SOA composite can be REST-enabled or invoke an existing REST service through the REST adapter.

For more information, see Integrating REST Operations in SOA Composite Applications.

35.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 Components window.

35.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 Technology section of the Components window, 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. Not all adapters can be dropped in both swimlanes. If an adapter is only available for references, then you cannot drop it into the services swimlane.
    • 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 35-6 shows a SOAP web service being dragged into the composite. This action invokes a dialog for specifying various configuration properties.

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

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

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

35.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. The following example provides details:

<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 for SOA composite interaction with ADF-BC Web Application. After deployment of a composite with ADF binding, invocation from a JSP/Java class is successful. The following example provides details:

<reference name="ADFWebService"
             ui:wsdlLocation="ADFWebService.wsdl">
    <interface.wsdl interface="http://example.com/hr/#wsdl.interface(HRAppService)"/>
    <binding.adf serviceName="{http://example.com/hr/}HRAppService"
                 registryName="hrapp_JBOServiceRegistry"/>
  </reference>

For this example, hrapp is the ADF-BC web application name.

35.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, the following code shows the location attribute with hardcoded values for protocol (http), host (host.us.example), and port (80).

<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">

The following example shows the location attribute after the creation of tokens.

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

Note:

  • 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 Administering Oracle SOA Suite and Oracle Business Process Management Suite.

35.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 35-7 provides details.

    Figure 35-7 Binding URL Tokenizer Icon

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

    The Binding URLs dialog appears, as shown in Figure 35-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

    • Binding URLs for REST references with the location attribute of the binding.rest element are automatically displayed.

    Figure 35-8 Binding URLs Dialog

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

    The Service2 reference in Figure 35-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 35-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 35-9.

    Figure 35-9 Binding URL Tokenization Dialog

    Description of Figure 35-9 follows
    Description of "Figure 35-9 Binding URL Tokenization Dialog"
  4. Provide values appropriate to your environment, as described in Table 35-4, and click OK.

    Table 35-4 Binding URL Tokenization Dialog

    Field Description

    Token File

    Perform either of the following options:

    • Click the Browse button to access a 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 check box 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 check box 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 35-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 35-10 Token Picker Dialog

    Description of Figure 35-10 follows
    Description of "Figure 35-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.