About Web Services
Web Services provide a standard means of interoperating between different software applications, running on a variety of platforms and/or frameworks. This section begins with a description of the major components and concepts of a Web Service. Later, we describe these concepts within the EGO context.
Web Service Components
XML
XML is used in the Web Services architecture as the platform-independent format for transferring information between the Web Service and the Web Service client. The XML format ensures uniform data representation and exchange. XML 1.0 was released as a W3C Recommendation; refer to document REC-xml-19980210 for further information.
WSDL
The Web Services Description Language (WSDL) describes the message syntax associated with the invocation and response of a Web Service. A WSDL file is an XML document that defines the Web Service operations and associated input/output parameters. In a way, the WSDL can be considered a contract between the Web Services client and the Web Services server.
Basically, a WSDL document describes three fundamental properties of a Web Service:
- The operations (methods) that the service provides including input arguments needed to invoke them and the response.
- Details of the data formats and protocols required to access the service's operations.
- Service location details such as a URL.
WSDL 1.1 was suggested in a note to W3C as an XML format for describing Web Services; refer to http://www.w3.org/TR/2001/NOTE-wsdl-20010315.
XML Schema
XML schemas are used to specify the structure of WSDL documents and the data type of each element/attribute. XML schemas describe the documents that serve as the body of the SOAP messages traversing the EGO Web Service interface. XML Schema was approved as a W3C Recommendation; refer to http://www.w3.org/TR/xmlschema-1/.
SOAP
SOAP is the protocol used for communication between the Web Service and the client application. SOAP uses the Hypertext Transfer Protocol (HTTP or HTTPS) as the underlying protocol for transporting the data. SOAP 1.1 was suggested in a note to W3C as a protocol for exchanging information in a distributed environment. The EGO Web Services implementation supports SOAP version 1.2; refer to http://www.w3.org/TR/soap12-part1/.
Web Service gateway
The Web Service gateway is a runtime component of Platform EGO. The gateway provides a standards-based Web Services interface for Web Service clients to access EGO functionality. The Web Service client sends its request to the gateway via SOAP protocol. The gateway calls the EGO C APIs in order to perform the required operations on behalf of the Web Service client and returns the results.
A closer look at an EGO WSDL and schema
This section looks at some key features of the EGO WSDLs and schemas.
SOAP binding style
SOAP supports two invocation models: Remote Procedure Calls (RPC) and document style.
In the RPC-style model, clients invoke the Web Service by sending parameters and receiving return values that are wrapped inside the SOAP body. These procedure calls are synchronous, which means that the client sends the request and waits for the response.
In the document style model, the client sends the parameters to the Web Service within an XML document. The Web Service receives the entire document, processes it and possibly returns a response message. Using the document style, the body of the SOAP message is interpreted as straight XML. Hence, this combination of sending a document with a literal XML infoset as a payload is referred to as document/literal. This is opposed to the RPC style that uses RPC conventions for the SOAP body as defined in the SOAP specification. One advantage of using the document-centric approach is that document messaging rules are more flexible than the RPC style, which allows for changes to the XML schema without breaking the calling applications.
The type of binding model that is implemented is determined by an attribute in the WSDL. The style attribute within the SOAP protocol binding can be set to either rpc or document. Here is an example of WSDL binding element that is set to document style.
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>Here is an example of the encoding technique that is specified on the soap:body element's use attribute. In this case, it is set to literal.
<wsdl:input> <soap:body parts="RequestAllocationRequest" use="literal"/> </wsdl:input>The Java code samples provided in the SDK use document style binding and that is why a document must be created for the request and response messages.
Passing parameters to a Web Service
The following example shows a portion of the WSDL file for the EGO MonitoringService Web Service and its associated schema file.
... <wsdl:types> <xsd:schema targetNamespace="http://www.platform.com/ego/2005/05/wsdl/monitoring" elementFormDefault="qualified"> ... <xsd:element name="ResourceInfoRequest"> <xsd:complexType> <xsd:sequence> <xsd:element ref="ego:ResourceRequirement" minOccurs="0" /> <xsd:element ref="ego:ResourceName" minOccurs="0" maxOccurs="unbounded" /> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="ResourceInfoResponse"> <xsd:complexType> <xsd:sequence> <xsd:element ref="ego:Resource" minOccurs="0" maxOccurs="unbounded"/> </xsd:sequence> </xsd:complexType> </xsd:element> ... <wsdl:message name="ResourceInfoRequestMessage"> <wsdl:part element="tns:ResourceInfoRequest" name="ResourceInfoRequest" /> </wsdl:message> <wsdl:message name="ResourceInfoResponseMessage"> <wsdl:part element="tns:ResourceInfoResponse" name="ResourceInfoResponse" /> </wsdl:message> ... <wsdl:portType name="MonitoringPortType"> ... <wsdl:operation name="ResourceInfo"> <wsdl:input message="tns:ResourceInfoRequestMessage"> </wsdl:input> <wsdl:output message="tns:ResourceInfoResponseMessage"> </wsdl:output> </wsdl:operation>The operation name used in the example in this section is ResourceInfo. This operation takes a single input argument defined as a message of type ResourceInfoRequestMessage. Now we need to determine the number of parameters in this message and their data types.
In the message element named ResourceInfoRequestMessage, the part element is named ResourceInfoRequest. If you look up this message in the types element, you will find it contains two parameters: ResourceRequirement and ResourceName.
<xsd:element name="ResourceName" type="xsd:string"> </xsd:element> <xsd:element name="ResourceRequirement" type="xsd:string"> </xsd:element>In the schema file, you can see that the ResourceName and ResourceRequirement parameters have string data types. When you call the ResourceInfo operation, you pass both parameters as input.
Return values from a Web Service
Web Service operations often return information back to the client application. You can determine the name and data type of returned information by examining the WSDL and schema files for the Web Service.
Referring to the previous portion of the WSDL file for the EGO MonitoringService Web Service, we find that the operation named ResourceInfo returns a message of type ResourceInfoResponseMessage. In the message element named ResourceInfoResponseMessage, the part element is named ResourceInfoResponse. If you look up this message in the types element, you will find it contains a return argument called Resource. In the schema file, you can see that the Resource parameter has a complex data type. Complex data types are serialized as XML and returned from the Web Service as the result. The variable used to store the result must match the structure of the complex data type.
<xsd:element name="Resource"> <xsd:complexType> <xsd:sequence> <xsd:element ref="ego:ResourceState" minOccurs="0"/> <xsd:element ref="ego:ConsumableAttribute" minOccurs="0"/> <xsd:element ref="ego:Attribute" minOccurs="0" maxOccurs="unbounded"/> <xsd:any namespace="##other" minOccurs="0" processContents="lax"/> </xsd:sequence> <xsd:attribute name="ResourceName" type="xsd:string" use="required"/> <xsd:attribute name="ResourceType" type="xsd:anyURI"/> </xsd:complexType> </xsd:element>
Building a Web Service client
A Web Services client is an application capable of sending and receiving SOAP messages. Such an application serializes or deserializes the SOAP messages to a programming language type system enabling programmatic processing.
Here is the sequence for invoking a Web Service:
- Client serializes the arguments of the method call into the XML payload of the SOAP message
- Send the message to the Web Service
- Wait for a response (or timeout)
- Deserialize the XML payload in the response message to a local type/structure
- Return that type/structure as a value from the method call.
Using Axis2 to Develop Java Web Service Clients
As a client to a Web Service, encoding your requests in XML to the Web Service and decoding the responses you get back would be tedious (not to mention implementing the logic that deals with accepting requests and sending responses).
Apache Axis2 is an implementation of the SOAP protocol and it shields the developer from the details of dealing with SOAP and WSDL. You can use Axis on the client side to greatly facilitate the development of your client. All code samples included in this guide were developed with Axis2. Bear in mind that there are several tools available to aid in the development of a Web Service client and Platform does not endorse any particular one.
When using Axis2 to write your client, you don't need to deal directly with SOAP and XML. Axis creates a proxy (or stub) for your clients to abstract away SOAP. All you need to do is make the method calls on the Web Service proxy as if it were a local object.
![]()
The client calls the stub, the stub translates the call into a SOAP message, and the stub sends it to the Web Service. The listening server receives the SOAP message and translates it into a method call at the server. Since the server is written in Java, the SOAP message is turned into a Java call. The server's return values are translated back to SOAP and then returned to the stub, which translates the returned SOAP message into a Java response.
A sample Bash shell script is provided that creates client-side classes for consuming services described in the WSDL files. Run this script from the directory containing the EGO WSDL files.
#!/bin/bash # Add the location of Java tools to PATH export PATH=/usr/local/jdk/bin/:$PATH # Set the location of Axis2 binary installation AXIS2_HOME=/home/ACCOUNT DIRECTORY/axis2-0.92-bin # Build Axis2 classpath AXIS2_CLASSPATH=. for i in $AXIS2_HOME/lib/*.jar; do AXIS2_CLASSPATH=$AXIS2_CLASSPATH:$i; done # Generate the Java classes for i in *.wsdl; do echo $i; j=`echo $i | sed -e 's/\(.*\)\..*/\1/'`; echo $j ; java -classpath $AXIS2_CLASSPATH org.apache.axis2.wsdl.WSDL2Java -uri $i $i done # Compile the generated classes for i in codegen codegen/databinding/com/platform/www codegen/databinding/org/w3/www codegen/databinding/org/xmlsoap/schemas; do javac -classpath $AXIS2_CLASSPATH $i/*.java; javac -classpath $AXIS2_CLASSPATH $i/impl/*.java; done # Create the Jar file jar cvf ego.jar ./codegen ./schemaorg_apache_xmlbeans/ # Use the generated jar file in classpath of your application exit 0[ Top ]
[ Platform Documentation ]
Date Modified: July 12, 2006
Platform Computing: www.platform.com
Platform Support: support@platform.com
Platform Information Development: doc@platform.com
Copyright © 1994-2006 Platform Computing Corporation. All rights reserved.