Apache Muse - Creating WSDLs
The Role of WSDL in Muse Applications
A WSDL document defines the web services interface that remote clients will use to communicate with your resource. While the implementation of a resource may have many components and APIs, the WSDL will only document those things that can be invoked directly by a client. In addition to providing the client interface, a resource's WSDL is also used by Muse at application startup to determine what the contract of the resource is - that is, what requests are valid, what APIs should be restricted, and how to convert data from XML to Java objects (and back). The WSDL file, then, is the most important document in a Muse-based application; it confirms what is in the deployment descriptor (discussed later) and provides the details needed to process SOAP requests.
Muse provides tools that allow you to generate the required implementation files from a WSDL, and we will use these tools in the next section. First, however, we must create a WSDL and discuss the conventions used to simplify what can be a very cumbersome document.
WSDL Creation and Conventions
Creating a WSDL can be a tough task. Even if you're using an IDE with a nice WSDL editor, these generic tools can only provide so much help in constructing a WSDL that expresses the right semantics for your application. At some point, you're going to end up looking at the XML itself, and that's just a lot of XML.
The Muse team has tried to simplify the WSDL creation process in two ways: templates and conventions. The template WSDL provides a web services interface that includes all of the properties and operations defined by the WSRF, WSN, and WSDM port types; all you have to do to modify the template is add comment markers around definitions you don't want and add your custom properties and operations. Using this template as a starting point will greatly reduce the amount of time spent before code generation.
The aforementioned WSDL conventions have been put in place to simplify the design of WSDL (by you) and the processing of the WSDL (by the tools). The WSDL spec is very liberal in that it allows many concepts to be expressed in multiple ways; such freedom of expression inevitably causes ambiguity in the processing of the WSDL files, and this leads to inconsistent behavior during code generation. You should adhere to the WSDL conventions when modifying the template file so that the artifacts that are generated by the tools match the semantics of your interface.
Sample Resource and WSDL
Because WSDL creation is time-consuming (even with a template), this tutorial provides a sample WSDL for a resource that implements WSRP, WSN NotificationProducer, and a few of the simpler WSDM MUWS capabilities. This WSDL was created by uncommenting some of the definitions in the template WSDL and adding some new definitions to illustrate custom capabilities. In future sections, we will generate code for this resource interface and write code that publishes sample notifications on a set interval.
Our WSDM interface uses the following features from the world of web services standards:
- WS-ResourceProperties - GetResourceProperty operation
- WS-MetadataExchange - GetMetadata operation
- WSN NotificationProducer - Subscribe and GetCurrentMessage operations, as well as WS-Topics properties
- WSDM MUWS Identity - ResourceId property
- WSDM MUWS Description - Caption, Description, and Version properties
- WSDM MUWS OperationalStatus - OperationalStatus property
In addition, it adds the following features that are resource-specific:
- Properties - ServerName and MessageInterval
The ServerName property will be read-only, and represents the name of the resource's host. The MessageInterval property will be read-write, and represents the number of seconds that the resource waits before publishing messages to its subscribers.
You should review the contents of the sample WSDL so that you understand the definition of the new properties and operations and how they fit together with those from WS-*. Once you are comfortable reading through the WSDL file, you can move on to code generation.