Creating a RESTful Web Service Reference

To utilize a RESTful Web service from your application, you must create a RESTful Web service reference.

To create a RESTful Web service reference:

1. Navigate to the Web Service References page. See "Accessing the Web Service References Page".
2. Click Create.
3. Select REST and click Next.
4. For REST Details, specify the following:
   
   1. Name - Enter a name to identify the reference.
   2. URL - Enter the URL endpoint of the Web service.
   3. Proxy - Enter a proxy to override the application proxy for this service (optional).
   4. HTTP Method - Choose the http method used for the request to the Web service. Select GET, HEAD, POST, PUT or DELETE.
   5. Basic Authentication - Select Yes to require HTTP Basic Authentication. Otherwise, select No.
   6. HTTP Headers - Enter the names of the HTTP headers to send with the request.
   7. Click Next.
5. For REST Input parameters, specify the following:
   
   1. Name - Enter the name of the input parameter expected by the method.
   2. Type - Select the input type.
   3. Click Add Parameter.
   4. Repeat steps a though c for each expected input.
   5. Click Next.
6. For REST Output parameters, specify the following:
   
   1. Output Format - Select XML or Text for the response format expected from the Web service.
   2. XPath to Output Parameters (XML only) - Enter an XPath expression to the relevant part of the response.
   3. Response Namespace (XML only) - Enter the namespace corresponding to the Response XPath.
   4. Parameter Delimiter (Text only)- Enter the character or sequence that separates parameters returned from the Web service. Use \n to indicate a new line and \t to indicate a tab character.
   5. New Record Delimiter (Text only) - Enter the character or sequence that determines a new record in a text response from the Web service. Use \nto indicate a new line and \t to indicate a tab character.
   6. Name - Enter the name of the output parameter returned by the method.
   7. Type - Select the output type.
   8. Click Add Parameter.
   9. Repeat steps f though h for each returned output parameter.
   Note:

   Click Test to send a request to a RESTful Web service and see the response. This test process will help you in specifying the appropriate Output parameters.
7. Click Create.

The Create Web Service Reference Success page appears. The Web service reference is added to the Web Service References Repository.

Creating a Web Service Reference Manually

To create a Web service reference manually:

1. Navigate to the Web Service References page. See "Accessing the Web Service References Page".
2. Click Create.
3. Select Manual and click Next.
   The Create/Edit Web Service page appears.
4. In Name, enter a name to identify the reference.
5. Under Service Description:
   
   1. URL - Enter the URL used to post the SOAP request over HTTP. This corresponds to the soap:address location of a service port in the WSDL.
   2. Action - Enter the intent of the SOAP HTTP request (optional). The value is a URI identifying the intent. SOAP places no restrictions on the format or specificity of the URI or requires that it is resolvable.
   3. Proxy - Enter a proxy to override the application proxy for this service.
   4. SOAP Version - Select 1.1 or 1.2.
   5. Basic Authentication - Choose whether the Web service requires authentication. Select Yes or No.
6. For SOAP Envelope, enter the SOAP envelope to be used for the SOAP request to the Web service.
   
   Note:

   You can reference items from session state in the SOAP envelope by using #ITEM_NAME# syntax.
7. For Store Response in Collection, enter the name of a collection to store the response (optional). The response is stored in the CLOB001 column.
8. Click Create.

The Web service reference is added to the Web Service References Repository.

Creating a Web Service Reference Based on a WSDL

When you create a Web service reference based on a WSDL, you must decide how to locate the WSDL. You can locate a WSDL in two ways:

• By searching a Universal Description, Discovery and Integration (UDDI) registry
• By entering the URL to the WSDL document

A UDDI registry is a directory where businesses register their Web services.

Creating a Web Service Reference by Searching a UDDI Registry

To create a Web service by searching a UDDI registry:

1. Navigate to the Web Service References page. See "Accessing the Web Service References Page".
2. Click Create.
3. Select Based on WSDL and click Next.
4. When prompted to search a UDDI registry to find a WSDL, click Yes then Next.
5. For UDDI Location, enter a URL endpoint to a UDDI registry and click Next.
6. For Search, specify the following:
   
   1. Search Type - Specify whether to search for a business name or a service name. You cannot search for both.
   2. Name - Enter the business name or service name to search for. Use the percent (%) symbol as a wildcard character.
   3. Optionally indicate if the search should be case-sensitive or an exact match.
   4. Click Search.
   5. When the search results appear, make a selection and click Next.
   A summary page appears describing the selected Web service.
7. Review your selection and click Next to continue.
   The URL to the WSDL document displays in the WSDL Location field.
8. Click Finish.

The Web service reference is added to the Web Service References Repository.

Creating a Web Service Reference by Specifying a WSDL Document

To create a Web service by specifying a URL to a specific WSDL document:

1. Navigate to the Web Service References page. See "Accessing the Web Service References Page".
2. Click Create.
3. Select Based on WSDL and click Next.
4. When prompted to search a UDDI registry to find a WSDL, click No then Next.
5. In WSDL Location, enter the URL to the WSDL document.
6. Click Finish.

The Web service reference is added to the Web Service References Repository.

Working with SSL Enabled Web Services

Secure Sockets Layer (SSL) is an industry standard protocol that uses RSA public key cryptography with symmetric key cryptography to provide authentication, encryption, and data integrity.

If the Web service that you need to interact with is SSL-enabled (that is, https displays in the URL to the Web service), you must create a wallet and configure Oracle Application Express to use the wallet. A wallet is a password-protected container that stores authentication and signing credentials (including private keys, certificates, and trusted certificates) needed by SSL.

Understanding Web Service References

To utilize Web services in Oracle Application Express, you create a Web service reference using a wizard. Web service references can be based on a Web Services Description Language (WSDL) document, RESTful style, or created manually by supplying information about the service.

When you create a Web service reference based on a WSDL, the wizard analyzes the WSDL and collects all the necessary information to create a valid SOAP message, including:

• The URL used to post the SOAP request over HTTP(S)
• A Universal Resource Identifier (URI) identifying the SOAP HTTP request
• Operations of the Web Service
• Input parameters for each operation
• Output parameters for each operation

When you create a Web service reference manually, you supply the necessary information to create a valid SOAP request, including:

• The URL used to post the SOAP request over HTTP(S)
• A Universal Resource Identifier (URI) identifying the SOAP HTTP request
• The SOAP envelope for the request, including any item substitutions
• Optionally the name of a collection to store the response from the Web service

When you create a RESTful Web service reference, you supply the necessary information about the structure of the request and response including:

• A Universal Resource Identifier (URI) identifying the RESTful request
• The HTTP method identifying the method of the Web service
• HTTP Headers, if required, that are part of the request
• The type of input expected by the Web service
• The format of the response and how to identify the response parameters
  

  Accessing the Web Service References Page

  You manage Web service references on the Web Service References page.
  To access the Web Service References page:
  

  1. On the Workspace home page, click the Application Builder icon.
  2. Select an application.
  3. Click Shared Components.
     The Shared Components page appears.
  4. Under Logic, click Web Service References.
     The Web Service References page appears.

  Specifying an Application Proxy Server Address

  If your environment requires a proxy server to access the Internet, you must specify a proxy server address on the Application Attributes page before you can create a Web service reference.
  To specify a proxy address for an application:
  

  1. On the Workspace home page, click the Application Builder icon.
  2. Select an application.
     Application home page appears.
  3. Click the Edit Application Properties button.
  4. Under Name, enter the proxy server in the Proxy Server field.
  5. Click Apply Changes.

Writing Java Class Based Web Services

Writing Java class based Web Services involves building a Java class that includes one or more methods. When a Web Services client makes a service request, Oracle Application Server Web Services invokes a Web Services Servlet that runs the method that implements the service request. There are very few restrictions on what actions Web Services can perform. At a minimum, Web Services generate some data that is sent to a client or perform an action as specified by a Web Service request.

This section shows how to write a stateful and a stateless Java Web Service that returns a string, "Hello World". The stateful service also returns an integer running count of the number of method calls to the service. This Java Web Service receives a client request and generates a response that is returned to the Web Service client.

The sample code is supplied on the Oracle Technology Network Web site,

http://otn.oracle.com/tech/java/oc4j/demos/1012/index.html

After expanding the Web Services demo.zip file, the Java class based Web Service is in the directory under webservices/demo/basic/java_services on UNIX or in\webservices\demo\basic\java_services on Windows.

Writing Stateless and Stateful Java Web Services

Oracle Application Server Web Services supports stateful and stateless implementations for Java classes running as Web Services, as follows:

• For a stateful Java implementation, Oracle Application Server Web Services uses a single Java instance to serve the Web Service requests from an individual client.
• For a stateless Java implementation, Oracle Application Server Web Services creates multiple instances of the Java class in a pool, any one of which may be used to service a request. After servicing the request, the object is returned to the pool for use by a subsequent request.

Defining a Java Class Containing Methods for the Web Service

Create a Java Web Service by writing or supplying a Java class with methods that are deployed as a Web Service. In the sample supplied in the java_services sample directory, the .ear file, ws_example.earcontains the Web Service source, class, and configuration files. In the expanded .ear file, the class StatefulExampleImpl provides the stateful Java service and StatelessExampleImpl provides the stateless Java service.

When writing a Java Web Service, if you want to place the Java service in a package, use the Java package specification to name the package. The first line of StatefulExampleImpl.java specifies the package name, as follows:

package oracle.j2ee.ws_example;

The stateless sample Web Service is implemented with StatelessExampleImpl, a public class. The class defines a public method, helloWorld(). In general, a Java class for a Web Service defines one or more public methods.

Example 3-1 shows StatelessExampleImpl.

The stateful sample Web Service is implemented with StatefulExampleImpl, a public class. The class initializes the count and defines two public methods, count() and helloWorld().

Example 3-2 shows StatefulExampleImpl.

Example 3-1 Defining A Public Class with Java Methods for a Stateless Web Service

package oracle.j2ee.ws_example;

public class StatelessExampleImpl {
    public StatelessExampleImpl() {
  }
  public String helloWorld(String param) {
    return "Hello World, " + param;
  }
}

Example 3-2 Defining a Public Class with Java Methods for a Stateful Web Service

package oracle.j2ee.ws_example;

public class StatefulExampleImpl {
  int count = 0;
  public StatefulExampleImpl() {
  }
  public int count() {
    return count++;
  }
  public String helloWorld(String param) {
    return "Hello World, " + param;
  }
}

A Java class implementation for a Web Service must include a public constructor that takes no arguments. Example 3-1 shows the public constructor StatelessExampleImpl() and Example 3-2 showsStatefulExampleImpl().

When an error occurs while running a Web Service implemented as a Java class, the Java class should throw an exception. When an exception is thrown, the Web Services Servlet returns a Web Services (SOAP) fault. Use the standard J2EE and OC4J administration facilities to view the logs of Servlet errors for a Web Service that uses Java classes for its implementation.

When you create a Java class containing methods that implement a Web Service, the method's parameters and return values must use supported types, or you need to use an interface class to limit the methods exposed to those methods using only supported types