SAWSDL4J

SAWSDL4J Tutorial

This document provides a quick overview of how to use the SAWSDL4J object model. This includes code samples showing how to kickstart the usage of SAWSDL4J

A word about the origins

This object model is built based on the WSDL4J object model from sourceforge. The interfaces are mostly extended (rather than replicated) so that the exisitng WSDL4J model is loosely coupled to this implementation. This gives us the flexibility to easily integrate the changes in WSDL4J implementation.

Starting up - what you need

The following jar files are needed in the classpath in order to use SAWSDL4J

SAWSDL4J
WSDL4J
Jaxen

Note that the Jaxen dependancy is due to the use of Jaxen based XPath interpreter used inside the SAWSDL4J implementation. If you plan to start from scratch with the source then please read the building from source section.

The API

The SAWSDL specification focuses on the following elements

Interface (PortType in WSDL 1.1)
Operation
Fault
Schema complexType
Schema Element
Schema SimpleType
Schema Attribute

In WSDL4J the schema is treated as a plain DOM tree. Hence handling schema objects (such as types and elements) is done through the use of Xpaths operating on the DOM tree. The other objects such as Operations and PortTypes have modified Interfaces. To accomodate the change in Part element, both the Message Interface and the Part Interface has been modified. Following is a list of interfaces that have been modified.

Definition
PortType
Operation
Message
Part
Schema (From extensions)

These modification include the following changes

Addition of methods to extract/set the model references
Addition of methods to extract/set lifting and lowering mappings
Modifiying create methods to create the annotated objects (Definition)
Addition of methods to retrieve modified objects(Definition/PortType/Message)

Note that the SAWSDL specification does not restrict model references only in these elements. However special attention has been given to the aboe mentioned elements hence the SAWSDL4J API also gives specialized methods for those elements. The next sections briefly mention how to use the API.

Creating SAWSDL Definition Objects

The following code segment shows how a SAWSDL definition object can be constructed

                
            System.setProperty("javax.wsdl.factory.WSDLFactory",
               "edu.uga.cs.lsdis.sawsdl.impl.factory.WSDLFactoryImpl");

            WSDLReader wsdlReader = WSDLFactory.newInstance().newWSDLReader();
            String wsdlURI = new File(WSDLFileName).toURI().toString();
            Definition def = (Definiton)wsdlReader.readWSDL(wsdlURI);

Note the variable WSDLFileName holds the full path of the WSDL file. The most important line of code in this segment is the setting of the system property in the first line .This is how the WSDL4J libraries take the SAWSDL factory. The other important fact to notice is that a casting is needed to actually get the edu.uga.cs.lsdis.sawsdl.Definition object since the standard factory interface returns and object of type javax.wsdl.Definition.

If the system property is set one can even use the edu.uga.cs.lsdis.sawsdl.util.SAWSDLUtility to get the definition object. The following code segment shows how to use the utility classes to get a definitions object easily.

                

        System.setProperty("javax.wsdl.factory.WSDLFactory",
            "edu.uga.cs.lsdis.sawsdl.impl.factory.WSDLFactoryImpl");

        Definition def =
                edu.uga.cs.lsdis.sawsdl.util.SAWSDLUtility.getDefinitionFromFile(new File(WSDLFileName));

If there is a requirement not to change the root factory using the system property setting then one can pass the fully qualified factory class name to the newInstance() method

Accessing Other Specialized Objects

Once the definition object is aquired, one can easily navigate to the other semantically annotated objects. The following code segement shows how one can retrieve the model references in the PortType. Note that the attrExtensions has been handled underneath to handle the model reference correctly.

          
        Definition sawsdlDefinition = getDefinition();
        PortType sawsdlPortType =
                sawsdlDefinition.getSemanticPortType(new QName(TARGET_NS,PORTTYPE_NAME));
        ModelReference modelReference = sawsdlPortType.getModelReference();

        String concept = modelReference.getConcept();

The getDefinition() method returns a modified Definition object. The same prinicipal applies to the other modified objects where the getSemanticxxx methods are available.

Handling schema

Handling schema is done through the use of Xpath. The following code fragment shows how to access an element with given model reference.

            
        Definition sawsdlDefinition = getDefinition();
        Types types = sawsdlDefinition.getTypes();
        List < Schema > schemaList = SchemaUtils.getSchemas(types);
        Schema s = schemaList.get(0);

        try {
            Set < ModelReference> modelReferences =
                s.getModelReferences(s.getElement(), "//xsd:schema/xsd:element[@name=\"OrderRequest\"]", sawsdlDefinition);
            // do something with the model references
        } catch (WSDLSException e) {
            e.printStackTrace();
        }

Accessing Other Model References

If there are model references in other components (as an attribute) then these will be available from the releavant object as an extensibility attribute. The extensibility attribute will actually be a list of Strings that contain the model reference url.

           
         Definition sawsdlDefinition = getDefinition();
         Binding binding =
                 sawsdlDefinition.getBinding(new QName(TARGET_NS,BINDING_NAME));
         List < String > modelRefURIs = (List <String >)
              binding.getExtensionAttribute(edu.uga.cs.lsdis.sawsdl.impl.Constants.Q_ATTR_MODELREF);

Conclusion

SAWSDL4J is a simple API that allows easy handling of SAWSDL documents

Resources

A Complete Java Example Program

Project Documentation