1. Administering Oracle SOA Suite and Oracle Business Process Management Suite
  2. Administering Binding Components
  3. Managing Service and Reference Binding Components

34 Managing Service and Reference Binding Components

This chapter describes how to manage policies for web service and JCA adapter service and reference binding components in SOA composite applications, publish service binding components to the Universal Description, Discovery, and Integration (UDDI) registry from a registered UDDI source, and perform additional Oracle Service Registry tasks.

This chapter includes the following topics:

Note:

Oracle SOA Suite does not support multiple bindings for service or reference binding components (for example, specifying both SOAP 1.1 and SOAP 1.2 in the composite.xml file). Support is only provided for a single web service binding per service or reference. If you specify multiple bindings, remove all but one and redeploy your SOA composite application.

For more information, see the following documentation:

Managing Binding Component Policies

You can attach and detach security policies to and from binding components included in a currently deployed SOA composite application (for example, web services and JCA adapters). Policies apply security to the delivery of messages. Oracle Fusion Middleware uses a policy-based model to manage web services.

Note:

Before attaching policies, see Securing Web Services and Managing Policies with Oracle Web Services Manager for definitions of available policies and details about which ones to use in your environment.

To manage binding component policies:

  1. Access this page through one of the following options:

    From the SOA Infrastructure Menu... From the SOA Folder in the Navigator...

    1. Select Home.

    2. Select the Deployed Composites tab.

    3. In the Composite section, select a specific SOA composite application.

    1. Under soa-infra, expand the SOA folder.

    2. Select a specific SOA composite application.

    The Dashboard page for the selected SOA composite application appears. The Services and References section of this page displays the binding components being used in the application.

  2. In the Services and References section, select a service or reference.

  3. Click Policies.

    The Policies page enables you to view the globally-attached and directly-attached policies, and to attach or detach security policies to and from a service or reference binding component:

    • The Globally Attached Policies table displays the globally-attached policy name, the policy set, the category (such as Management, Reliable Messaging, MTOM Attachment, Security, or WS Addressing), the violations since the SOA Infrastructure was last restarted, and the authentication, authorization, confidentiality, and integrity failures since the SOA Infrastructure was last restarted.

      Policy sets provide a means to attach policies globally to a range of endpoints of the same type. Attaching policies globally using policy sets enables an administrator to ensure that all subjects are secured in situations in which the developer, assembler, or deployer did not explicitly specify the policies to attach. Policies that are attached using a policy set are considered externally attached. For information about creating and managing policy sets, see Securing Web Services and Managing Policies with Oracle Web Services Manager.

    • The Directly Attached Policies table displays the directly-attached policy name, the policy reference status (enabled or disabled), the category, the violations since the SOA Infrastructure was last restarted, and the authentication, authorization, confidentiality, and integrity failures since the SOA Infrastructure was last restarted.

  4. Description of binding-component-policies.png follows
    Description of the illustration binding-component-policies.png

  5. In the Directly Attached Policies section, click Attach/Detach.

    If multiple components are available, you are prompted to select the service or component for which to perform the attachment or detachment.

    Note:

    If you attach a policy to a service binding component (client) and initiate an instance of the SOA composite application in the Test Web Service page, and the policy attachment fails, an Oracle Web Services Manager (OSWM) policy error is not generated and viewable in Oracle Enterprise Manager Fusion Middleware Control.

    If the same business flow instance is initiated externally, a policy error is generated and viewable in Oracle Enterprise Manager Fusion Middleware Control.

    For service components (such as a BPEL process) or reference binding components, the policy error is always generated and viewable, regardless of whether the business flow instance was initiated externally or internally through the Test Web Service page.

  6. Select the service or component to which to attach or detach a policy.

    This invokes a dialog for attaching or detaching policies.

    Policies currently attached appear in the Attached Policies section. Additional policies available for attachment appear in the Available Policies section.

  7. Select policies to attach that are appropriate to your environment.

  8. Click Attach.

  9. When you are finished attaching policies, click Validate.

  10. If an error message appears, make the necessary corrections until you no longer have any validation errors.

    The attached policy is displayed in the policies table.

  11. Click OK.

For more information, see the following documentation:

Override Policy Configuration Property Values

Your environment may include multiple servers with the same policies. However, each server may have their own specific policy requirements. To satisfy your runtime requirements, you can override the property values for some management and security policies attached to service and reference binding components.

  1. Follow the instructions in Managing Binding Component Policies to attach a policy to a service or reference binding component.
  2. Select the attached policy in the table.
  3. Click Override Policy Configuration.

    The Security Configuration Details dialog is displayed.

    Description of binding-component-policies2.png follows
    Description of the illustration binding-component-policies2.png
  4. In the Value field, enter a value to override the default value in the Original Value column.
  5. Click Apply.

For more information on overriding policy values, see Securing Web Services and Managing Policies with Oracle Web Services Manager.

Publishing Web Services to the UDDI Registry

You can publish service binding components to the UDDI registry from a registered UDDI source.

Notes:

  • You cannot publish a reference binding component to the UDDI registry.

  • You can only publish web services to the UDDI registry. For example, you cannot publish a JCA adapter.

  • You can publish web services to default Oracle Service Registry businesses from Oracle Enterprise Manager Fusion Middleware Control. To publish to nondefault businesses, use the publish option in Oracle Service Registry.

  • For more information about Oracle Service Registry, including documentation, visit the following URL:

    http://www.oracle.com/technetwork/middleware/registry/overview/index.html

For more information about publishing web services to the UDDI registry, see Administering Web Services.

To publish a web service to the UDDI registry:

  1. Access this page through one of the following options:

    From the SOA Infrastructure Menu... From the SOA Folder in the Navigator...

    1. Select Services and References.

    1. Right-click soa-infra.

    2. Select Services and References.

    The Services page displays details about the names and types of the services, the SOA composite applications in which the services are used, the SOA folder in which the composite is deployed, the total number of messages processed, the average processing time, and the number of faults occurring in the services.

  2. In the Service table, select a service to publish to the UDDI registry.

  3. From the Actions list, select Publish To UDDI.

    Description of bc_pubuddi.gif follows
    Description of the illustration bc_pubuddi.gif

    The Publish Service to UDDI dialog appears.

  4. Enter the following information:

    Field Description

    Service Name

    Displays the name of the selected service.

    Service Description

    Enter an optional description of the selected service.

    System Definition Location

    Displays the WSDL URL to publish to the UDDI registry. For example:

    http://myhost.mycompany.com:7001/soa-infra/services/default/HelloWorld/client?WSDL

    UDDI Source

    Select the UDDI publishing source from which to register the service.

    Business Name

    Select a business to publish the service. This is the name of the data structure in the UDDI registry. It is assumed that the business has already been registered in the UDDI registry.

    When complete, the Publish Service to UDDI dialog looks similar to the following:

    Description of bc_pubuddi2.gif follows
    Description of the illustration bc_pubuddi2.gif

  5. Click OK.

Changing the Endpoint Reference and Service Key for Oracle Service Registry Integration

If a reference binding component of the SOA composite application is integrated with Oracle Service Registry (OSR), you can change the endpoint reference and service key in the General section of this page.

The UDDI ServiceKey field automatically displays the value of binding.ws property="oracle.soa.uddi.serviceKey" from the composite.xml file if you selected to use UDDI for runtime resolution of the endpoint.

You can edit the UDDI ServiceKey field after the SOA composite application has been deployed to either:

  • Change the value as needed.

  • Add it to a composite that did not use UDDI for runtime endpoint resolution.

The Endpoint Address field represents the endpoint location as defined with the ws.binding endpointURI property in the composite.xml file. The Endpoint Address field is not filled in after the SOA composite application has been deployed, but can override the endpoint location in the concrete WSDL.

The endpoint location order of precedence is as follows:

  • Dynamically set the binding oracle.soa.uddi.serviceKey at runtime in the UDDI ServiceKey field.

  • Dynamically set the binding property endpointURI at runtime in the Endpoint Address field.

  • Use the binding property value for oracle.soa.uddi.serviceKey in the composite.xml file (viewable and editable in Oracle Enterprise Manager Fusion Middleware Control).

  • Use the binding property value for endpointURI in the composite.xml file (viewable and editable in Oracle Enterprise Manager Fusion Middleware Control).

  • Use the location specified in the concrete WSDL.

Figure 34-1 shows both fields.

Figure 34-1 Endpoint Reference and Service Key Properties

Description of Figure 34-1 follows
Description of "Figure 34-1 Endpoint Reference and Service Key Properties"

To change the endpoint reference and service key for OSR integration:

  1. In the UDDI ServiceKey field, change the service key to use during runtime.

  2. In the Endpoint Address field, enter the endpoint address to use during runtime.

You can edit both fields. The value for one field is selected and used based on what you selected in the UDDI Deployment Options dialog during design time. The changes to these fields are persisted in the composite.xml file during runtime.

For information about design-time tasks such as how to publish a business service, create a connection to the UDDI registry, and configure a SOA project to invoke a service from the registry, see Developing SOA Applications with Oracle SOA Suite.

For information about how to set the inquiry URL during runtime, see Configuring SOA Infrastructure Properties.

Configuring Caching of WSDL URLs

Caching of endpoint WSDL URLs occurs by default during runtime. If an endpoint WSDL URL is resolved using the orauddi protocol, subsequent invocations retrieve the WSDL URLs from cache, and not from OSR. You can increase the amount of time that the endpoint WSDL URL is available in cache for inquiry by the service key with the UddiCacheLifetime property. This property invalidates the cache at specified time intervals. The default value is 86400 seconds. The minimum value is 300 seconds.

To configure endpoint caching of WSDL URLs:

  1. From the SOA Infrastructure menu, select Administration > System MBean Browser.
  2. Select Application Defined MBeans > oracle.as.soainfra.config > Server: soa_server1 > SoaInfraConfig > soa-infra > Attributes.
  3. Click the UddiCacheLifetime property on the right side of the page.
  4. Enter a value.
  5. Click Apply.

Publishing and Browsing the Oracle Service Registry

The Oracle Service Registry (OSR) provides a common standard for publishing and discovering information about web services. This section describes how to configure OSR against a separately installed Oracle SOA Suite environment.

You can use Oracle SOA Suite with the following versions of OSR:

  • OSR 11g

  • OSR 10.3 (with Oracle WebLogic Server 10.3)

  • OSR 10.1.3

For more information about OSR, visit the following URL:

http://www.oracle.com/technetwork/middleware/registry/overview/index.html

Note:

  • This section does not describe how to configure OSR against the embedded Oracle WebLogic Server in Oracle JDeveloper.

  • OSR 10.3 deploys to the 10.3.0.0 version of Oracle WebLogic Server.

  • OSR 10.3 does not support the 10.3.1.0 version of Oracle WebLogic Server.

Publishing a Business Service

This section provides an overview of how to publish a business service. For specific instructions, see the documentation at the following URL:

http://www.oracle.com/technetwork/middleware/registry/overview/index.html

You can also access the documentation by clicking the Registry Documentation link.

To publish a business service:

  1. Go to the Registry Control:
    http://hostname:port/registry/uddi/web
  2. Click Publish > WSDL.
  3. Log in when prompted.
  4. Complete the fields on this page to specify the access point URL and publish the WSDL for the business service.

    Note:

    If you later change your endpoint location, you must also update the WSDL location in the Registry Control. Otherwise, UDDI invocation fails during runtime. See section Changing Endpoint Locations in the Registry Control.

Creating a Connection to the Registry

To create a connection to the registry:

  1. Go to Oracle JDeveloper.
  2. Select File > New > Connections > UDDI Registry Connection to create a UDDI connection.
  3. Enter a connection name.
  4. Enter an inquiry endpoint URL. For example:
    http://myhost.us.example.com:7001/registry/uddi/inquiry
  5. Ensure that the Business View option is selected.
  6. Click Next.
  7. Click Test Connection.
  8. If successful, click Finish. Otherwise, click the Back button and correct your errors.

Note:

When you right-click a web service of a SOA composite application under IDE Connections > Application Server in the Resources window in Oracle JDeveloper, the Publish WSDL To UDDI option is disabled.

Configuring a SOA Project to Invoke a Service from the Registry

To configure a SOA project to invoke a service from the registry:

  1. Open the SOA project in which to create a reference to the business service.
  2. Drag a Web Service icon into the External References swimlane.

    The Create Web Service dialog appears.

  3. To the right of the WSDL URL field, click the icon to select a WSDL.
  4. From the list at the top, select Resource Palette.
  5. Expand the navigational tree.
  6. Expand UDDI Registry > Business Services.
  7. Select the published business service, and click OK.
    Description of sca_jdevresource.gif follows
    Description of the illustration sca_jdevresource.gif

    The UDDI Deployment Options dialog appears.

  8. Select one of the following deployment options:

    • Dynamically resolve the SOAP endpoint location at runtime

    • Dynamically resolve the concrete WSDL location at runtime

    Description of sca_uddi.gif follows
    Description of the illustration sca_uddi.gif
  9. Click OK.

    You are returned to the Create Web Service dialog.

  10. See the following section based on your selection in the UDDI Deployment Options dialog.
Dynamically Resolving the SOAP Endpoint Location

To dynamically resolve the SOAP endpoint location:

  1. Complete the remaining fields in the Create Web Service dialog, and click OK.

    The Create Web Service dialog looks as follows.

    Description of sca_selectsoap.gif follows
    Description of the illustration sca_selectsoap.gif

  2. Wire the reference with the appropriate service component.

  3. In the SOA Composite Editor, click Source.

    The composite.xml file shows the serviceKey. The property dynamically resolves the endpoint binding location at runtime. 

    <property name="oracle.soa.uddi.servicekey" type="xs:string" many="false">uddi:
 d3611b59-1c79-478e-9ae5-874007eb20c4">

  4. If you want, you can also resolve the SOAP endpoint location by explicitly adding the oracle.soa.uddi.servicekey property in the Property Inspector. This action dynamically resolves the SOAP endpoint location at runtime for any external reference to a web service.

    1. Highlight the reference binding component in the External References swimlane.

    2. In the Property Inspector, expand the Properties section.

    3. Click the Add icon.

    4. In the Name list, select oracle.soa.uddi.servicekey.

    5. In the Value field, specify the value for oracle.soa.uddi.servicekey from the composite.xml file.

      Description of sca_servicekey.gif follows
      Description of the illustration sca_servicekey.gif
Dynamically Resolving the WSDL Endpoint Location

To dynamically resolve the WSDL endpoint location:

  1. Complete the remaining fields in the Create Web Service dialog, and click OK.
  2. Wire the reference with the appropriate service component.
  3. In the SOA Composite Editor, click Source.

    The composite.xml file shows that the WSDL location is an abstract URL of orauddi:/uddi_service_key instead of a concrete URL (such as a HTTP URL). The orauddi protocol dynamically resolves the WSDL location at runtime. 

    <location="orauddi:/uddi:d3689250-6ff5-11de-af2b-76279200af27">
Resolving Endpoints

Oracle SOA Suite invokes a service for resolving an endpoint. Examples and descriptions are shown in Table 34-1.

Table 34-1 Resolving Endpoints

Endpoint Resolutions Description Example

Normalized message UDDI serviceKey

The OSR UDDI serviceKey is specified in the normalized message property within an Oracle Mediator or an Oracle BPEL Process Manager assign activity (serviceKey).

For example, with Oracle Mediator: 

<copy target="$out.property.oracle.soa.uddi.serviceKey"
value="uddi:10a55fa0-99e8-11df-9edf-7d5e3ef09eda"/>

Normalized message endpointURI

The normalized message endpointURI property is specified within an Oracle Mediator or an Oracle BPEL Process Manager assign activity (endpointURI).

For example, with Oracle Mediator: 

<copy target="$out.property.endpointURI"
value="http://hostname:8001/soa-infra/services
/partition/Project/endpoint_ep"/>

composite.xml UDDI serviceKey

The OSR UDDI serviceKey property (oracle.soa.uddi.serviceKey) is specified in the binding component section of composite.xml.

Note: This can be overwritten in Oracle Enterprise Manager Fusion Middleware Control. 

<binding.ws
 port="http://xmlns.oracle.com/UDDIPublishApplication
 /Proj/BPELProcess1#wsdl.endpoint(bpelprocess1_client
 _ep/BPELProcess1_pt)"
 . . .>
 <property name="oracle.soa.uddi.serviceKey"
 type="xs:string"
 many="false">uddi:31040650-9ce7-11df-9ee1-7d5e3e
 f09eda</property>
</binding.ws>

composite.xml endpointURI

The endpointURI property is specified within the binding component section of composite.xml.

Note: This can be overwritten in Oracle Enterprise Manager Fusion Middleware Control. 

<binding.ws
 port="http://xmlns.oracle.com/UDDIPublishApplica
 tion/Project/BPELProcess1#wsdl.endpoint(bpelproc
 ess1_client_ep/BPELProcess1_pt)"
 . . . >
 <property name="oracle.soa.uddi.endpointURI"
 value="http://hostname:8001/soa-infra/services/
 Partition/Project/bpelprocess1_client_ep"</property>
</binding.ws>

composite.xml concrete WSDL endpoint location

The endpoint location is specified in the concrete WSDL in the binding component section of composite.xml. 

<binding.ws
 port="http://xmlns.oracle.com/UDDIPublishApplication
 /Project/BPELProcess1#wsdl.endpoint(bpelprocess1_
 client_ep/BPELProcess1_pt)"
 location="http://hostname:8001/soa-infra/services
 /Partition/Project/bpelprocess1_client_ep?wsdl"
 soapVersion="1.1">

The failover scenario for resolving endpoints is as follows.

  • Normalized message UDDI serviceKey

    • Any error on the endpoint access

      • Log a severe error

      • Return an error to the user

  • Normalized message endpointURI

    • Any error on the endpoint access

      • Log a severe error

      • Return an error to the user

  • composite.xml UDDI serviceKey

    • Error on an OSR connection

      • Log a severe error

      • Use the composite.xml endpointURI if it is coded

      • Else, return an error to the user

    • Error for an invalid serviceKey in the connection

      • Log a severe error

      • Use the composite.xml endpointURI if it is coded

      • Else, return an error to the user

    • Error on the endpoint access

      • Log a warning error

      • Use a second (or third) binding template if it exists.

      • Else, fail over to the composite.xml endpointURI

  • composite.xml endpointURI

    • Error on the endpoint access

      • Log a warning error

      • Fail over to the composite.xml concrete WSDL endpoint location

  • composite.xml concrete WSDL endpoint location

    • Error on the endpoint access

      • Log a severe error

      • Return an error to the user

Configuring the Inquiry URL, UDDI Service Key, and Endpoint Address for Runtime

You can set the inquiry URL, UDDI service key, and endpoint address during runtime in Oracle Enterprise Manager Fusion Middleware Control.

To configure the inquiry URL, UDDI service key, and endpoint reference for runtime:

  1. Log in to Oracle Enterprise Manager Fusion Middleware Control.
  2. Specify values for the following properties:
  3. Restart the SOA Infrastructure.
  4. Exit Oracle Enterprise Manager Fusion Middleware Control.
  5. To see endpoint statistics, return to the Registry Control.
  6. Go to the Manage page and check statistics to see the increase in the number of invocations when not cached (the first time).

    Caching of WSDL URLs occurs by default during runtime. If a WSDL URL is resolved using the orauddi protocol, subsequent invocations retrieve the WSDL URLs from cache, and not from OSR. When an endpoint WSDL obtained from cache is no longer reachable, the cache is refreshed and OSR is contacted to retrieve the new endpoint WSDL location. As a best practice, Oracle recommends that you undeploy services that are no longer required in Oracle Enterprise Manager Fusion Middleware Control and used by the SOA Infrastructure. Endpoint services that are shut down or retired (but not undeployed) are still reachable. Therefore, the cache is not refreshed.

    If you move the business service WSDL from one host to another, ensure that you change the location in the Registry Control. No change is required in Oracle JDeveloper or Oracle Enterprise Manager Fusion Middleware Control.

    You can optionally increase the amount of time that the WSDL URL is available in cache for inquiry by the service key. For more information, see Configuring Service and Reference Binding Component Properties.

    Note:

    In 11g, caching occurs automatically. If you are using Oracle SOA Suite 10.1.3, caching is supported by setting the CacheRegistryWSDL property to true in bpel.xml. Setting this property to false disables caching.

Changing Endpoint Locations in the Registry Control

The Registry Control provides an option for changing the endpoint location. This is a two-step process. The following steps provide an overview. For more specific details, see the Oracle Service Registry documentation:

http://www.oracle.com/technetwork/middleware/registry/overview/index.html

To update WSDL bindings:

  1. Log in to Registry Control.
  2. Click Search > Business.
  3. Click Add Name.
  4. In the Name field, enter a search criteria.
  5. Click Find.
  6. In the search results, click the business name that is displayed.
  7. On the right side, click the Services tab.
  8. From the list of services, click the service name.
  9. At the bottom, click the Edit button.
  10. On the right side, click the Bindings tab.
  11. In the list of bindings, select the notepad icon next to the description column.

    Oracle Service Registry is now in edit mode for bindings.

  12. In the Access Point field, change the required URL, and save your changes.
To Update WSDL Binding Overview Documentation:

  1. Within the Registry Control, click Search.

  2. In the tModel name field, enter the name and click Find tModel.

  3. In the name column, click the name with the description wsdl:type representing portType.

  4. Ensure that WSDL details are shown correctly.

  5. Click the Edit button.

  6. On the right side, click the Overview doc tab.

  7. Under the Add description button, click the Edit icon.

  8. Enter the new URL.

  9. Click Update and save the changes.

    Description of sca_osr2.gif follows
    Description of the illustration sca_osr2.gif

  10. To verify, navigate to the service and ensure that the WSDL URL is pointing to a new location.

Publishing WSDLs from Multiple SOA Partitions

Follow these steps to publish WSDLs from multiple SOA partitions using the Registry Control, and access them using a separate serviceKey and bindings.

To publish WSDLs from multiple SOA partitions:

  1. Log in to Registry Control.

    http://host:port/registry/uddi/web

  2. Publish the WSDL from the first partition.

  3. Publish the WSDL from the second partition.

    1. Click Publish > WSDL.

    2. Enter values in the Business key and WSDL location (URI) fields.

    3. Select the Advanced Mode checkbox.

    4. Click Publish.

    5. In the navigation tree in the left pane, select the endpoint, bindings, and port type, and ensure that the "new" mode option is selected.

      Description of sca_osr3.gif follows
      Description of the illustration sca_osr3.gif

    6. Click Publish.

How to Publish WSDLs to UDDI for Multiple Partitions

The following limitations exist for publishing WSDL services from Oracle Enterprise Manager Fusion Middleware Control.

  • You cannot publish the same service with the same target namespace from different SOA partitions or from different hosts.

  • There is no option for entering your own service key.

Instead, use the Registry Console to publish the same WSDL service deployed to different partitions to OSR.

To publish WSDLs to UDDI for multiple partitions:

  1. Log in to the Registry Console.
  2. Publish the WSDL of the first partition.
  3. Rename the above-mentioned service name to a unique name.
  4. Publish the WSDL of the second partition.

    This creates two separate services in OSR.