Quick Review

In Part 1 of this series, I introduced a cross-browser JavaScript library providing a simple SOAP Web services client capable of RPC encoded and document-literal style requests. Included in that client is support for request and response handlers, custom XML serializers/deserializers, and SOAP Headers; all of which I make use of in this WS-Addressing and WS-ResourceFramework implementation.

The primary objects defined in ws.js (introduced in Part 1) include:

1. WS.Call: A Web Service Client that wraps XMLHttpRequest
2. WS.QName: XML Qualified Name implementation
3. WS.Binder: Base for custom XML serializers/deserializers
4. WS.Handler: Base for Request/Response Handlers
5. SOAP.Element: Base SOAP Element wrapping XML DOM
6. SOAP.Envelope: SOAP Envelope Object extends SOAP.Element
7. SOAP.Header: SOAP Header Object extends SOAP.Element
8. SOAP.Body: SOAP Body Object extends SOAP.Element
9. XML: Cross-platform utility methods for handling XML

Of this set of objects, five are critical to the WS-Addressing and WS-ResourceFramework implementation: WS.QName, SOAP.Element, WS.Handler, WS.Binder, and WS.Call. I would strongly suggest that you go back to the first article to review the basic function of these objects.

In this installment, I introduce two new JavaScript files. The first defines objects supporting WS-Addressing (wsa.js); the second defines objects supporting a basic implementation of the WS-ResourceFramework (wsrf.js).

The primary objects defined in wsa.js include:

1. WSA.EndpointReference: WS-Addressing EndpointReference object.
2. WSA.EndpointReference.ReferenceParameters: Container for WS-Addressing EPR reference parameters.
3. WSA.EndpointReference.Binder: XML Serializer/Deserializer for WSA.EndpointReference objects.
4. WSA.MessageContext: Container for WS-Addressing SOAP message header metadata.
5. WSA.Handler: Request handler that inserts WS-Addressing SOAP message headers into the SOAP Envelope.

The primary objects defined in wsrf.js include:

1. WSRF.Request.GetResourceProperty: Wrapper for the WS-ResourceFramework GetResourceProperty operation.
2. WSRF.Request.GetMultipleResourceProperties: Wrapper for the WS-ResourceFrame GetMultipleresourceProperties operation.
3. WSRF.Resource: Client interface for invoking WS-ResourceFramework operations.

Note that while this might be a significant number of new JavaScript objects to learn, the API they present has been designed to minimize the amount of work you have to do when actually invoking a Web service. For instance, if you skip ahead to Listing 8, you'll see that the API lets you invoke a method on WS-ResourceFramework-compliant Web services with only a few lines of code -- without the need to mess around with the details of the underlying SOAP implementation.

Back to top

Implement WS-Addressing support

The Web Services Addressing specification defines the mechanisms for inserting addressing information into SOAP envelopes. At the core of WS-Addressing is an object known as an EndpointReference, which serves as a reference to and a description of a specific Web service instance. (See Listing 1.) Secondary to the EndpointReference, the WS-Addressing specification defines a number of SOAP message headers that are used to convey addressing information directly within a SOAP envelope.

The wsa.js JavaScript library provides a number of objects that implement basic support for the WS-Addressing EndpointReference and SOAP message header elements.

<EndpointReference xmlns="http://www.w3.org/2005/08/addressing">
  <Address>http://www.example.org/services/HelloWorld</Address>
  <ReferenceParameters>
    <abc:foo xmlns:abc="urn:foo">This is a test</abc:foo>
  </ReferenceParameters>
</EndpointReference>

The WSA.EndpointReference object is used to represent WS-Addressing EndpointReferences, as illustrated in Listing 2. Compare this code with the XML above, and you should be able to get a good sense of how the API operates.

var epr = 
  new WSA.EndpointReference(
    "http://www.example.org/services/HelloWorld");
var epr_rp = epr.create_reference_parameters();
epr_rp.create_child(
  new WS.QName('foo','urn:foo','abc')).
    set_value('This is a test');

The API for WSA.EndpointReference currently supports the Address and ReferenceParameters properties as defined by the WS-Addressing information model. The Metadata property is currently not implemented, as it is not critical to the basic function of the client being implemented here.

The WS-Addressing SOAP message headers are intended to be set on the SOAP Envelope being sent by the Web services client to the service. Because the WS.Call object defined in the ws.js JavaScript library hides the details of working with the underlying SOAP.Envelope, you use a WS.Handler to insert the appropriate headers for you.

The Web services client invokes the methods of the WS.Handler object on every request, response, and error. For the WS-Addressing implementation, a WSA.Handler has been provided that uses a corresponding WSA.MessageContext object containing the information that is to be inserted into the message. This is illustrated in Listing 3.

var address = 'http://www.example.com/services/HelloWorld';
var ctx     = new WSA.MessageContext();
ctx.to      = new WSA.EndpointReference(address);
ctx.replyto = new WSA.EndpointReference(WSA.ANONYMOUS);
ctx.action  = address + '#SayHello'

var handler = new WSA.Handler();
handler.set_context(ctx);

var call = new WS.Call('');
call.add_handler(handler);

The properties on the WSA.MessageContext object correspond to each of the WS-Addressing SOAP message headers:

• to: A WSA.EndpointReference object whose Address specifies an absolute URI identifying the destination of the message.
• from: A WSA.EndpointReference object identifying the sender of the message.
• replyto: A WSA.EndpointReference object identifying where replies should be delivered.
• faultto: A WSA.EndpointReference object identifying where faults should be delivered.
• action: An absolute URI identifying the action that the message is intended to trigger.
• messageid: An absolute URI that uniquely identifies the message.
• relatesto: An array of URI pairs that identify related messages. The first URI in the pair identifies the type of relationship; the second URI specifies the unique Message ID of the related message.

Once the WSA.Handler has been registered with the WS.Call object used to invoke the Web service, the WS.Call object invokes the handler on every request, handing it a reference to the SOAP.Envelope object. The handler pulls the information from the WSA.MessageContext and inserts the appropriate headers into the message as illustrated in Listing 5.

Back to top

Implement WS-ResourceFramework support

The Web Services Resource Framework defines a convention for the use of Web services standards to access and manipulate instances of stateful resources. Individual Resources are identified and referenced by WS-Addressing EndpointReferences. A handful of common operations may be used to retrieve or modify the properties of the resource.

The wsrf.js JavaScript library provides a partial implementation of the Web Services Resource Framework supporting the GetResourceProperty and GetMultipleResourceProperties operations. The API builds on both the ws.js and wsa.js APIs and is designed more for the purpose of illustrating the use of those two scripts than it is to provide a comprehensive WS-ResourceFramework implementation.

WS-ResourceFramework operations are document-literal SOAP requests that are directed toward specific Resource instances. The target resource is identified by a WS-Addressing EndpointReference, as illustrated in Listing 4.

<EndpointReference xmlns="http://www.w3.org/2005/08/addressing">
  <Address>http://localhost:9080/SoapAjax2/services/DeviceService</Address>
  <ReferenceParameters>
    <abc:DeviceID xmlns:abc="urn:deviceservice">ABC123</abc:DeviceID>
  </ReferenceParameters>
</EndpointReference>

When expressed within a SOAP Envelope using the mechanisms defined in wsa.js, the information within the WSRF EndpointReference takes the form of SOAP message headers, as shown in Listing 5.

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
 <Header>
  <To xmlns="http://www.w3.org/2005/08/addressing">
    http://localhost:9080/SoapAjax2/services/DeviceService</To>
  <abc:DeviceID xmlns="urn:deviceservice">ABC123</abc:DeviceID>
 </Header>
 <Body>
 <GetResourceProperty 
  xmlns="http://docs.oasis-open.org/wsrf/rp-2" 
  xmlns:ns="urn:foo">ns:bar</GetResourceProperty>
 </Body>
</Envelope>

The API presented by wsrf.js is designed to hide all of the details of working with the SOAP Envelope and WS-Addressing headers necessary to enable interaction with WS-ResourceFramework Web services. Taking a peek at the code, however, you see a number of important aspects of how the code works.

Listing 6 illustrates a wrapper object for the WSRF GetResourceProperty operation. This wrapper is used internally by the wsrf.js library and includes the basic mechanism for creating the SOAP Envelope and building the requisite XML for the operation. Note that the object utilizes the SOAP.Element and SOAP.Envelope APIs provided by ws.js. The "qname" parameter passed in on initialization of the wrapper object is the XML Qualified name of the property that is being requested.

WSRF.Request.GetResourceProperty = Class.create();
WSRF.Request.GetResourceProperty.prototype = {
  initialize : function(qname) {
    this.envelope = new SOAP.Envelope();
    this.set_qname(qname);
  },
  set_qname : function(qname) {
    var body = this.envelope.create_body();
    var method = body.create_child(
      WSRF.Request.QNAME_GETRESOURCEPROPERTY);
    if (!qname.namespace) qname.namespace = '';
    if (!qname.prefix) qname.prefix = 'ns';
    method.declare_namespace(qname);
    method.set_value(qname.value_of());
  }
};

Listing 7 contains a snippet of code from the WSRF.Resource object. What you see is the creation of a WS.Call object, the preparation of the WSA.Handler object that will be used to set the appropriate SOAP message headers, the creation of a WSRF.Request.GetResourceProperty wrapper object, and the invocation of the Web services operation.

get_resource_property : function(qname, callback) {
  var call = new WS.Call(this.address);
  var handler = new WSA.Handler();
  var wsactx = new WSA.MessageContext(this.epr);
  handler.set_context(wsactx);
  call.add_handler(handler);
  var req = new WSRF.Request.GetResourceProperty(qname);
  call.invoke(req.envelope, callback);
}

To invoke the GetResourceProperty operation against a WS-ResourceFramework Web service, an application needs only to supply an EndpointReference for the target WS-Resource and a WS.QName object identifying the property being retrieved as illustrated in Listing 8.

var ADDRESS = 'http://localhost:9080/SoapAjax2/services/DeviceService'

function getDeviceName(deviceID, container) {
  var epr = new WSA.EndpointReference(ADDRESS);
  var epr_rp = epr.create_reference_parameters();
  epr_rp.create_child(
    new WS.QName(
      'DeviceID',
      'urn:deviceservice')).set_value(deviceID);
  var res = new WSRF.Resource(ADDRESS, epr);
  res.get_resource_property(
    new WS.QName('DeviceName','urn:deviceservice'),
    function(call,envelope) {
      $('soap').innerHTML = arguments[2].escapeHTML();
    }
  );
}

Listing 8 wraps the call to the WS-Resource in a convenient function that can be called from anywhere within your HTML page. Listing 9 provides a button that passes in a device id from an input field called id and displays the response SOAP Envelope in a div element called result.

<input 
  value="Invoke the Web Service" 
  type="button" 
  onclick="getDeviceName($('id').value,$('result'))" />

Back to top

Next Steps

In this installment, you saw how the Ajax Web services client introduced in Part 1 of this series can be extended to support higher order Web services standards such as Web Services Addressing and the Web Services Resource Framework. In the next installment, the author will explore support for the Web Services Description Language.

Back to top

Download

Information about download methods

Resources

Learn

• Call SOAP Web services with Ajax -- Read all parts in this series.
  
  
• High Availability Disaster Recovery (HADR) -- Learn about the feature in DB2 UDB V8.2 that provides a high-availability solution for protection against both partial and complete site failures.
  
  
• Build dynamic Java applications -- Philip McCarthy's introduction to Ajax for Java developers (developerWorks, September 2005).
  
  
• JavaScript Framework -- Learn about the prototype framework upon which the Web Services JavaScript Library is based.
  
  
• XMLHttpRequest API -- Learn more about it from the XUL Planet Web site
  
  
• Exploit the Document Object Model to create enhanced Web application -- Learn more about XML Document Object Model that Microsoft Internet Explorer 6.0 uses (developerWorks, February 2004).
  
  
• Mozilla Web Services -- Learn more about Mozilla/Firefox's built-in Web services support.
  
  
• Web Services Resource Framework -- Learn more about the OASIS Web Services Resource Framework activity.
  
  
• Web Services Addressing -- Learn more about the W3C Web Services Addressing activity.
  
  
• Standards roadmap -- understand the impact and importance of standards and specifications for the development of SOA and Web services.
  
  
• Architecture: Build for the future -- visit the Architecture area on developerWorks and get the resources you need to advance your skills in the architecture arena.
  
  
• SOA and Web services -- hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop Web services applications.
  
  

Discuss

• developerWorks blogs -- get involved in the developerWorks community.
  
  

About the author

James Snell is a member of IBM's Emerging Technologies Toolkit team. He has spent the past few years focusing on emerging Web services technologies and standards, and has been a contributor to the Atom 1.0 specification. He maintains a weblog focused on emerging technologies at http://www.ibm.com/developerworks/blogs/page/jasnell.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Quick Review
• WS-Addressing
• WS-Resource Framework
• Next Steps
• Download
• Resources
• About the author
• Comments

Next steps from IBM

Create rich Internet applications using WebSphere Portal Express Web 2.0 technologies.

---

• Try: WebSphere Portal Express
• Article: Get started using Ajax and WebSphere Portal Express
• Tutorial: Quickly build a an Ajax-enabled WebSphere Portal Express Web application
• Demo: Architecture, design, and construction using the IBM Rational Software Delivery Platform: AJAX
• Webcast: Rational software process automation: Real value delivered, real customer stories
• Buy: WebSphere Portal Express

My developerWorks community

Dig deeper into Java on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers