Apache Muse - Deployment Descriptor
The Role of the Deployment Descriptor
Muse requires the use of a deployment descriptor in order to load, configure, and support the resource types that you have implemented. The name of the descriptor file is muse.xml. The WSDL2Java tool created this file during code generation and put it in a predetermined location so that the Muse engine could find it during initialization; also included during code generation is the schema for muse.xml, which you can use to validate any changes that you make to the file.
You can find information about every part of the muse.xml file in the reference manual. For now, we will cover the elements that relate to the definition of the resource type and the code generated by WSDL2Java.
Resource Type Definitions
In the muse.xml file that was generated by WSDL2Java, you will find a <resource-type/> element that describes the sample resource. Every resource type has a unique URL, with each URL conforming to the following pattern:
http://[host]/[web-application-name]/services/[context-path]where context-path is the value in the <context-path/> element under <resource-type/>. The context path for our sample resource is WsResource, and the name of our web application directory is wsn-producer, so a valid URL would be:
http://localhost/wsn-producer/services/WsResource
As you can see, the context path determines the last part of the URL. This allows resource types that share an application to have a unique URL that distinguishes them from the rest.
The sample resource, like all Muse resources, is a collection of smaller units of function called capabilities. The capability concept was initially described in WSDM MUWS 1.0 as a means of communicating to clients what data, operations, and behavior could be expected from the resource (over-and-above the basic contractual guarantees of the WSDL port type). Despite the use of capabilities to advertise behavior to clients, the way that capabilities are defined in the WSDM MUWS specification is reminiscent of the way Java developers break apart large pieces of software into smaller chunks of related tasks; the aggregation of capabilities like Identity, Configuration, and Relationships into a single web service interface suggests a similar model for server-side implementations. Muse has generalized the WSDM MUWS capability concept to make it easier for programmers to implement resources as reusable units of function rather than monolithic Java classes.
The capabilities that make up our sample resource include:
- WSRP GetResourceProperty
- WSMEX MetadataExchange
- WSN NotificationProducer
- WSDM MUWS Identity
- WSDM MUWS Description
- WSDM MUWS OperationalStatus
- MyCapability (contains the custom properties)
This list should look very familiar - it's the same list that we made in Section #2 when we were creating our WSDL. The WSDL2Java tool has split up the implementation of the resources based on the way we built our WSDL port type. Non-standard capabilities are identified by the XML namespace that contains their schema definitions; in other words, each capability should have its own XML namespace for defining properties and operations. Distinguishing your capability interfaces in this manner makes it easier to reuse them (and their implementations!) in other resource types.
Comparison to the Generated Code
Under the <resource-type/> element there is a set of <capability/> elements, each of which contains a URI (<capability-uri/>) and the name of the Java class that holds the capability implementation (<java-capability-class/>). Each of these values is important to understanding the Muse programming model and how the code that you write will be invoked.
Each capability in a resource type must have a unique URI. This URI is usually based on the XML namespace that contains the schema definitions of the capability's properties and operations, but it doesn't have to be; WSRF capabilities are based on their namespace of the spec that defines them, but WSDM capabilities are actually have official definitions in that spec. The list of all of the capability URIs in our sample is as follows:
- WSRP GetResourceProperty - http://docs.oasis-open.org/wsrf/rpw-2/Get
- WSMEX MetadataExchange - http://schemas.xmlsoap.org/ws/2004/09/mex
- WSN NotificationProducer - http://docs.oasis-open.org/wsn/bw-2/NotificationProducer
- WSDM MUWS Identity - http://docs.oasis-open.org/wsdm/muws/capabilities/Identity
- WSDM MUWS Description - http://docs.oasis-open.org/wsdm/muws/capabilities/Description
- WSDM MUWS OperationalStatus - http://docs.oasis-open.org/wsdm/muws/capabilities/OperationalStatus
- MyCapability - http://ws.apache.org/muse/test/wsrf
The capability URI provides a lookup mechanism for both the SOAP request handler and your own implementation code, which may require that multiple capabilities leverage each other in order to complete a task(s). Referencing other capabilities from within your code is covered in the reference manual.
The capability implementation classes implement the properties and operations that are defined in the capability schemas and aggregated in the resource's WSDL. Muse has default implementation of all of the WSRF, WSN, and WSDM capabilities, and WSDL2Java includes those classes when appropriate. In our sample, all of the classes are under the org.apache.muse.ws.resource.properties, org.apache.muse.ws.metadata, org.apache.muse.ws.notification, and org.apache.muse.ws.dm.muws packages and can be found in the JAR files that were added to your application during code generation.
The only class that is not part of the Muse framework is the one that represents our custom capability, org.apache.ws.muse.test.wsrf.MyCapability. Because this class is not part of Muse, WSDL2Java has generated a skeleton Java class that you must implement before you can deploy and test. This class is found in the src directory of the generated project; during the build process, it will be compiled into a JAR file and added to the other JARs in the application's classpath.
In the next section, we will review the coding tasks that must be completed in order to finish the custom capability and get our application ready for testing.