Skip Headers

Oracle9iAS Containers for J2EE JSP Tag Libraries and Utilities Reference
Release 2 (9.0.3)
Part Number A97678-01
Go To Core Documentation
Core		 Go To Platform Documentation
Platform		 Go To Table Of Contents
Contents		 Go To Index
Index

Go to previous page Go to next page

10
Web Services Tags

Oracle furnishes a tag library with OC4J that enables developers to create JSP pages for use as client programs for Web services.

This chapter describes the tag library and is organized as follows:

This chapter is written with the assumption that you are already familiar with Web services, Simple Object Access Protocol (SOAP), and the Web Services Definition Language (WSDL); however, some overview is provided here. There are also references to additional documents, including related specifications from the World Wide Web Consortium (W3C).

The OC4J Web services tag library is based on Oracle9iAS Web Services. See the Oracle9iAS Web Services Developer's Guide for information.

Overview of Web Services

This section provides a quick overview of Web services concepts, covering the following topics:

General Web Services Overview

Web services are sets of procedures, or actions, that can be invoked by a client over the Internet. For example, there might be a "World Cup Soccer" service that consists of actions to get scores, schedules, and standings.

A Web service must have the following features:

For more information about Web services, particularly Oracle9iAS Web Services, you can refer to the Oracle9iAS Web Services Developer's Guide.

For related specifications, refer to the following Web sites:

http://www.w3.org/TR/SOAP (W3C SOAP specification)

http://www.w3.org/TR/wsdl (W3C WSDL specification)

http://www.uddi.org/specification.html (UDDI specification)

Overview of SOAP and Related Features

This section offers a brief overview of SOAP. See the W3C Simple Object Access Protocol (SOAP) 1.1 specification for details.

SOAP is a lightweight, XML-based protocol for exchanging typed and structured data over the Internet or other distributed environments. Among other features, SOAP supports remote procedure call (RPC) and message-oriented data exchanges.

In a message-oriented implementation, data is exchanged through a modular packaging and encoding model. A message is a WSDL component that specifies input data parts and output data parts associated with an operation. See "Overview of Web Service Messages and XML Schema Definitions" for more information.

RPC is an alternative to sockets, with the communication interface being at the level of procedure calls. It is as though you are calling a local procedure, but arguments of the call are actually packaged and sent to a remote target. The RPC mechanism uses a request/response methodology, where an end-point receives a procedure-oriented message and sends back a corresponding response.

Using SOAP with RPC is independent of the protocol binding. Where HTTP is the protocol binding, HTTP requests correspond to RPC calls, and HTTP responses correspond to RPC responses.

Key aspects of SOAP include the following:

Overview of Web Services Definition Language Key Elements

A Web service is described using the XML-based Web Services Definition Language, in a WSDL (.wsdl) document.

Here are some key WSDL terms:

The WSDL specification outlines the general structure of a WSDL document, which includes the following key elements. Refer to the W3C Web Services Description Language (WSDL) 1.1 specification for complete information.

Overview of Web Service Messages and XML Schema Definitions

Messages define parameters used by the operations, or methods, of a Web service. A message is a typed definition of the data being communicated, consisting of one or more parts. Each part corresponds to a logical entity, such as a "Purchase Order" part and an "Invoice" part. For each part, there are type specifications for the associated data items.

In a SOAP-based implementation, such as for Oracle9iAS Web Services, the data types used by a message are defined through the XML Schema Definition (XSD) language, which supports predefined simple types as well as user-defined complex types.

With an implementation that uses XSD, the syntax for defining a message is as follows: 

   <message name="nmtoken">
      <part name="nmtoken" [type="qname"] [element="qname"] />
   </message>

In this syntax, the element attribute refers to where an XSD complex type is defined using XSD syntax, the type attribute indicates an XSD simple type, "nmtoken" indicates a standard XML name token, and "qname" indicates a standard XML qualified name. There can be zero or more messages, and zero or more parts for each message.

For a SOAP encoding style of encoded, only simple types are allowed, so the element attribute is not used. For an encoding style of literal, you can have simple types or complex types, so a <part> element can use either the type attribute or the element attribute, but not both.

Here is an example of a message definition, from "Example: WSDL Definition": 

   <message name="GetLastTradePriceInput">
      <part name="body" element="xsd1:TradePriceRequest"/>
   </message>

GetLastTradePriceInput is the name of the message, which is an input message (as the name implies). In this case, the element attribute refers to a namespace where a complex type, TradePriceRequest, is defined. Here is an example of such a definition (also part of "Example: WSDL Definition" below): 

   <element name="TradePriceRequest">
      <complexType>
         <all>
             <element name="tickerSymbol" type="string"/>
             <element name="companyName" type="string"/>
         </all>
      </complexType>
   </element>

An XML schema primer is available from W3C at the following location: 

http://www.w3.org/TR/xmlschema-0/

Web Service Example

This example shows the WSDL definition of a Web service, and illustrates its input and output messages embedded in an HTTP request and HTTP response, respectively.

Example: WSDL Definition

The W3C Web Services Description Language (WSDL) 1.1 specification provides the following example of a WSDL document, which defines a stock quote service that takes a ticker symbol as input and returns the current stock price as output. Note this uses a SOAP encoding style of literal, so complex types are allowed (and used). 

<?xml version="1.0"?>
<definitions name="StockQuote"

targetNamespace="http://example.com/stockquote.wsdl"
          xmlns:tns="http://example.com/stockquote.wsdl"
          xmlns:xsd1="http://example.com/stockquote.xsd"
          xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
          xmlns="http://schemas.xmlsoap.org/wsdl/">

   <types>
      <schema targetNamespace="http://example.com/stockquote.xsd"
              xmlns="http://www.w3.org/2000/10/XMLSchema">
         <element name="TradePriceRequest">
            <complexType>
               <all>
                  <element name="tickerSymbol" type="string"/>
               </all>
            </complexType>
         </element>
         <element name="TradePrice">
            <complexType>
               <all>
                  <element name="price" type="float"/>
               </all>
            </complexType>
         </element>
      </schema>
   </types>

   <message name="GetLastTradePriceInput">
      <part name="body" element="xsd1:TradePriceRequest"/>
   </message>

   <message name="GetLastTradePriceOutput">
      <part name="body" element="xsd1:TradePrice"/>
   </message>

   <portType name="StockQuotePortType">
      <operation name="GetLastTradePrice">
         <input message="tns:GetLastTradePriceInput"/>
         <output message="tns:GetLastTradePriceOutput"/>
      </operation>
   </portType>

   <binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">
      <soap:binding style="document" 
                    transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="GetLastTradePrice">
         <soap:operation soapAction="http://example.com/GetLastTradePrice"/>
            <input>
               <soap:body use="literal"/>
            </input>
            <output>
               <soap:body use="literal"/>
            </output>
      </operation>
   </binding>

   <service name="StockQuoteService">
      <documentation>My first service</documentation>
         <port name="StockQuotePort" binding="tns:StockQuoteBinding">
            <soap:address location="http://example.com/stockquote"/>
          </port>
   </service>

</definitions>

This WSDL definition first specifies the GetLastTradePriceInput and GetLastTradePriceOutput input and output messages, next ties them to the operation GetLastTradePrice, then defines a binding and a port for that operation.

Notes:

  • This example has all aspects of the Web service definition, including the XML schema definitions for data exchanges, in the same document. Alternatively, stockquote.xsd, for example, could be a separate XSD document instead of a namespace within this document. The W3C WSDL specification illustrates this. Be aware, however, that the OC4J Web services tag library does not support WSDL documents that use <import> elements to import other WSDL documents.

  • The example uses a document-style binding. Be aware that the OC4J Web services tag library implementation supports only RPC-style bindings as of Oracle9iAS release 2 (9.0.3).

Example: SOAP Messages Embedded in HTTP Request and Response

Corresponding to the Web service defined in the preceding example, this section shows what the messages would look like--the soap-enveloped input message embedded in an HTTP request, and the soap-enveloped output message embedded in an HTTP response. These examples are also from the W3C Web Services Description Language (WSDL) 1.1 specification.

Here is a request: 

POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "SOAP_URI"

   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Body>
         <m:GetLastTradePrice xmlns:m="xmlns_URI">
            <m:tickerSymbol>DIS</m:tickerSymbol>
         </m:GetLastTradePrice>
      </soapenv:Body>
   </soapenv:Envelope>

In this example, xmlns_URI is a URI to the location where the GetLastTradePrice operation and its messages are defined, such as the WSDL document in the preceding "Example: WSDL Definition". This is also where tickerSymbol is defined. The request is for a stock quote for Walt Disney Co. SOAP_URI is the URI for the SOAP action HTTP header for the HTTP binding of SOAP.

And here is the response: 

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Body>
         <m:GetLastTradePriceResponse xmlns:m="Some_URI">
            <m:price>34.5</m:price>
         </m:GetLastTradePriceResponse>
      </soapenv:Body>
   </soapenv:Envelope>

By convention, the response for an operation Xxxx is called XxxxResponse.

OC4J Web Services Tags

This section provides an overview and details of the Web services tag library, as well as an overview of Oracle9iAS Web Services, upon which the tag library implementation is based. The section is organized as follows:

Overview of Oracle9iAS Web Services and the Tag Library Implementation

The Web services tag library provided with OC4J enables developers to conveniently create JSP pages for Web service client applications. The implementation uses a SOAP-based, RPC-style mechanism. A client application would access the WSDL document, and then use the WSDL information to access the operations of a Web service.

The tag library also uses the Oracle implementation of the dynamic invocation API, described in the Oracle9iAS Web Services Developer's Guide. When a client application acquires a WSDL document at runtime, the dynamic invocation API is the vehicle for invoking any SOAP operation described in the WSDL document. The tag handler uses the API in sending a SOAP request that invokes a Web service, and in handling the SOAP response.

The Oracle dynamic invocation API consists of classes and interfaces in the oracle.j2ee.ws.client and oracle.j2ee.ws.client.wsdl packages.

The oracle.j2ee.ws.client package includes the following:

The oracle.j2ee.ws.client.wsdl package includes the following:

Overview of Web Services Tag Functionality

This section provides an overview of the OC4J Web services tag library and its functionality. The tag library includes support for binding to a Web service, using a Web service operation through SOAP requests and SOAP responses, defining input and output message parts, mapping SOAP/XML data types to Java types, and setting custom properties for use by the client application.

The tag library supports invoking operations defined in WSDL documents that use the W3C XML schema version whose namespace is the following: 

http://www.w3.org/2001/XMLSchema

The Web services tag library includes the webservice tag, optionally with nested map and property tags, and the invoke tag, optionally with nested part tags. They are used as follows.

Web Services Tag Descriptions

This section supplies detailed descriptions of the OC4J Web services tags, including syntax documentation:

The Web services tag library, a standards-compliant JavaServer Pages tag library implementation, is included in the ojsputil.jar file, which is provided with OC4J. Verify that this file is installed and in your classpath.

To use the Web services tag library, the tag library descriptor file, wstaglib.tld, must be deployed with the application, and any JSP page using the library must have an appropriate taglib directive. In an Oracle9iAS installation, the TLD file is in the "well-known" tag library directory. Refer to the Oracle9iAS Containers for J2EE Support for JavaServer Pages Developer's Guide for information about taglib directives and the well-known tag library directory.

For an example that uses the tags described in this section, see "Web Services Tag Examples".

Notes:

  • The prefix "ws:" is used in the tag syntax here. This is by convention, but is not required. You can specify any desired prefix in the taglib directive.

  • See "Tag Syntax Symbology and Notes" for general information about tag syntax conventions in this manual.

Web Services webservice Tag

Use this tag to create a Web service proxy--an instance of a class that implements the oracle.j2ee.ws.client.WebServiceProxy interface. The tag requires the URL of a WSDL document and uses a binding and SOAP location or a service name and port, as follows:

  1. First, if tag attributes provide a binding and SOAP location, the tag handler uses them in creating the proxy. (Tag attributes for service name and port are ignored in this case.)

  2. If no binding and SOAP location are provided, the tag handler uses a service name and port, as follows:

    1. If a service name and port are provided through tag attributes, then the tag handler uses them in creating the proxy.

    2. If no service name and port are provided, the tag handler uses the first service in the WSDL document, and the first port listed for that service.

Using a binding and SOAP location is particularly useful for a Web service whose WSDL document is accessed through a UDDI registry. In that case, the binding and location can be determined through UDDI queries and supplied to the tag through request-time expressions.

After the Web service proxy is created, it will use any nested map tags to add entries to the SOAP mapping registry. See the next section, "Web Services map Tag".

Syntax

<ws:webservice wsdlUrl = "WSDL_URL_of_Web_service"
             [ id = "variable_name_for_Web_service_proxy" ]
             [ scope = "page" | "request" | "session" | "application" ]
             [ binding = "SOAP_binding_information" ]
             [ soapLocation = "SOAP_endpoint_URL" ]
             [ service = "service_name_in_WSDL" ]
             [ port = "port_name_for_service" ] 

...body / nested tags...

</ws:webservice>

Note:

The scope attribute cannot take request-time expressions.

Attributes

Web Services map Tag

For interoperability, a mapping mechanism is necessary to map WSDL-defined SOAP/XML data types to the Java types used in JSP pages of a Java client application. This is possible through the Oracle9iAS Web Services SOAP mapping registry.

You can have any number of map tags nested within a webservice tag, to have the Web service proxy add entries to the registry. Use one map tag for each desired type mapping.

The registry is an instance of the XMLJavaMappingRegistry class of the org.apache.soap.util.xml package. A WebServiceProxy instance has a getXMLMappingRegistry() method to access the registry.

The map tag includes attributes to specify the encoding style, serializer, deserializer, and namespace URI to facilitate the type mapping. The Web services tag library supports custom serializers and deserializers, if you want to create your own.

Important:

When using a map tag, you must nest it within a webservice tag.

Syntax

<ws:map localName = "local_name_of_SOAPXML_type"
        namespaceUri = "URI_of_namespace_for_SOAPXML_type"
        javaType = "Java_type_to_map"
        encodingStyle = "URL_of_SOAP_encoding_style"
        java2xmlClassName = "Java_to_XML_serializer"
        xml2javaClassName = "XML_to_Java_deserializer" />
Attributes

Web Services property Tag

You can optionally use this tag to specify a name/value pair that defines any of several supported custom properties for use by the Web service client application. For example, you could use property tags to specify an HTTP proxy host and proxy port if a proxy is required for access through a network firewall. The following properties are supported:

Syntax

<ws:property name="http.proxyHost" | "http.proxyPort" | "javax.net.ssl.KeyStore"
            value = "property_value" />
Attributes

Web Services invoke Tag

Use this tag to invoke an operation of the Web service. The tag handler will call the remote Web service operation by passing an input message in a SOAP request, then will wait for the SOAP response. You must specify the operation, and an object ID for the object that will contain the returned response. The tag handler uses the operation name to find the operation in the WSDL document.

The invoke tag gains access to a Web service proxy in one of two ways:

In a situation where there are overloaded operations--two operations of the same name using different I/O messages--the invoke tag has attributes to specify the input and output message names for the desired operation. In this case, the specified input and output message names are used to form the RPC signature of the operation. Otherwise, the RPC signature is the default according to the WSDL document.

If the output message has multiple parts, then the returned result is an array of message parts (all within a single SOAP response).

Important:

Waiting for the SOAP response is a blocking function.

Syntax

<ws:invoke id = "variable_name_for_output_result"
           operation = "operation_to_invoke"
         [ webservice = "variable_name_of_Web_service_proxy" ]
         [ inputMsgName = "name_of_input_message" ]
         [ outputMsgName = "name_of_output_message" ]

...body / nested tags...

</ws:invoke>
Attributes

Web Services part Tag

Use this tag if the operation being performed requires input message part values, using one part tag for each input part.

Important:

When using a part tag, you must nest it within an invoke tag.

Syntax

<ws:part name = "part_name"
         value = "part_value" />
Attributes

Web Services Tag Examples

This section provides two examples--a template for use of the tag library, and a concrete JSP page example.

Web Services Example: Usage Template

<HTML>
<HEAD>
<TITLE>Title</TITLE>
</HEAD>
<BODY>
<H2>This is sample HTML text.</H2>
<%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ws/WsTagLibrary.tld"
           prefix="ws" %>
<ws:webservice id="myws" 
               wsdlUrl="wsdlurl" 
               {
                  binding="" soapLocation="" | service="" port=""
               }
               {
                  scope="page | request | session | application"
               }
                >
   <ws:property name="property" value="string"/>

   <ws:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
           localname="SOAPStruct"
           namespaceUri="http://soapinterop.org/xsd"
           javaType="MySoapStructBean"
           java2xmlClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
           xml2javaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
    />

</ws:webservice>

<ws:invoke id="result" webservice="myws" operation="add" inputMsgName=""
           outputMsgName=""> 
   <ws:part name="part_name" value="{string | <%= expression %>}"/>
</ws:invoke>

<% =result %>
</BODY>
</HTML>

Web Services Example: Sample JSP Page

<%@ page contentType="text/html"%>
<%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ws/wstaglib.tld"
           prefix="ws" %>
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; ">
</HEAD>
<BODY>
<%
 String itemID = request.getParameter("itemID");
%>
<ws:webservice id="ebay" 
    wsdlUrl="http://www.xmethods.net/sd/2001/EBayWatcherService.wsdl"
    binding="eBayWatcherBinding"
    soapLocation="http://services.xmethods.net:80/soap/servlet/rpcrouter"
    scope="page">
  <ws:property name="http.proxyHost" value="www-proxy.us.oracle.com"/>
  <ws:property name="http.proxyPort" value="80"/>
</ws:webservice>
<ws:invoke id="price" webservice="ebay" operation="getCurrentPrice">
  <ws:part name="auction_id" value="<%=itemID%>"/>
</ws:invoke>
<B>
Action price for eBay Item # <%=itemID%> is :
</B>
<P>
$<%= price%> 
@ 
<%= new java.util.Date()%>
</P>
</BODY>
</HTML>

Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.
All Rights Reserved.
Go To Core Documentation
Core		 Go To Platform Documentation
Platform		 Go To Table Of Contents
Contents		 Go To Index
Index