Woden elements must have serialize methods

• Key: WODEN-65
• Type: Improvement
• Status: Open
• Priority: Major
• Assignee: Sagara Gunathunga
• Reporter: Eran Chinthaka
• Component/s: Parser
• Fix Version/s: M9

Description

When we load a WSDL in to Woden object model, there is no way to serialize the object model in to an output stream. This is very much useful when some one wants to make sure Woden can properly spit out what it has read.

And there is a requirement from Axis2 also to make Woden element serializable to cater for ?wsdl2 requests.

Comments

[John Kaputin]

We plan to add a WSDLWriter interface for serializing the Woden object model to a WSDL Document, similar in function to the WSDLWriter in WSDL4J.

[Sagara Gunathunga]

WSDLWriter.java.txt - WSDLWriter interface

WSDLFactory.java.txt - added factory method to create WSDLWriter instance.

DOMWSDLFactory.java.txt - added factory method to create DOM based WSDLWriter instance.

[Sagara Gunathunga]

OMWSDLFactory.java.txt - added factory method to create OM based WSDLWriter instance.

BaseWSDLWriter.java.txt - define the features common to DOM and OM WSDLWriter implementations.

DOMWSDLWriter.java.txt - DOM based implementation of WSDLWriter

[Sagara Gunathunga]

OMWSDLWriter.java.txt - OM based implementation of WSDLWriter

DOMUtils.java.txt - Utility for DOM based implementation of WSDLWriter.

WriterFeatures.java.txt - define WSDLWriter features

[Sagara Gunathunga]

sample1.java - WSDLWriter example .

test.wsdl - Example WSDL file .

[John Kaputin]

Hi John,
As you said I have fixed the problems with patch files and modified codes according to JIRA (WODEN-177). Also I have removed the woden.internal.DOMUtils class. But I didn't touch rest of the code because still I'm having basic questions to solve. Here I have listed below.
 
(1)
> > > As a beginning I have studied how serialization is implemented in
> > > WSDL4J and Apache AXIOM projects. If I summarized what I realized is
> > >
> > >
> > > (1) In WSDL4J? WSDLWriterImpl use basic Java java.io.PrintWriter
> > > to actual writing tasks and DOMUtils, DOM2Writer used to traversing > > > and formatting tasks.
> > >
> > > (2) In AXIOM - javax.xml.stream.XMLStreamWriter is used to writing
> > task.
> > >
> > >
> > > Then I came up with 2 ideas for Woden serialization implementation
> > >
> > > (1) Use an approach that similar to WSDL4J, means
> > > java.io.PrintWriter for writing task and use of DOMUtils, DOM2Writer
> > > and OMUtil, OM2Writer for other works. (In this case necessity of two
> > > Writer implementation is a question?)
> > >
> > >
> > > (2) Use one writer (may be java.io.PrintWriter or any other
> > > available writer on DOM) for DOMWriterImplemanatation and use
> > > javax.xml.stream.XMLStreamWriter for OMWrterImplematation.
 
 
(2) parseXXX () methods of WSDLWriter take XMLElement as a parameter. In my case I use Woden Elements as parameters for printXXX() methods. I'm interesting to have some comments on this issue also. I think this issue is relevant to the point you mentioned in your last mail.
 
> Note that DOM elements (and OMElement)
> are represented in Woden by XMLElement and many of the element access
> method available via DOMUtils are now available via the XMLElement
> interface. We might need to think about how to access and use XMLElement
> objects to serialize the WSDL.
 
It is much easy to me go forward, If you can provide a descriptive comments for above issues .
thanks
sagara

[John Kaputin]

> (2) parseXXX () methods of WSDLWriter take XMLElement as a
> parameter.

Regarding your question about whether or not to use XMLElement in the printXXX methods of WSDLWriter, I think 'no'. What you have done with DOMUtils, following the WSDL4J approach, looks good. XMLElement was introduced as an abstraction of DOM Element and OMElement allow some refactoring of the WSDLReader implementations and reduce duplication in the parsing logic. However, the XMLElement objects for each WSDL element are not preserved in the Woden model and are not available to be passed to the WSDLWriter print methods. For now, the methods you have added to DOMUtils are fine.

> > > > Then I came up with 2 ideas for Woden serialization implementation

I haven't had time to consider this in detail yet. The main requirement is that both implementations (DOM and Axiom) should support a single API. So the writeWSDL methods, which currently take a java.io.Writer and java.io.OutputStream, may need some type of abstraction to represent a java.io.Writer and a javax.xml.stream.XMLStreamWriter. Perhaps 'org.apache.woden.XMLWriter', with the org.apache.woden.internal.DOMXMLWriter implementation making use of java.io.Writer and org.apache.woden.internal.OMXMLWriter using javax.xml.stream.XMLStreamWriter. Then the WSDLWriter methods would be something like writeWSDL(DescriptionElement, XMLWriter).

BTW, I just noticed your writeWSDL methods take a Description object. I think DescriptionElement would be better. The Element API corresponds to the WSDL infoset and as WSDLWriter is about serializing this infoset, we may as well pass in a DescriptionElement object. The client programming model would be to call Description.toElement() and pass this to the writeWSDL method.

[John Kaputin]

r569372
Initial commit of the patch files to the 'woden65' branch in SVN.

This looks pretty good. Thanks Sagara. There were several unnecessary whitespace changes in DOMUtils, probably resulting from WODEN-166 (eol style), so I removed these before committing the code.

Further action required:

1) In the supplied testcase, the wsdl:service element in the serialized document does not have a closing tag

2) All of the files must have the text in apache-boilerplate.txt added to the beginning of the file.

3) A bit more class and method Javadoc is needed, at least for any API interfaces and methods.

4) Testcases should be include, in Junit form as part of the Woden test suite in the /tests folder. A testcase that serializes some WSDL and checks that it contains all the expected content would be ideal . This could be achieved in various ways, from checking strings to deserializing again and checking the content of the DOM model.

5) Indentation of the serialized WSDL could be improved. The inline schema in the <types> element was all left-aligned (no indentation).

[Sagara Gunathunga]

I have developed most of TODO things in my initial contribution. But, still I didn't upload new patch files because I came up with following question when I tested my WSDLWriter manually.

When I used flickr.wsdl [1] file as an input source, I got some errors regarding element QName prefixes. In above WSDL file some of the attributes of InterfaceMessageReferenceElement (simply input, output element) doesn't have QName prefixes; this will result in an exception when I call getQualifiedValue() method in DOMUtils class.

I have 3 suggestions for this,

(1) Ignore the above WSDL file and leave the code as it is. ( in other words, force to use QName )
(2) When no element prefix is available use the TargetNsmespace's prefix as the element prefix for such elements. (e.g. SIN into TargetNsmespace'sPrefix:SIN)

(3) Write these attribute without considering QName prefix.( e.g. SIN )

So, please comment on this issue, and above flickr.wsdl [1] file is somewhat huge file, so I created a small example WSDL file to illustrate this issue.


Other than this I'm trying for serialization of ExtensionElement and ExtensionAttribute.Could you please give an introduction on Woden Extension mechanism and sketch required steps for extension serialization on the half of WSDLWriter?

 (Starting from SomeElement. getExtensionElements( ) or SomeElement. getExtensionAttributes( ), what are the interactions among Extenstionregistry, ExtenstionSerilizer ...etc. to achieve serialization)

[1] - http://dev.w3.org/cvsweb/2002/ws/desc/test-suite/documents/good/FlickrHTTP-1G/flickr.wsdl

[Sagara Gunathunga]

Sample WSDL file created to illustrate above issue (absence of prefix).

[John Kaputin]

> (1) Ignore the above WSDL file and leave the code as it is. ( in other words, force to use QName )
We can't mandate the use of a namespace (either via a prefix or via a default namespace defined in the WSDL). This would impose a new rule not defined in the WSDL 2.0 spec.

> (2) When no element prefix is available use the TargetNsmespace's prefix as the element prefix for such elements. (e.g. SIN into
> TargetNsmespace'sPrefix:SIN)
Again, this would impose a new rule not defined in the spec. If the element xs:QName value has no prefix, and if there is no default namespace defined, then the element simply has no namespace. We can't force it to use the TNS.

> (3) Write these attribute without considering QName prefix.( e.g. SIN )
We do need to consider the prefix, but if there isn't one then we just print the localpart (i.e. not qualified by a prefix)

Note, adding a default namespace declaration to the WSDL (xmlns="http://example.org/name") will avoid the NPE, but it should not be necessary to do this. It should be possible to print out the WSDL as is.

The NPE that occurs with your example WSDL is because in writer.printInterfaceMessageReferenceElement, the call to desc.getNamespace is returning a null and toString() is being called on the null value. The code fragment below shows a fix:

            QName attrQName=msgRef.getElementName();
            URI ns = des.getNamespace(attrQName.getPrefix());
            String attrName = null;
            if(ns != null) {
                attrName = DOMUtils.getQualifiedValue(des.getNamespace(attrQName.getPrefix()).toString(),
                    attrQName.getLocalPart(), des);
            } else {
                attrName = attrQName.getLocalPart(); //just print the localpart, without a prefix
            }
            DOMUtils.printAttribute(Constants.ATTR_ELEMENT, attrName, pw);

I'll comment separately on serializing extensions.

[John Kaputin]

You can get the extension elements and attributes using the methods getExtensionElements and getExtensionAttributes which all WSDL elements inherit from WSDLElement..

To serialize an extension element you need to use ExtensionRegistry.querySerializer to get an ExtensionSerializer object specific to the extension element. Each extension element will need an implementation of the ExtensionSerializer interface registered with the ExtensionRegistry (for the SOAP and HTTP extension, this will need to be done in the ctor of PopulatedExtensionRegistry). This is similar in concept to the implementation of ExtensionDeserializer which is also registered in the PopulatedExtensionRegistry ctor and is invoked in the BaseWSDLReader.parseExtensionElement method.

The ExtensionDeserializer.unmarshall method is similar to the parseXXXX methods in the WSDLReader classes which are used for WSDL elements. The ExtensionSerializer objects have a marshall method which will be similar in function to the printXXXX methods in your WSDLWriter impl class. See WSDL4J for examples.

The extension attributes are represented in Woden as XMLAttr objects. XMLAttr classes used in Woden (SOAP and HTTP) are registered in the PopulatedExtensionRegistry ctor. XMLAttr has a method toExternalForm() which returns the string representation of the serialized attribute value as it appears in the WSDL document. It also has a method getAttributeType which returns the QName of the attribute, from which you can get the attribute local name and any prefix value. You will need to put these 3 items (optional prefix, attribute local name and attribute value) together to reproduce the serialized attribute.

[Sagara Gunathunga]

Following modifications have been done.

1. apache-boilerplate.txt is added to each source file. Javadoc for classes and methods also improved.

2. Most of TO-DO things have been completed.

3. Extension serialization is also completed. (Please review these two methods and comment on them
 About them specially printExtenstionElement method.)

[John Kaputin]

r581066
Committed the latest (Sept 16) contributions for serialization to the woden65 branch. Thanks Sagara.

[John Kaputin]

Good work Sagara. Looks like you've made some great progress. I'll take a closer look at the extensions serialization and see if I have any comments to add. In the meantime, here's some feedback on your latest code contribution.

2 naming styles are used for the DOMWSDLWriter print methods; printXXXXs and printXXXXElements (e.g. printBindings and print BindingOperationElements). Could you use just one naming convention here. For example, either printBindings and printBindingOperations (the WSDL4J style) or printBindingElements and printBindingOperationElements. If you choose the first style, the documentation print method should be called printDocumentation (without an 's' on the end).

The printDocumentations method in DOMWSDLWriter uses a Java 5 JAXP API method. It calls the org.w3c.dom.Node.getTextContent() method.
Woden currently pre-reqs Java 1.42, so this method will not compile under Java 1.42. Can you use a similar approach to WSDL4J, which is also coded to Java 1.4 - see how WSDL4J WSLDWriterImpl.printDocumentation calls DOM2Writer.serializeAsXml which further down the call path uses the Node.getNodeValue() method.

I have 3 observations after running your latest code against your original test-prefix.wsdl file:

(1) The attribute xsi:schemaLocation is not being printed out. I'm not sure yet if this a problem with the writer code or if it's not being parsed correctly from the WSDL by the reader code.

(2) When printing the TypesElement, the output includes a schema import for the W3C schema for XML Schema:
<xs:import
 namespace="http://www.w3.org/2001/XMLSchema" location="file:/C:/workspace/woden/woden65/bin/org/apache/woden/resolver/XMLSchema.xsd" />

This schema import is added by Woden to get the built-in XML schema data types into the Woden object model. We have a JIRA open to come up with a better solution. In the meantime, your writer code should just ignore the schema import if it's for the W3C schema for XML Schema (i.e. namespace http://www.w3.org/2001/XMLSchema).

(3) There are some unexpected namespace declarations being printed out for the xs:schema element within the wsdl:types element. They are xmlns:name, xmlns:wsdl, xmlns:soap, xmlns:xs (these are declared in the wsdl:description element, not the inlined xs:schema element)

Could you please create some JUnit test classes to add to the Woden test suite in the /test folder. We will need a WSDLWriterTest class in the org.apache.woden package that contains a test method for each method on the WSDLWriter interface (so, this class tests each writer API method). I've just noticed that the /test/org.apache.woden.WSDLReaderTest class does not have a specific test method for every method on the WSDLReader interface so that's not a good example to follow! Take a look at something like /test/org.apache.woden.wsdl20.EndpointTest instead for a better example.

You could try this slighty different programming model from the code in sample1.java:
  Description descComp = re.readWSDL(....wsdluri....);
  DescriptionElement descElem=descComp.toElement();
  wr.writeWSDL(descElem,System.out);
    ....or just....
  wr.writeWSDL(descComp.toElement(), System.out);

Thanks again for your contributions so far.

[Sagara Gunathunga]

John , printing unexpected attributes with Scheme element problem is same as 3rd point of your previous comment on this thread .

Following unexpected attributes print with the schema element .

 xmlns:tns="http://example.org/Echo"
 xmlns:whttp="http://www.w3.org/ns/wsdl/http
 xmlns:wsdl="http://www.w3.org/ns/wsdl"
 xmlns:wsdlx="http://www.w3.org/ns/wsdl-extensions"
 xmlns:xs="http://www.w3.org/2001/XMLSchema"
 attributeFormDefault="unqualified"


I used Apache XmlSchema -Schema. write() method to print the schema elements ( please refer printInlinedSchemaElements() method of DOMWSDLWriter class.)


 I have attached small WSDL file and generated out put file to illustrate this issue , you can test this samples with WSDLWriter code available on branch- 65 of the code base .

[John Kaputin]

Sagara,
I tried the sample WSDL file and looked at the XmlSchema.write method. I guess a fix to XmlSchema is needed. It needs access to declared namespaces that are 'in-scope' (eg. declared in <wsdl:types> or above) so that it can resolve prefixes, but it should avoid printing them on the xs:schema element if the schema is inlined and the namespaces are declared in the surrounding document. You could have a go at creating a fix if you like or just leave it as is for now - the printed XML is still logically correct.

Alternatively, you could use the Woden API to get the schema DOM element and try printing it like WSDL4J does using the DOMUtil and DOM2Writer utility classes.

Will you be adding some indentation to the printing?

[John Kaputin]

I have merged the latest trunk code into the woden65 branch and made just the code changes necessary for it to compile. One of the differences you will see in the printing code is that namespace declarations are now handled where they occur, in the appropriate WSDL element. Previously, all namespace declarations were stored in DescriptionElement.

[Sagara Gunathunga]

Fixes for following issues

  1. Printing unexpected attributes with printInlinedSchemas() method.

  2. Printing schema import for the W3C schema for XML Schema with printImportedSchemas() method.

 3. Java 5 JAXP API specific getTextContent() method was removed from the printDocumentations() method.

   and

  A JUnit test case was added for WSDLWriter interface.

[Sagara Gunathunga]

Hi John,

I have uploaded several patch files today. With this update, I could resolve following issues of my previous code contribution.

1.Printing unexpected attributes with printInlinedSchemas() method.

2.Printing schema import for the W3C schema for XML Schema with printImportedSchemas() method. Please note that this is a temporary implementation, once we have a solution for JIRA131; we need to change this method implementation also.

3.Java 5 JAXP API specific getTextContent() method was removed from the printDocumentations() method.

4.Standardized all the method names into one format.

5.A JUnit test case was added for WSDLWriter interface. But still test case is failing.. I can't figure out what's the exact reason for that, if you have free time please investigate the Testcase.

Apart from 4th point, I have completed most of the task required for DOM based implementation of WSDLWriter. I'm planning to complete remaining things and move to OM based implementation quickly.

[John Kaputin]

r631272
Committed Sagara's latest patches to woden65 branch.

Minor change - changed the printType method back to printTypes to reflect the element name <types>. I have not finished reviewing the code yet, so will add feedback later.

The new WSDLWriter testcase looks good. The failure is due to a problem in Woden, not the testcase. Woden does not yet have a completed implementation of the equals() method throughout the WSDL model. This might not be resolved unless/until we merge the Element and Component APIs, as per the API Review issue on the wiki. I'll look at the testcase and consider alternative tests for the time being.

[John Kaputin]

The WSDLWriter.printDocumentation method was modifed by the latest patch to avoid Java 5 JAXP API and now includes this comment:

                    * This is not enough to handle DocumentationElement
                     * with nested DocumentationElements,if it is required
                     * a recursive method based on getNodeType()
                     * (org.w3c.dom.Node) can be used to solve this issue.

Documentation elements should not contain child documentation elements according to the WSDL 2.0 schema. DOMWSDLReader will report a schema error and I think any nested documentation elements would just be treated as unknown extensibility elements in the WSDL object model.

[Sagara Gunathunga]

AFAIK for DOM based implementation we have following tasks left to do.

First, It is necessary to have a close review for 1st and 2nd point of my previous comments (please refer my comments on 12/Feb/08 10:58).

Secondly, we need to find an alternative way for failing test case, if you can come up with any possible suggestion, I can work on it.


With following points we can initiate our discussion about OM- based implementation.

(1) As a basis we can use either AXIOM API or pure StAX API.

(2) In the initial stage, need to add/improve classes of org.apache.woden.internal.util.om package to achieve same functionality offered by org.apache.woden.internal.util.dom package.(Need to add OMWriter class and some improvements for OMUtil class ).

(3) We can use same style that we used for DOM implementation.

[Sagara Gunathunga]

Corrected POM files for Woden modules.

[Sagara Gunathunga]

I have started working on OM implementation, still I didn't get any feedback for my last two code contributions, Further it is required to apply the patches for JIRA -212 ,in order to work OMWSDLWriter correctly .

[John Kaputin]

r674519 Sagara's pom.xml patches
r674522 merged in some further changes to pom.xml files from trunk
r674534 Sagara's OM serialization patches.

I'll do some testing of these latest patches and respond to Sagara's comments.

[Sagara Gunathunga]

OM based Writer implementation completed and add some missing features to DOM based writer. I have tested with some of WSDL 2.0 files available in W3C Test Suite.

[Sagara Gunathunga]

I refactored WSDLWriterTest in to two separate test cases as DOMWSDLWriterTest and OMWSDLWriterTest . Further these test cases added to AllWodenTests Class.

[Sagara Gunathunga]

 revision: 810577
Committed latest patches.