ws-sandesha-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Heusinger, Marcel" <>
Subject AW: Apache mentoring programme
Date Tue, 04 May 2010 07:57:31 GMT
Dear Andreas, dear Sanjiva,


Thank you for your time and your detailed suggestions. Please excuse my
terrible delayed message, I was on holiday for the last two weeks and I
didn't the environment to work out an appropriate response. 


>From your e-mails I extracted the following critics or suggestions,
beside the problem of mapping generated types and schemas element

(1) documentation should be added to xs:documentation instead of

(2) an WIKI-style syntax for the semantic annotation 

(3) getting documentation done by developers

(4) the enlargement of the projects scope. 


Below you find my thoughts regarding the points listed above:


1.Using the xs:annotation/xs:documentation instead of

Actually, I proposed to nest the documentation with the xs:appinfo
element because it is used for machine-readable content, whereas the
xs:documentation is used to provide information for human readers [1].
As the generation of documentation is done by a machine, I thought it
would be standard-conform to use the xs:appinfo element. After reading
the specification's section again, I have to confess that I was not
aware of the fact that the provided URI references don't have to be
de-referenced and therefore could be treated as plain text. Therefore it
makes pretty much sense to add the documentation to the xs:documentation
element. Furthermore, it seems to be a good compromise using a
Wiki-Style syntax, as it is much easier to read for humans and does not
entail the overhead that an Xml content would bring along while


2. Wiki-Style syntax.

After doing some research on Wiki syntax I found an open source wiki
called SnipSnap. The syntax of editing pages is very close, nearly
identical, to the one used by Wikipedia (see [2] and [3]). But the
interface provided by SnipSnap is much richer as far as I was able to
find out. SnipSnap introduces some interesting Macros, for example the
api macro. It is used to reference a parameter within an API

A tag nested in the xs:annotation/xs:document element could be:
{also:{api:java.lang.Object}}. When rendered that element would generate
something like "See also: java.lang.Object". Within that example the
{also:<Content>} would generate "See also: <Content>" and {api:<Class>}
would be mapped to a clickable link to the class's API documentation.
There are also other elements used for formatting of code (useful for an
example section), link, or text formatting macros like lists and so on.

I think the syntax is quite easy to grasp and somehow readable even in
the source view. But as it adds some complexity, a point that Sanjiva
mentioned, the main problem is getting the documentation done.


3. Getting documentation done

I agree with you Sanjiva, developers prefer coding over documentation,
which makes the automatic code documentation in Eclipse quite popular.
But I would think, most of  the developers would agree that an in-code
documentation, which evolves with the development of the code, is vital
for the usage of an (external visible) API. An appropriate tool support,
which reduces the documentation afford to adapt some parts of
automatically generated documentation could help to encourage the
documentation of WSDL interfaces and Xml schema abstract data types. May
the proposal could be enlarged to include such a tool support, for
example in form of an Eclipse view. This view could probably provide
standard input fields based on the element's properties and scope (fault
contract vs. data contract vs. service contract).


4. Enlarging the proposal's scope by including wsimport and by adding a
tool to generate human readable documentation

As wsimport as part of JAX-WS, which is not an ASF, and creating a tool
that is not part of an ongoing Apache project is not suitable for the
Apache Mentoring Programme: "The work of a mentee project can be code or
documentation, so long as it contributes to an existing Foundation
project. Individual research or prototyping projects are not acceptable
- working with an ASF project community is an essential part of the

Furthermore, one of the WS-JAX's goals is interoperability between.NET,
especially WCF, and Java[6]. Although the documentation does not affect
interoperability of services and proxy generation, both sides certainly
want to be involved in a convention's elaboration. 

Considering this problems lead me to the following idea, which should
not be taken to serious, it's just a discussable sketch of a possible
way to meet the requirements mentioned before:

a.] creating a working solution A within the Axis2 project's scope

b.] document architectural decisions for further investigation while
designing an interoperable solution B within the enlarged project's
scope mentioned in 4.)

c.] moving solution A to Apache Commons, in order to re-use it within
the WS-JAX project and enable its integration in tools.

d.] evolve solution A according to the community process of the
interoperable solution B and add functionality to be used as
documentation generator

But that would cause a lot more mentor interaction, which seems to be a
problem anyway as indicated by the proposal's response. That means it
will be even much harder to find a mentor for this kind of proposal.


Although, I still think it would be useful and an interesting project,
it will be too difficult to find a mentor, who would put that much
effort into such a project. 

Therefore: Does anybody has another idea or an appropriate issue that
could be suitable for the Apache Mentoring Programme?


Kind regards,





[3] As the site is not available at the moment see the Google Cache for:

[4] As the site is not available at the moment see the Google Cache for:



[7] I agree with you that the mapping is a problem, but it could be
possibly solved by adding some mapping configuration. But before an
architectural decisions like this could be considered, the project's
feasibility should have been agreed upon, which seems to be a problem in
the first place.




Von: Sanjiva Weerawarana [] 
Gesendet: Dienstag, 20. April 2010 02:07
An: java-dev
Betreff: Re: Apache mentoring programme


+1 .. I think the main issue with docs is getting people to do it. While
Dublin Core has been around for a long time adoption in the Web services
/ SOA worlds is minimal/non-existent. As such a tool that depends on
those annotations being present will likely see little use.


Marcel, I don't want to blunt your enthusiasm for participating in
Axis2. Do you have other ideas or variations that interest you? Do you
want ideas on things you can do?



On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen
<> wrote:


After thinking a bit more about your proposal and combining your ideas
with findings I made some time ago when thinking about best practices
to add documentation to WSDL/XSDs, I would like to make the following

1. In its present form, your proposal neglects a fundamental
constraint, namely that wsdl2java is used in contract first scenarios
where in many cases the WSDL/XSD is submitted to other teams and/or
organizations that don't necessarily use the same tools. It is
therefore important to avoid introducing syntax specific to a single
tool, because this would make the documentation useless when the
WSDL/XSD is processed by another team/organization, or within the same
team/organization, but with a different tool. E.g. the documentation
in xs:annotation/xs:appinfo/dc:description will (probably) not be
visible when opening the schema with XMLSpy, which is a popular tool
used in many organizations. The only way to satisfy this portability
requirement is to use xs:annotation/xs:documentation elements with
plain text content [1]. That is of course a very strict constraint.

2. The limited reaction by the community to your proposal is probably
an indication of some lack of interest. Probably one could generate
more interest by somewhat enlarging the scope of the proposal, namely
by including wsimport and by adding a tool that generates human
readable (browsable or printable) documentation directly from
WSDL/XSDs. Including wsimport may generate interest outside of the
Axis2 project as can be seen in [2] and [3]. A good documentation
generator could generate interest because there are not that many good
open source tools available.

3. There are some additional challenges when generating Javadoc from
WSDL/XSDs that are not addressed by existing solutions:

a. Since the content of xs:documentation is plain text, any formatting
(paragraphs, lists, etc.) is lost. As an example, you may consider the
code generated from [4] by wsimport.

b. The names of the Java classes and properties are not necessarily
the same as the names of the corresponding types and elements in the
schema. This in particular occurs with wsimport when using JAXB
customizations. E.g. I'm working in project where the guideline is to
use names ending with "Type" for all XSD types. Since having class
names ending with "Type" looks very silly in Java, I usually customize
the JAXB bindings to strip the "Type" suffix from these names. This is
a problem if the XSD documentation contains cross-references to other
types or elements, because the generated Javadoc will not be in sync
with the generated code. This is of course due to the fact that
current code generators cannot extract any semantic information from
the (plain text) xs:documentation element.

c. For the same reasons as item b., no {@link} annotations will be
generated. This makes it difficult to navigate the generated Javadoc.

An interesting project would be to propose a consistent solution for
these issues. This necessarily requires the definition of some form of
semantic annotation for the WSDL/XSD documentation (so that e.g. the
code generator can identify cross-references and replace them by the
right Java names). At first glance this seems to be in contradiction
with point 1 because one immediately things about XML markup to
achieve this. However, an alternative would be to define some sort of
Wiki-style syntax that leaves the xs:documentation element as plain
text, is human readable, interacts well with existing tools and that
at the same time has enough semantics to enable generation of high
quality Javadoc.



[1] If I remember well, the specs don't say anything about markup in
xs:documentation. Some time ago I checked how different tools react to
(HTML) markup in xs:documentation, and most of them render it
verbatim. E.g. wsimport will escape any angle brackets and ampersands
before inserting the documentation into the Javadoc.

On Thu, Apr 8, 2010 at 23:36, Heusinger, Marcel

<> wrote:

>>Two quick questions about your proposal:
>>- Axis2 supports several binding styles. There is the classic code
>>generator (wsdl2java) that supports different data bindings (the
>>default ADB, xmlbeans, JIBX,...), but there is also support for JAX-WS
>>artifacts generated by wsimport (which is not part of Axis2, but that
>>comes from Sun's JAX-WS reference implementation). What would be the
>>scope of this project?
>>- Can you give an example of how an annotated XML schema element would
>>look like? That would give us a better understanding of the ideas you
>>have in mind.
> First of all thanks for your reply. To answer your first question, I
> the idea while generating proxies with java2wsdl using its default
> binding adb. As I haven't tried out the other bindings yet, I would
> limit to this combination for the moment. Althought I haven't worked
> every detail of the mapping, I have something on my mind like the
> following:
> <description xmlns=""
> xmlns:dc="" ...>
>  <types>
>    <xs:schema ...
>      <xs:element name="request" type="xs:string">
>        <xs:annotation>
>          <xs:appinfo xmlns:dc="">
>              <dc:description>This parameter represents
> ...</dc:description>
>          </xs:appinfo>
>        </xs:annotation>
>      </xs:element>
>      <xs:element name="response" type="xs:string">
>        <xs:annotation>
>          <xs:appinfo xmlns:dc="">
>            <dc:description>This will be returned ...</dc:description>
>          </xs:appinfo>
>        </xs:annotation>
>      </xs:element>
>      <xs:element name="simpleError" type="xs:string">
>        <xs:annotation>
>          <xs:appinfo xmlns:dc="">
>            <dc:description>Thrown if ...</dc:description>
>          </xs:appinfo>
>        </xs:annotation>
>      </xs:element>
>    </xs:schema>
>  </types>
>  <interface name="webServiceInterface" >
>        <fault name="simpleFault"
>            element="simpleError" />
>        <operation
>            name="SimpleOperation"
>            pattern=""
>            style=""
>            wsdlx:safe="true">
>            <input
>                messageLabel="In"
>                element="request" />
>            <out
>                messageLabel="Out"
>                element="response" />
>            <outfault
>                ref="simpleFault"
>                messageLabel="Out" />
>            <documentation>
>              <dc:description>This is the method's description ...
> </dc:description>
>              <dc:creator>Developer</dc:creator>
>              <dc:relation>AnotherOperation</dc:relation>
>            </ documentation >
>      </operation>
>      <operation
>            name="AnotherOperation"
>            pattern="" ...
>  ...
> </description>
> The proxy's method should be annotated like the following:
> /**
>  * This is the method's description ...
>  * @param request This parameter represents ...
>  * @return This will be returned ...
>  * @see AnotherOperation
>  * @throws SimpleFault Thrown if ...
>  * @author Developer
> public Response SimpleOperation (Request ...
>  ...
> }
> Hope that I could explain what I intended with my proposal by
> this simplified example, which has to be worked out in more detail of
> course.
> Thanks.
> Marcel
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

Sanjiva Weerawarana, Ph.D.
Founder, Director & Chief Scientist; Lanka Software Foundation;
Founder, Chairman & CEO; WSO2, Inc.;
Member; Apache Software Foundation;
Director; Sahana Software Foundation;
Visiting Lecturer; University of Moratuwa;


View raw message