Implementing Web Services

Web services enable applications to interact with one another over the Web in a platform-neutral, language independent environment. In a typical Web services scenario, a business application sends a request to a service at a given URL by using the protocol over HTTP. The service receives the request, processes it, and returns a response. You can incorporate calls with external Web services in applications developed in Application Builder.

Web services are typically based on Simple Object Access Protocol (SOAP) or Representational State Transfer (REST) architectures. SOAP is a World Wide Web Consortium (W3C) standard protocol for sending and receiving requests and responses across the Internet. SOAP messages can be sent back and forth between a service provider and a service user in SOAP envelopes. RESTful Web services are resource oriented. The scope of the Web service is found in the URI and the method of the service is described by the HTTP method that is used such as GET, POST, PUT, HEAD, and DELETE.

SOAP offers two primary advantages:

• SOAP is based on XML, and therefore easy to use.
• SOAP messages are not blocked by firewalls because this protocol uses simple transport protocols, such as HTTP.
  
  
  REST offers similar advantages:
• REST messages are also not blocked by firewalls because this protocol uses the HTTP protocol.
• REST requests do not require the overhead of XML and SOAP envelopes and inputs are typically provided in the URI.

Topics:

• Understanding Web Service References
• Working with SSL Enabled Web Services
• Creating a Web Service Reference Based on a WSDL
• Creating a Web Service Reference Manually
• Creating a RESTful Web Service Reference
• Using the Web Service Reference Repository
• Testing a Web Service Reference Created from a WSDL
• Testing a Web Service Reference Created Manually
• Testing a REST Web Service Reference
• Creating an Input Form and Report on a Web Service
• Creating a Form on a Web Service
• Invoking a Web Service as a Process
• Editing a Web Service Process
• Viewing a Web Service Reference History
• Exposing a Report Region as a RESTful Web Service

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.

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.

Mapping of SQL Types

Although Oracle Application Server does not currently support LOB types, XMLTYPE, REF CURSORS, and OUT/IN OUT arguments (they will be addressed in future releases), you can use an alternative approach to expose PL/SQL methods and SQL types as Web services.

You can change JPublisher's default behavior to generate code that uses a user-provided subclass. For example, if you have a PL/SQL method that returns a REF CURSOR, JPublisher automatically maps the return type to java.sql.ResultSet. However, this ResultSet type cannot be published as a Web service. To solve this, simply create a new method that can return the result set in a Web service-supported format, such as:

public String [] readRefCursorArray(String arg1, Integer arg2)
  {java.sql.ResultSet rs = getRefCursor(arg1,arg2);
    ... create a String[] from rs and return it... }

Then create an interface that contains the exact methods to publish. You can use JPublisher to easily accomplish this mapping by using the following:

jpub -sql=MYAPP:MyAppBase:MyApp#MyAppInterf...

where:

• MyApp contains the method to return the result set.
• MyAppInterf is the interface that contains the method to publish.

After translating the code for your application, archive all the class files into a single JAR file and use the Web Services Assembler to create a deployable Web service EAR file

EJB Tutorial from JBoss: turn EJB to web service

File: Calculator.java
/*
 * JBoss, Home of Professional Open Source.
 * Copyright 2006, Red Hat Middleware LLC, and individual contributors
 * as indicated by the @author tags. See the copyright.txt file in the
 * distribution for a full listing of individual contributors.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package org.jboss.tutorial.webservice.bean;
import javax.jws.WebService;
import javax.jws.WebMethod;
import java.rmi.Remote;
import java.rmi.RemoteException;
import javax.jws.soap.SOAPBinding;
import javax.jws.soap.SOAPBinding.Style;
@WebService
@SOAPBinding(style=Style.RPC)
public interface Calculator extends Remote
{
   @WebMethod int add(int x, int y);
   @WebMethod int subtract(int x, int y);
}
 
File: CalculatorBean.java
/*
 * JBoss, Home of Professional Open Source.
 * Copyright 2006, Red Hat Middleware LLC, and individual contributors
 * as indicated by the @author tags. See the copyright.txt file in the
 * distribution for a full listing of individual contributors.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package org.jboss.tutorial.webservice.bean;
import javax.ejb.Stateless;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import javax.jws.soap.SOAPBinding.Style;
@Stateless
@WebService(endpointInterface="org.jboss.tutorial.webservice.bean.Calculator")
public class CalculatorBean
{
   public int add(int x, int y)
   {
      return x + y;
   }
   public int subtract(int x, int y)
   {
      return x - y;
   }
}
File: Client.java
/*
 * JBoss, Home of Professional Open Source.
 * Copyright 2006, Red Hat Middleware LLC, and individual contributors
 * as indicated by the @author tags. See the copyright.txt file in the
 * distribution for a full listing of individual contributors.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package org.jboss.tutorial.webservice.client;
import org.jboss.tutorial.webservice.bean.Calculator;
import javax.xml.namespace.QName;
import javax.xml.rpc.Service;
import javax.xml.rpc.ServiceFactory;
import java.net.URL;
import java.io.File;
public class Client
{
   public static void main(String[] args) throws Exception
   {
      URL url = new URL("http://localhost:8080/tutorial/CalculatorBean?wsdl");
      QName qname = new QName("http://bean.webservice.tutorial.jboss.org/jaws",
              "CalculatorService");
      ServiceFactory factory = ServiceFactory.newInstance();
      Service service = factory.createService(url, qname);
      Calculator calculator = (Calculator) service.getPort(Calculator.class);
      System.out.println("1 + 1 = " + calculator.add(1, 1));
      System.out.println("1 - 1 = " + calculator.subtract(1, 1));
   }
}