14 Exposing Web Services Using the ADF Model Layer

This chapter describes how to call a third-party web service in a Fusion web application and work directly with the service proxy and service data objects (SDOs) programmatically for all common remote service data access tasks. It also describes how to create ADF data controls for third-party web services when you want to work with the web service in the user interface.

This chapter includes the following sections:

Section 14.1, "About Web Services in Fusion Web Applications"
Section 14.2, "Creating Web Service Data Controls"
Section 14.3, "Creating a New Web Service Connection"
Section 14.4, "Securing Web Service Data Controls"

14.1 About Web Services in Fusion Web Applications

Web services allow enterprises to expose business functionality irrespective of the platform or language of the originating application because the business functionality is exposed in such a way that it is abstracted to a message composed of standard XML constructs that can be recognized and used by other applications.

Web services are modular business services that can be easily integrated and reused, and it is this that makes them ideally suited as components within SOA. JDeveloper helps you to create top-down web services (services created starting from a WSDL), bottom-up web services (created from the underlying implementation such as a Java class or a PL/SQL stored procedure in a database), and services created from existing functionality, such as exposing an application module as a service.

14.1.1 Web Services Use Cases and Examples

You can consume web services in web applications, and common reasons for wanting to do so are:

To add functionality which would be time-consuming to develop with the application, but which is readily available as a web service
To access an application that runs on different architecture
To access an application that is owned by another team when their application must be independently installed, upgraded, and maintained, especially when its data is not replicated locally (for example, when other methods of accessing their application cannot be used).

14.1.2 Additional Functionality for Web Services in Fusion Applications

You may find it helpful to understand other ADF features before you start working with web services. Following are links to other functionality that may be of interest.

You can design a databound user interface by dragging an item from the Data Controls panel and dropping it on a page as a specific UI component. For more information, see Section 13.4.1, "How to Use the Data Controls Panel."
If you are working behind a firewall and you want to use a web service that is outside the firewall, you must configure the web browser and proxy settings in JDeveloper, as described in Section 9.12.4.3, "Setting Browser Proxy Information."
For information about creating data controls for application modules, see Chapter 13, "Using ADF Model in a Fusion Web Application." For information about other types of data controls, see Appendix H, "Data Controls in Fusion Web Applications."

The following chapters provide information about specific objects you can use in data controls:

For information about using collections on a data control to create forms, see Chapter 26, "Creating a Basic Databound Page."
For information about using collections to create tables, see Chapter 27, "Creating ADF Databound Tables."
For information about using master-detail relationships to create UI components, see Chapter 29, "Displaying Master-Detail Data."
For information about creating lists, see Chapter 30, "Creating Databound Selection Lists and Shuttles."
For information about creating graphs, charts, and other visualization UI components, see Chapter 33, "Creating Databound ADF Data Visualization Components."

14.2 Creating Web Service Data Controls

The most common way of using web services in an application developed using Oracle ADF is to create a data control for an external web service. A typical reason for doing this is to add functionality that is readily available as a web service, but which would be time consuming to develop with the application, or to access an application that runs on a different architecture.

Additionally, you can reuse components created by Oracle ADF to make them available as web services for other applications to access.

14.2.1 How to Create a Web Service Data Control

JDeveloper allows you to create a data control for an existing web service using just the WSDL for the service. You can browse to a WSDL on the local file system, locate one in a UDDI registry, or enter the WSDL URL directly.

Note:

If you are working behind a firewall and you want to use a web service that is outside the firewall, you must configure the web browser and proxy settings in JDeveloper. For more information, see Section 9.12.4.3, "Setting Browser Proxy Information."

Before you begin:

It may be helpful to have an understanding of how web service data controls are used in ADF applications. For more information, see Section 14.2, "Creating Web Service Data Controls."

You may also find it helpful to understand additional functionality that can be added using other web services features. For more information, see Section 14.1.2, "Additional Functionality for Web Services in Fusion Applications."

To create a web service data control:

In the Application Navigator, right-click an application and choose New.
In the New Gallery, expand Business Tier, select Web Services and then Web Service Data Control, and click OK.
In the Create Web Service Data Control wizard, on the Data Source page, specify a name for the data control, a WSDL URL, and the specific web service to be accessed by the data control.
On the Data Control Operations page, select the operations you want the data control to support.
On the Response Format page, specify the format of the SOAP response.
On the Endpoint Authentication page, specify the authentication details for the endpoint URL, and click Finish.

14.2.2 How to Include a Header Parameter for a Web Service Data Control

When using a web service data control, you may want to add an enterprise ID to the HTTP header when invoking the SOAP request. This enterprise ID in the request allows the web service data control to specify which cloud service the request will be directed to.

To configure the web service data control to use a header parameter, you select Include Http Header Parameter on the Data Control Operations page of the Create Web Service Data Control wizard. After creating the data control, you will be able to see the HttpHeader parameter in the Data Controls panel under the Parameters node of the web service data control's methods. You will also notice that AdapterDataControl element for the web service data control (in the .dcx file) contains an <httpHeaders paramName="HttpHeader"/> element.

To use the HttpHeader parameter, you will need to create a backing bean in the user interface project for the web service data control. The value for the HttpHeader parameter is provided through the backing bean. The backing bean must have a property of the type java.util.Map and the name/value pairs for the http headers should be added to that property. Additionally, the Map must be of type <String, List<String>> or <String,String>, and you should expose the property with getter and setter methods, as shown Example 14-1.

Example 14-1 Backing Bean to Support Http Header Parameters in a Web Service Data Control

public class BackingBean {
  private Map<String,Object> httpHeadersMap = new HashMap<String,Object>();
  public BackingBean() {
    List<String> headersList = new ArrayList<String>();
    headersList.add("Oracle");
    httpHeadersMap.put("enterpriseID",headersList);
  }
  public void setHttpHeadersMap(Map<String,Object> httpHeadersMap) {
    this.httpHeadersMap = httpHeadersMap;
  }
  public Map<String,Object> getHttpHeadersMap() {
    return httpHeadersMap;
  }
}

When you drag and drop the operation from the Data Controls panel onto a page as an ADF Parameter Form, remove the HttpHeader from the list of fields. Then, in the Edit Action Binding dialog, under the Parameters section specify the value for HttpHeader parameter by providing an expression that points to the backing bean Map property.

14.2.3 How to Adjust the Endpoint for a Web Service Data Control

After developing a web service data control, you can modify the endpoint. This is useful, for example, when you migrate the application from a test environment to production.

Before you begin:

It may be helpful to have an understanding of how web service data controls are used in ADF applications. For more information, see Section 14.2, "Creating Web Service Data Controls."

To change the endpoint for a web service data control:

In the Application Navigator, select the .dcx file for the web service data control.
In the Structure window, right-click the web service data control and choose Edit Web Service Connection from the context menu.
In the Edit Web Service Connection dialog, make the necessary changes to the endpoint URL and port name.
Click OK.

14.2.4 How to Refresh a Web Service Data Control

After creating a web service data control, you might find that a web service operation has changed in its method signature, return type, or structure. When this happens, you can update the data control without having to re-create it.

Before you begin:

It may be helpful to have an understanding of how web service data controls are used in ADF applications. For more information, see Section 14.2, "Creating Web Service Data Controls."

To refresh an operation in a web service data control:

In the Application Navigator, select the .dcx file for the web service data control.
In the Structure window, right-click the desired web service operation and choose Update from the context menu.

JDeveloper queries the web service and updates the web service data control to reflect the current state of the selected operation.

14.2.5 What You May Need to Know About Primary Keys in Web Service Data Controls

When you create a data control on a web service, the data control supports primary key operations on any exposed collection.

If the web service definition references a schema that defines an element or attribute as type xsd:ID, the data control will expose the attribute as a key attribute and make the setCurrentRowWithKey and setCurrentRowWithKeyValue data control operations available for the collection.

For example, your schema could set the deptno attribute as the primary key using the <xsd:attribute> element as shown below:

<xsd:attribute name="deptno" type="xsd:ID" use="required"/>

Or the schema could set the deptno attribute as the primary key using the <xsd:element> element as shown below:

<xsd:element name="deptno" type="xsd:ID"/>

Note:

The XSD entries shown above are generated at runtime if you have created the web service from a Java class and added the JAXB @XmlID annotation and either @XmlAttribute(required=true) or @XmlElement(required=true) to the getter method representing the key.

If no ID is defined for a collection in one of the above ways, the data control creates a hidden attribute for the collection that serves as an index-based primary key. You can then use the setCurrentRowWithKey or setCurrentRowWithKeyValue data control operation to pass the index of the row.

Note:

If you do not see the setCurrentRowWithKey or setCurrentRowWithKeyValue operations for a collection in the Data Controls panel, you may need to manually update the DataControls.dcx file to have those operations exposed. To do so, open the Source view of the DataControls.dcx and change the value of the service's ensureKeyAttribute property to true. Then, in the Data Controls panel, click the Refresh icon to refresh the list of operations.

14.2.6 What You May Need to Know About Web Service Data Controls

As with other kinds of data controls, you can design a databound user interface by dragging an item from the Data Controls panel and dropping it on a page as a specific UI component. For more information, see Section 13.4.1, "How to Use the Data Controls Panel."

In the Data Controls panel, each data control object is represented by an icon. Table 14-1 describes what each icon represents, where it appears in the Data Controls panel hierarchy, and what components it can be used to create.

Table 14-1 Data Controls Panel Icons and Object Hierarchy for Web Services

Name	Description	Used to Create...
Data Control	Represents a data control. You cannot use the data control itself to create UI components, but you can use any of the child objects listed under it. Depending on how your web services are defined, there may be more than one data control. Typically, there is one data control for each web service. However, you may have additional data controls that were created for other types of business services (for example, application modules). For information about creating data controls for application modules, see Chapter 13, "Using ADF Model in a Fusion Web Application."	Serves as a container for other objects and is not used to create anything
Collection	Represents a named data collection. A data collection represents a set of data objects (also known as a row set) in the data model. Each object in a data collection represents a specific structured data item (also known as a row) in the data model. Throughout this guide, data collection and collection are used interchangeably. For more information about using collections on a data control to create forms, see Chapter 26, "Creating a Basic Databound Page." For more information about using collections to create tables, see Chapter 27, "Creating ADF Databound Tables." For more information about using master-detail relationships to create UI components, see Chapter 29, "Displaying Master-Detail Data." For information about creating graphs, charts, and other visualization UI components, see Chapter 33, "Creating Databound ADF Data Visualization Components."	Forms, tables, graphs, trees, range navigation components, and master-detail components.
Attribute	Represents a discrete data element in an object (for example, an attribute in a row). Attributes appear as children under the collections or method returns to which they belong. For information about using attributes to create fields on a page, see Section 26.2, "Using Attributes to Create Text Fields." For information about creating lists, see Chapter 30, "Creating Databound Selection Lists and Shuttles."	Label, text field, date, list of values, and selection list components.
Structured Attribute	Represents a returned object that is not one of the Java primitive types (which are represented as attributes) and is also not a collection of any type. An example of a structured attribute would be a domain, which is a developer-created data type used to simplify application maintenance. For more information about domains, see Section 4.15, "Creating Custom, Validated Data Types Using Domains."	Label, text field, date, list of values, and selection list components
Method	Represents an operation in the data control or one of its exposed structures that may accept parameters, perform some business logic and optionally return single value, a structure or a collection of those.	Command components For methods that accept parameters: command components and parameterized forms
Method Return	Represents an object that is returned by a web service method. The returned object can be a single value or a collection. If a custom method returns anything at all, it is usually a single scalar value. However, some custom methods can return collections. A method return appears as a child under the method that returns it. The objects that appear as children under a method return can be attributes of the collection, other methods that perform actions related to the parent collection, and operations that can be performed on the parent collection. When a single-value method return is dropped, the method is not invoked automatically by the framework. You should either drop the corresponding method as a button to invoke the method, or if working with task flows you can create a method activity for it. For more information about executables, see Section 13.7.2.2, "Executable Binding Objects Defined in the Page Definition File."	The same components as for collections and attributes.
Operation	Represents a built-in data control operation that performs actions on the parent object. Data control operations are located in an Operations node under collections or method returns, and also under the root data control node. The operations that are children of a particular collection or method return operate on those objects only, while operations under the data control node operate on all the objects in the data control. If an operation requires one or more parameters, they are listed in a Parameters node under the operation. The standard operations supported by the web service data control are for form navigation: `First`, `Last`, `Next`, `Previous`, `SetCurrentRowByWithKey`, and `SetCurrentRowWithKeyValue`. Because the web service data control is not an updateable data control, you cannot use built-in operations like `Commit` and `Rollback`.	UI command components, such as buttons, links, and menus. For more information, see Section 26.4, "Incorporating Range Navigation into Forms," and Section 26.5, "Creating a Form to Edit an Existing Record."
Parameter	Represents a parameter value that is declared by the method or operation under which it appears. Parameters appear in the Parameters node under a method or operation. Array and structured parameters are exposed as updateable structured attributes and collections under the data control, which can be dropped as an ADF form or an updateable table on the UI. You can use the UI to build a parameter that is an array or a complex object (not a standard Java type).	Label, text, and selection list components.

14.3 Creating a New Web Service Connection

After developing a web service proxy, you can generate additional connections for the proxy that you can use in testing and deployment situations. For example, you might want to create a connection that includes user name and password for testing purposes.

14.3.1 How to Create a New Web Service Connection

The connection information is stored in the connections.xml file along with the other connections in your application. This abstraction of the endpoint URL also allows you to edit the connection after deployment using Enterprise Manager without requiring modification to the client code.

Before you begin:

It may be helpful to have an understanding of how web service connections are used in ADF applications. For more information, see Section 14.3, "Creating a New Web Service Connection."

You may also find it helpful to understand additional functionality that can be added using other data controls and web services features. For more information, see Section 14.1.2, "Additional Functionality for Web Services in Fusion Applications."

To create a new web service connection:

In the Application Navigator, right-click a web service proxy and choose Create ADF Web Service Connection.

The New ADF Web Service Connection dialog displays the default settings for a connection associated with the selected proxy.
Modify the connection information as necessary, and click OK.

WARNING:

If you create a new web service connection with the same name as an existing connection, the existing connection will be overwritten with the new information.

After you create a new web service connection, you can modify your client to use this connection. You could use code similar to that shown in Example 14-2 to access the connection from your client.

Example 14-2 Accessing a Web Service Connection from a Client

Context ctx = ADFContext.getCurrent().getConnectionsContext();
WebServiceConnection wsc = (WebServiceConnection) ctx.lookup("MyAppModuleService");
MyAppModuleService proxy = wsc.getJaxWSPort(MyAppModuleService.class);

The argument that you pass to the lookup() method is the name that you gave to the web service connection. In this example, it is MyAppModuleService.

14.4 Securing Web Service Data Controls

Web services allow applications to exchange data and information through defined application programming interfaces. SSL (Secure Sockets Layer) provides secure data transfer over unreliable networks, but SSL only works point to point. Once the data reaches the other end, the SSL security is removed and the data becomes accessible in its raw format. A complex web service transaction can have data in multiple messages being sent to different systems, and SSL cannot provide the end-to-end security that would keep the data invulnerable to eavesdropping.

Any form of security for web services has to address the following issues:

The authenticity and integrity of data
Data privacy and confidentiality
Authentication and authorization
Non-repudiation
Denial of service attacks

Throughout this section the "client" is the web service data control, which sends SOAP messages to a deployed web service. The deployed web service may be:

A web service running on Oracle Application Server
A web service running anywhere in the world that is accessible through the Internet

14.4.1 WS-Security Specification

The WS-Security specification unifies multiple security technologies to make secure web services interoperable between systems and platforms.

WS-Security addresses the following aspects of web services security issues:

Authentication and authorization

The identity of the sender of the data is verified, and the security system ensures that the sender has privileges to perform the data transaction.

The type of authentication can be a basic username/password pair transmitted in plain text, or trusted X509 certificate chains. SAML assertion tokens can also be used to allow the client to authenticate against the service, or allow it to participate in a federated SSO environment, where authenticated details are shared between domains in a vendor-independent manner.
Data authenticity, integrity, and non-repudation

XML digital signatures, which use industry-standard messages, digest algorithms to digitally sign the SOAP message.
Data privacy

XML encryption that uses industry-standard encryption algorithms to encrypt the message.
Denial of service attacks

Defines XML structures to time-stamp the SOAP message. The server uses the time stamp to invalidate the SOAP message after a defined interval.

14.4.2 Using Key Stores

A web service data control can be configured for message-level security using key stores. For more information about creating and using key stores for message protection, see the section about managing keystores, wallets, and certificates in the Oracle Fusion Middleware Administrator's Guide, and the section about configuring policies in the Oracle Application Server Web Services Security Guide.

14.4.3 How to Define Web Service Data Control Security

After you create a web services data control in a JDeveloper project, you can define security for the data control using the Edit Data Control Policies dialog.

Before you begin:

It may be helpful to have an understanding of how security is used in web service data controls. For more information, see Section 14.4, "Securing Web Service Data Controls."

To define security for a web service data control:

In the Application Navigator, select the web service data control .dcx file.
In the Structure window, right-click the web service data control, and choose Define Web Service Security.

JDeveloper displays the Edit Data Control Policies dialog, which shows the Policy Store location. To select an alternative policy store, use the WS Policy Store page of the Preferences dialog.
From the Ports dropdown list, select the port to which you want the specified policies are applied.
From the MTOM dropdown list, select the MTOM (message transmission optimization mechanism) policy you want to use. If you leave this field blank, no MTOM policy is used.
From the Reliability dropdown list, select the reliability policy you want to use. If you leave this field blank, no reliability policy is used.
From the Addressing dropdown list, select the addressing policy you want to use. If you leave this field blank, no addressing policy is used.
In the Security list, you can optionally specify additional security policies to apply. To add a policy, click the Add security policy icon.
In the Management list, you can optionally specify additional management policies to apply. To add a policy, click the Add management policy icon.
If necessary, you can also remove policies from the Security list and the Management list by selecting the appropriate policy and clicking the corresponding delete icon.
You can optionally override properties for the policies in the Security list and the Management list by clicking Override Properties.
After you have selected the appropriate policies for your web service data control, click OK to apply your selections and close the dialog.

For more information about predefined policies and configuring policies and their properties, see the Oracle Application Server Web Services Security Guide.