13 Integrating Web Services Into a Fusion Web Application

This chapter describes how to call a third-party web service 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:

13.1 Introduction to 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.

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)

13.2 Calling a Web Service from an Application Module

In a service-oriented architecture, your Oracle ADF application module may need to take advantage of functionality offered by a web service that is not based on an application module. A web service can be implemented in any programming language and can reside on any server on the network. Each web service identifies the methods in its API by describing them in a standard, language-neutral XML format. This XML document, whose syntax adheres to the Web Services Description Language (WSDL), enables JDeveloper to understand the names of the web service's methods, as well as the data types of the parameters they might expect and their eventual return value.

Note:

Application modules can also be exposed as web services so that they can be consumed across modules of the deployed Fusion web application. For details about reusing ADF Business Components using external services, see Chapter 11, "Integrating Service-Enabled Application Modules."

JDeveloper's built-in web services wizards make this an easy task. Create a web service proxy class using the wizard, then call the service using method calls you add to a local Java object.

13.2.1 How to Call an External Service Programmatically

To call a web service from an application module, you create a web service proxy class for the service you want to invoke. A web service proxy is a generated Java class that represents the web service inside your application. It encapsulates the service URL of the web service and handles the lower-level details of making the call.

To work with a web service, you need to know the URL that identifies its WSDL document. If you have received the WSDL document as an email attachment, for example, and saved it to your local hard drive, the URL could be similar to:

file:///D:/temp/SomeService.wsdl

Alternatively, the URL could be an HTTP-based URL like:

http://someserver.somecompany.com/SomeService/SomeService.wsdl

Some web services make their WSDL document available by using a special parameter to modify the service URL. For example, a web service that expects to receive requests at the HTTP address of http://someserver.somecompany.com/SomeService might publish the corresponding WSDL document using the same URL with an additional parameter on the end, like this:

http://someserver.somecompany.com/SomeService?WSDL

Since there is no established standard, you will just need to know what the correct URL to the WSDL document is. With the URL information, you can then create a web service proxy class to call the service.

ADF Business Components services have URLs to the service of the following formats:

  • On Integrated WebLogic Server, the URL has the format http://host:port/EJB-context-root/@WebService-name?WSDL, for example:

    http://localhost:8888/EJB-StoreFrontService/StoreFrontService?WSDL
    
  • On Oracle Application Server, the URL has the format http://host:port/context-root/@WebService-name?WSDL, for example:

    http://localhost:8888/StoreFrontService/StoreFrontService?WSDL
    

The web service proxy class presents a set of Java methods that correspond to the web service's public API. By using the web service proxy class, you can call any method in the web service in the same way as you work with the methods of any other local Java class.

To call a web service from an application module using a proxy class, you perform the following tasks:

  1. Create a web service proxy class for the web service. To create a web service proxy class for a web service that you need to call, use the Create Web Service Proxy wizard.

  2. Implement the methods in the proxy class to access the desired web services.

  3. Create an instance of the web service proxy class in your application module and invoke one or more methods on the web service proxy object.

13.2.1.1 Creating a Web Service Proxy Class to Programmatically Access the Service

To create a web service proxy class for a web service you need to call, use the Create Web Service Proxy wizard.

To create a web service proxy class to programmatically access the service:

  1. In the Application Navigator, right-click the project in which you want to create the web service proxy, and choose New.

  2. In the New Gallery, expand Business Tier, select Web Services and then Web Service Proxy, and click OK.

  3. On the Select Web Service Description page of the wizard, enter or choose a Java package name for the generated web service proxy class.

  4. Enter the URL for the WSDL of the service you want to call in your application, and then tab out of the field.

    If the Next button does not enable, click Why Not? to understand what problem JDeveloper encountered when trying to read the WSDL document. If necessary, fix the problem after verifying the URL and repeat this step.

  5. When the wizard displays Next enabled, then JDeveloper has recognized and validated the WSDL document. You can click Next and continue.

  6. Continue through the pages of the wizard to specify details about the web service proxy. For more information about each page of the wizard, press F1 or click Help.

  7. Click Finish.

13.2.1.2 Calling the Web Service Proxy Template to Invoke the Service

After you create the web service proxy, you must implement the methods in the proxy class to access the desired web services.

To call the web service proxy template to invoke the service:

  1. Open the proxy client class, called port_nameClient.java, in the source editor, and locate the comment // Add your own code to call the desired methods, which is in the main method.

  2. Add the appropriate code to invoke the web service.

  3. Deploy the full set of client module classes that JDeveloper has generated, and reference this class in your application.

13.2.1.3 Calling a Web Service Method Using the Proxy Class in an Application Module

After you've generated the web service proxy class, you can use it inside a custom method of your application module, as shown in Example 13-1. The method creates an instance of the web service proxy class and calls the web service method from the web service proxy class for the result.

Example 13-1 Web Service Proxy Class Calls Web Service Method

// In YourModuleImpl.java
public void performSomeApplicationTask(String symbol) throws Exception {
  // application-specific code here
   :
  // Create an instance of the web service proxy class 
  StockQuoteServiceSoapHttpPortClient svc =
            new StockQuoteServiceSoapHttpPortClient();
  // Call a method on the web service proxy class and get the result
  QuoteInfo quote = svc.quoteForSymbol(symbol);
  float currentPrice = quote.getPrice();
  // more application-specific code here
}

13.2.2 How to Create 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.

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.

To create a new web service connection:

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

  2. 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 13-2 to access the connection from your client.

Example 13-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.

13.2.3 What Happens When You Create the Web Service Proxy

JDeveloper generates the web service proxy class in the package you've indicated with a name that reflects the name of the web service port it discovered in the WSDL document. The web service port name might be a human-readable name like StockQuoteService, or could be a less-friendly name like StockQuoteServiceSoapHttpPort. The port name is decided by the developer that published the web service you are using. If the port name of the service were StockQuoteServiceSoapHttpPort, for example, JDeveloper would generate a web proxy class named StockQuoteServiceSoapHttpPortClient.

The web service proxy displays in the Application Navigator as a single, logical node called WebServiceNameProxy. For example, the node for the StockQuoteService web service would appear in the navigator with the name StockQuoteServiceProxy. As part of generating the proxy class, in addition to the main web service proxy class that you use to invoke the server, JDeveloper generates a number of auxiliary classes and interfaces. You can see these files in the Application Navigator under the WebServiceNameProxy node. The generated files are used as part of the lower-level implementation of invoking the web service.

The only auxiliary generated classes you need to reference are those created to hold structured web service parameters or return types. For example, imagine that the StockQuoteService web service has a quoteForSymbol() method that accepts one String parameter and returns a floating-point value indicating the current price of the stock. If the designer of the web service chose to return a simple floating-point number, then the web service proxy class would have a corresponding method like this:

public float quoteForSymbol(String symbol)

If instead the designer of the web service thought it useful to return multiple pieces of information as the result, then the service's WSDL file would include a named structure definition describing the multiple elements it contains. For example, assume that the service returns both the symbol name and the current price as a result. To contain these two data elements, the WSDL file might define a structure named QuoteInfo with an element named symbol of string type and an element named price of floating-point type. In this situation, when JDeveloper generates the web service proxy class, the Java method signature would instead look like this:

public QuoteInfo quoteForSymbol(String symbol)

The QuoteInfo return type references one of the auxiliary classes that comprises the web service proxy implementation. It is a simple bean whose properties reflect the names and types of the structure defined in the WSDL document. In a similar way, if the web service accepts parameters whose values are structures or arrays of structures, then you will work with these structures in your Java code using the corresponding generated beans.

13.2.4 What Happens at Runtime: When You Call a Web Service Using a Web Service Proxy Class

When you invoke a web service from an application module, the web service proxy class handles the lower-level details of using the XML-based web services protocol described in SOAP. In particular, it does the following:

  • Creates an XML document to represent the method invocation

  • Packages any method arguments in XML

  • Sends the XML document to the service URL using an HTTP POST request

  • Unpackages the XML-encoded response from the web service

If the method you invoke has a return value, your code receives it as an appropriately typed object to work with in your application module code.

13.2.5 What You May Need to Know About Web Service Proxies

When you are implementing web service proxies in an application, you might want to use a try-catch block to handle web service exceptions or invoke an application module with a web service proxy class. The following sections contain additional information you might need to know about these and other features with regard to web service proxies.

13.2.5.1 Using a Try-Catch Block to Handle Web Service Exceptions

By using the generated web service proxy class, invoking a remote web service becomes as easy as calling a method in a local Java class. The only distinction to be aware of is that the web service method call could fail if there is a problem with the HTTP request involved. The method calls that you perform against a web service proxy should anticipate the possibility that the request might fail by wrapping the call with an appropriate try...catch block. Example 13-3 improves on the simpler example (shown in Section 13.2.1.3, "Calling a Web Service Method Using the Proxy Class in an Application Module") by catching the web service exception. In this case, it simply rethrows the error as a JboException, but you could implement more appropriate error handling in your own application.

Example 13-3 Wrapping Web Service Method Calls with a Try-Catch Block

// In YourModuleImpl.java
public void performSomeApplicationTask(String symbol) {
  // application-specific code here
  // :
  QuoteInfo quote = null;
  try {
    // Create an instance of the web service proxy class 
    StockQuoteServiceSoapHttpPortClient svc =
               new StockQuoteServiceSoapHttpPortClient();
    // Call a method on the web service proxy class and get the result
    quote = svc.quoteForSymbol(symbol);
  }
  catch (Exception ex) {
    throw new JboException(ex);
  }
  float currentPrice = quote.getPrice();
  // more application-specific code here
}

13.2.5.2 Separating Application Module and Web Services Transactions

You will use some web services to access reference information. However, other services you call may modify data. This data modification might be in your own company's database if the service was written by a member of your own team or another team in your company. If the web service is outside your firewall, of course the database being modified will be managed by another company.

In either of these situations, it is important to understand that any data modifications performed by a web service you invoke will occur in their own distinct transaction, unrelated to the application module's current unit of work. For example, if you have invoked a web service that modifies data and then you later call rollback() to cancel the pending changes in the application module's current unit of work, this has no effect on the changes performed by the web service you called in the process. You may need to invoke a corresponding web service method to perform a compensating change to account for your rollback of the application module's transaction.

13.2.5.3 Setting Browser Proxy Information

If the web service you need to call resides outside your corporate firewall, you need to ensure that you have set the appropriate Java system properties to configure the use of an HTTP proxy server. The Java system properties to configure are:

  • http.proxyHost — Set this to the name of the proxy server.

  • http.proxyPort — Set this to the HTTP port number of the proxy server (often 80).

  • http.nonProxyHosts — Optionally set this to a vertical-bar-separated list of servers not requiring the user of a proxy server (for example, localhost|127.0.0.1|*.yourcompany.com).

Within JDeveloper, you can configure an HTTP proxy server on the Web Browser and Proxy page of the Preferences dialog. When you run your application, JDeveloper includes appropriate -D command-line options to set these three system properties based on the settings you've indicated in this dialog.

13.2.5.4 Invoking Application Modules with a Web Service Proxy Class

If you use a web service proxy class to invoke an Oracle ADF service-based application module, you lose the ability to optimize the call when the calling component and the service you are calling are colocated. As an alternative, you can use the service interface approach described in Chapter 11, "Integrating Service-Enabled Application Modules."

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

13.3.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 13.2.5.3, "Setting Browser Proxy Information."

To create a web service data control:

  1. In the Application Navigator, right-click an application and choose New.

  2. In the New Gallery, expand Business Tier, select Web Services and then Web Service Data Control, and click OK.

  3. Follow the wizard instructions to complete creating the data control.

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

To change the endpoint for a web service data control:

  1. In the Application Navigator, select the .dcx file for the web service data control.

  2. In the Structure window, right-click the web service data control and choose Edit Web Service Connection from the context menu.

  3. In the Edit Web Service Connection dialog, make the necessary changes to the endpoint URL and port name.

  4. Click OK.

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

To refresh an operation in a web service data control:

  1. In the Application Navigator, select the .dcx file for the web service data control.

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

13.3.4 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 12.3.1, "How to Use the Data Controls Panel."

In the Data Controls panel, each data control object is represented by an icon. Table 13-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 13-1 Data Controls Panel Icons and Object Hierarchy for Web Services

Icon Name Description Used to Create...

Data control icon

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 12, "Using ADF Model in a Fusion Web Application."

Serves as a container for other objects and is not used to create anything

Collection icon

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 22, "Creating a Basic Databound Page."

For more information about using collections to create tables, see Chapter 23, "Creating ADF Databound Tables."

For more information about using master-detail relationships to create UI components, see Chapter 24, "Displaying Master-Detail Data."

For information about creating graphs, charts, and other visualization UI components, see Chapter 26, "Creating Databound ADF Data Visualization Components."

Forms, tables, graphs, trees, range navigation components, and master-detail components.

Attribute icon

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 22.2, "Using Attributes to Create Text Fields."

For information about creating lists, see Chapter 25, "Creating Databound Selection Lists and Shuttles."

Label, text field, date, list of values, and selection list components.

Attribute icon

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 38.1, "Creating Custom, Validated Data Types Using Domains."

Label, text field, date, list of values, and selection list components

Method icon

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.

For more information about using methods that accept parameters, see Section 28.2.2.2, "Using Parameters in a Method."

Command components

For methods that accept parameters: command components and parameterized forms

Method return icon

Method Return

Represents an object that is returned by a custom 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 either need to also create an invoke action as an executable, or drop the corresponding method as a button to invoke the method. For more information about executables, see Section 12.6.2.2, "Executable Binding Objects."

The same components as for collections and attributes.

For named criteria: query or quick query forms. For more information, see Chapter 27, "Creating ADF Databound Search Forms."

Data control operation icon

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, and Previous. Because the web service data control is not an updateable data control, you cannot use built-in operations like commit, rollback, and execute.

UI command components, such as buttons, links, and menus.

For more information, see Section 22.4, "Incorporating Range Navigation into Forms," and Section 22.5, "Creating a Form to Edit an Existing Record."

Parameter icon

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.


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

13.4.1 WS-Security Specification

The WS-Security specification unifies multiple security technologies to make secure web services interoperable between systems and platforms. You can view the specification at http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf.

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.

13.4.2 Using Key Stores

A web service data control can be configured for message-level security using either Java Key Store (JKS) or the Oracle Wallet. For information on setting up and using Oracle Wallet, see the Oracle Technology Network at http://www.oracle.com/technetwork.

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 Fusion Middleware Security and Administrator's Guide for Oracle Web Services.

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

To define security for a web service data control:

  1. In the Application Navigator, select the web service data control .dcx file.

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

  3. From the Ports dropdown list, select the port to which you want the specified policies are applied.

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

  5. From the Reliability dropdown list, select the reliability policy you want to use. If you leave this field blank, no reliability policy is used.

  6. From the Addressing dropdown list, select the addressing policy you want to use. If you leave this field blank, no addressing policy is used.

  7. In the Security list, you can optionally specify additional security policies to apply. To add a policy, click the Add security policy icon.

  8. In the Management list, you can optionally specify additional management policies to apply. To add a policy, click the Add management policy icon.

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

  10. You can optionally override properties for the policies in the Security list and the Management list by clicking Override Properties.

  11. 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 Fusion Middleware Security and Administrator's Guide for Oracle Web Services.