33.5 Calling a Web Service from an Application Module

In a service-oriented architecture, sometimes your application module will need to take advantage of functionality offered by a web service. JDeveloper's built-in web services wizards make this an easy task. After creating a web service proxy class using the wizard, calling the service is as simple as calling a method in a local Java object.

33.5.1 Understanding the Role of the Web Services Description Language Document

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) described in Section 33.1.2, "WSDL", enables tools like JDeveloper to automatically 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.

In order to work with any web service, you will need to know the URL that identifies its WSDL document. This URL could be a file-based URL like:

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

if you have received the WSDL document as an email attachment, for example, and saved it to your local hard drive. Alternatively, the URL could be an HTTP-based URL like:

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

Some web services make their WSDL document available by using a special parameter to modify the actual service URL itself. So, for example, a web service that expects to receive requests at the HTTP address of:

http://somerserver.somecompany.com/SomeService

might publish the corresponding WSDL document using the same URL with an additional parameter on the end like this:

http://somerserver.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 that URL in hand, you can then create a web service proxy class to call the service.

33.5.2 Understanding the Role of the Web Service Proxy Class

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.

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.

33.5.3 How to Call a Web Service from an Application Module

To call a web service from an application module, you perform three steps:

Create a web service proxy class for the web service.
Create an instance of the web service proxy class in your application module.
Invoke one or more methods on the web service proxy object.

33.5.3.1 Creating a Web Service Proxy Class for a Web Service

To create a web service proxy class for a web service you need to call, use the Create Web Service Proxy wizard. You'll find it in the Business Tier > Web Services category of the New Gallery. When the wizard appears, follow these steps:

In step 1on the Web Service Description page, enter the URL for the WSDL document that describes the service, then press [Tab].

For example, if the service is created to comply with the latest JAXRPC standard and deployed to an Oracle Application Server, the WSDL URL might look like this:
```
http://someserver:8888/StockQuoteService/StockQuoteServiceSoapHttpPort?WSDL
```
If the wizard displays the Next > button enabled, then JDeveloper has recognized and validated the WSDL document. You can click it and proceed to step 3. If the 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 try step 1 again.
In step 5 on the Default Mapping Options page, choose a Java package name for the generated web service proxy class, then click Finish.

33.5.3.2 Understanding the Generated 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 nice, human-readable name like StockQuoteService, or could be a less-friendly name like StockQuoteServiceSoapHttpPort. This port name is decided by the developer that published the web service you are using. Assuming that the port name of the service is StockQuoteServiceSoapHttpPort, JDeveloper will 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 above 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 will use to invoke the server, JDeveloper generates a number of auxiliary classes and interfaces. You can see these files in the Structure window by selecting the web service proxy node in the Application Navigator. The generated files are used as part of the lower-level implementation of invoking the web service.

The only auxiliary generated classes you will 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 will include a named structure definition describing the multiple elements it contains. For example, assume 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 will look like this instead:

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.

33.5.3.3 Calling a Web Service Method Using the Web Service Proxy Class

Once you've generated the web service proxy class, you can use it inside a custom method of your application module as shown in Example 33-11.

Example 33-11 Calling a Web Service Method Using the Web Service Proxy Class

// 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
}

33.5.4 What Happens When You Call a Web Service from an Application Module

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 Section 33.1.1, "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.

33.5.5 What You May Need to Know

33.5.5.1 Use 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 real 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 33-12 improves on the simpler example shown above by implementing the best practice of 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 33-12 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
}

33.5.5.2 Web Services are Do Not Share a Transaction with the Application Module

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 that is 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.

33.5.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 (e.g. "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 IDE Preferences dialog. When you run your application, JDeveloper includes appropriate -D command-line options to set the above three system properties based on the settings you've indicated in this dialog.