Mailing-List: contact java-dev-help@axis.apache.org; run by ezmlm
Precedence: bulk
Reply-To: java-dev@axis.apache.org
Received-SPF: pass (athena.apache.org: domain of andreas.veithen@gmail.com
 designates 209.85.161.45 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:in-reply-to:references:from:date:message-id:subject:to
         :content-type:content-transfer-encoding;
        b=iwCCqHNRpTMLo+4Qug2zMKPiX57HeW7LGIYzcxSsqt3nWD+cc+5tGHU/bU8m68d60T
         QdhnAA8vE9YXXlvq4ST8ZCckXpHXmDoZjqz42l+LM+ZPW3CFXCiLa+GAQHf9Waozx7PQ
         ZqChDzgIMlRtsBYMn5aJeatSgoszEcUSRVEWg=
MIME-Version: 1.0
In-Reply-To: 
 <F2D94777FF0928419037E41A47C847F6056A0E21@EXCHANGE01.win.uni-due.de>
References: 
 <F2D94777FF0928419037E41A47C847F6056A0E14@EXCHANGE01.win.uni-due.de>
	<m2xb67458761004081147tacbef076oed1ff5f6cb5d8d04@mail.gmail.com>
	<F2D94777FF0928419037E41A47C847F606DCF234@EXCHANGE01.win.uni-due.de>
	<q2ib67458761004191352n3f9dca5dh392558e553a3241b@mail.gmail.com>
	<u2qdc3907721004191707i6fa3dcfcj6e53cc9a6b1a9f16@mail.gmail.com>
	<F2D94777FF0928419037E41A47C847F6056A0E21@EXCHANGE01.win.uni-due.de>
From: Andreas Veithen <andreas.veithen@gmail.com>
Date: Tue, 4 May 2010 22:27:28 +0200
Message-ID: <AANLkTilcVDI1d3Mkmb_6tN9pcscJa0J7wvh3c3wFAUdZ@mail.gmail.com>
Subject: Re: Apache mentoring programme
To: java-dev@axis.apache.org
Content-Type: text/plain; charset=windows-1252
Content-Transfer-Encoding: quoted-printable

On Tue, May 4, 2010 at 09:57, Heusinger, Marcel
<marcel.heusinger@uni-due.de> wrote:
> 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=92t the environment to work out an appropriate response.
>
>
>
> From your e-mails I extracted the following critics or suggestions, besid=
e
> the problem of mapping generated types and schemas element names[7]:
>
> (1) documentation should be added to xs:documentation instead of xs:appin=
fo
>
> (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
> xs:annotation/xs:appinfo
>
> Actually, I proposed to nest the documentation with the xs:appinfo elemen=
t
> 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=92s section again, I have to confess that I was not aware o=
f the
> fact that the provided URI references don=92t have to be de-referenced an=
d
> therefore could be treated as plain text. Therefore it makes pretty much
> sense to add the documentation to the xs:documentation element. Furthermo=
re,
> 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 documenting.
>
> -------------------------
>
> 2. Wiki-Style syntax.
>
> After doing some research on Wiki syntax I found an open source wiki call=
ed
> 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 b=
y
> 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 documentation.
>
> 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 =93See also: java.lang.Object=94. Within that example the
> {also:<Content>} would generate =93See also: <Content>=94 and {api:<Class=
>}
> would be mapped to a clickable link to the class=92s API documentation. T=
here
> are also other elements used for formatting of code (useful for an exampl=
e
> 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 th=
e
> source view. But as it adds some complexity, a point that Sanjiva mention=
ed,
> the main problem is getting the documentation done.
>
> -------------------------
>
> 3. Getting documentation done
>
> I agree with you Sanjiva, developers prefer coding over documentation, wh=
ich
> makes the automatic code documentation in Eclipse quite popular. But I wo=
uld
> think, most of=A0 the developers would agree that an in-code documentatio=
n,
> 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 interface=
s
> 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=92=
s
> properties and scope (fault contract vs. data contract vs. service
> contract).
>
> -------------------------
>
> 4. Enlarging the proposal=92s 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 t=
hat
> is not part of an ongoing Apache project is not suitable for the Apache
> Mentoring Programme: =93The work of a mentee project can be code or
> documentation, so long as it contributes to an existing Foundation projec=
t.
> Individual research or prototyping projects are not acceptable =96 workin=
g
> with an ASF project community is an essential part of the process.=94[5]
>
> Furthermore, one of the WS-JAX=92s 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 w=
ant
> to be involved in a convention=92s elaboration.
>
> Considering this problems lead me to the following idea, which should not=
 be
> taken to serious, it=92s just a discussable sketch of a possible way to m=
eet
> the requirements mentioned before:
>
> a.] creating a working solution A within the Axis2 project=92s scope
>
> b.] document architectural decisions for further investigation while
> designing an interoperable solution B within the enlarged project=92s sco=
pe
> 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 documentatio=
n
> generator
>
> But that would cause a lot more mentor interaction, which seems to be a
> problem anyway as indicated by the proposal=92s response. That means it w=
ill
> be even much harder to find a mentor for this kind of proposal.
>

To be precise, wsimport is part of the build tools provided by the
JAX-WS reference implementation. The ASF has two projects (Axis2 and
CXF) that have their own implementation of the JAX-WS runtime.
However, both reuse the build tools from the reference implementation.
wsimport has an extensible (plugin) architecture. Currently, only the
CXF project has developed plugins for wsimport. If I remember well,
Daniel Kulp (who is one of the main developers of CXF) once mentioned
that he would be OK to move those plugins to the WS-Commons project
because they really have nothing CXF specific. Anyway, the point is
that there is no problem with developing a plugin for wsimport under
the umbrella of the ASF. Also, considering the fact that CXF has
already developed some plugins for wsimport (and is also more focused
on JAX-WS than the Axis2 project), it could be a good idea to propose
your idea to the CXF community as well.

>
> 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 in=
to
> such a project.
>
> Therefore: Does anybody has another idea or an appropriate issue that cou=
ld
> be suitable for the Apache Mentoring Programme?
>

There are over 600 open JIRA reports for the Axis2 project, but the
vast majority is probably related to maintenance of the existing
codebase. Nevertheless you may have a look at them (especially the
ones with type "Improvement" or "Task"); there may be some interesting
ideas in there.

Here are some new developments that are in progress and ideas that
have been discussed recently:

* Good Spring support for Axis2. This is work in progress, although it
has stalled over the last couple of weeks (I need to revive the
discussion). See the following links:

http://markmail.org/thread/vsnjbkyxh2wudn7e
https://issues.apache.org/jira/browse/AXIS2-4662
http://markmail.org/thread/m74otdyyfncvt2kd

* There was a proposal for a Google Summer of Code project that
started as a distributed TCP monitor but that evolved into a composite
application logger/monitor:

http://markmail.org/thread/bvu63eme4rnllqgt

I think the person who proposed that project now does a GSoC project
in CXF, meaning that the project idea is orphaned (to be confirmed of
course).

* A few days ago there was a post that triggered a discussion about
what are the challenges that should be addressed in the next major
release of Axiom:

http://markmail.org/thread/t5bxbn6crezkddry

As mentioned in one of my posts, some time ago I started a project
(http://code.google.com/p/ddom/) that implements some of the ideas
discussed in that thread. Initially the scope of that project didn't
include Axiom (as can still be seen from the outdated project
summary), but it evolved into something that _could_ become the basis
for Axiom 2.0. Of course there is much uncertainty here because the
code is outside of the ASF and before moving it to Axiom, one would
have to clarify its status (either by reaching an agreement within the
community to consider it as the basis for Axiom 2.0 or by simply
declaring it as proof-of-concept and to let the community decide later
what would be the relation to the current Axiom 1.x codebase). The
problem is that in my code there are many major parts missing that
would be necessary to prove that it would be a good candidate for
Axiom 2.0. There are also some radically new ideas in the already
implemented parts that would first have to be accepted by the
community, like bytecode manipulation to weave API front-ends (DOM,
Axiom, SAAJ) onto back-ends (implementing the data structures that
store the XML infoset)...

>
> Kind regards,
>
> Marcel
>
>
>
> [1] http://www.w3.org/TR/xmlschema11-1/#Annotation_details
>
> [2] http://en.wikipedia.org/wiki/Wikipedia:Layout
>
> [3] As the site is not available at the moment see the Google Cache for:
> http://snipsnap.org/space/snipsnap-help
>
> [4] As the site is not available at the moment see the Google Cache for:
> http://snipsnap.org/space/Macro+Tutorial
>
> [5] http://community.apache.org/mentoringprogramme.html
>
> [6] https://jax-ws.dev.java.net/
>
> [7] I agree with you that the mapping is a problem, but it could be possi=
bly
> solved by adding some mapping configuration. But before an architectural
> decisions like this could be considered, the project=92s feasibility shou=
ld
> have been agreed upon, which seems to be a problem in the first place.
>
>
>
>
>
>
>
> Von: Sanjiva Weerawarana [mailto:sanjiva@opensource.lk]
> 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 o=
n
> things you can do?
>
>
>
> Sanjiva.
>
> On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen <andreas.veithen@gmail.c=
om>
> wrote:
>
> Marcel,
>
> 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
> comments:
>
> 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.
>
>
> Regards,
>
> Andreas
>
>
> [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.
> [2] https://jaxb.dev.java.net/issues/show_bug.cgi?id=3D172
> [3] http://www.mail-archive.com/dev@cxf.apache.org/msg02796.html
> [4] http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd
>
>
> On Thu, Apr 8, 2010 at 23:36, Heusinger, Marcel
>
> <marcel.heusinger@uni-due.de> 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.
>>>
>>>Thanks.
>>>
>>>Andreas
>>
>> First of all thanks for your reply. To answer your first question, I had
>> 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 out
>> every detail of the mapping, I have something on my mind like the
>> following:
>>
>> <description xmlns=3D"http://www.w3.org/ns/wsdl"
>> xmlns:dc=3D"http://purl.org/dc/terms/" ...>
>> =A0<types>
>> =A0 =A0<xs:schema ...
>> =A0 =A0 =A0<xs:element name=3D"request" type=3D"xs:string">
>> =A0 =A0 =A0 =A0<xs:annotation>
>> =A0 =A0 =A0 =A0 =A0<xs:appinfo xmlns:dc=3D"http://purl.org/dc/terms/">
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0<dc:description>This parameter represents
>> ...</dc:description>
>> =A0 =A0 =A0 =A0 =A0</xs:appinfo>
>> =A0 =A0 =A0 =A0</xs:annotation>
>> =A0 =A0 =A0</xs:element>
>>
>> =A0 =A0 =A0<xs:element name=3D"response" type=3D"xs:string">
>> =A0 =A0 =A0 =A0<xs:annotation>
>> =A0 =A0 =A0 =A0 =A0<xs:appinfo xmlns:dc=3D"http://purl.org/dc/terms/">
>> =A0 =A0 =A0 =A0 =A0 =A0<dc:description>This will be returned ...</dc:des=
cription>
>> =A0 =A0 =A0 =A0 =A0</xs:appinfo>
>> =A0 =A0 =A0 =A0</xs:annotation>
>> =A0 =A0 =A0</xs:element>
>>
>> =A0 =A0 =A0<xs:element name=3D"simpleError" type=3D"xs:string">
>> =A0 =A0 =A0 =A0<xs:annotation>
>> =A0 =A0 =A0 =A0 =A0<xs:appinfo xmlns:dc=3D"http://purl.org/dc/terms/">
>> =A0 =A0 =A0 =A0 =A0 =A0<dc:description>Thrown if ...</dc:description>
>> =A0 =A0 =A0 =A0 =A0</xs:appinfo>
>> =A0 =A0 =A0 =A0</xs:annotation>
>> =A0 =A0 =A0</xs:element>
>> =A0 =A0</xs:schema>
>> =A0</types>
>>
>> =A0<interface name=3D"webServiceInterface" >
>>
>> =A0 =A0 =A0 =A0<fault name=3D"simpleFault"
>> =A0 =A0 =A0 =A0 =A0 =A0element=3D"simpleError" />
>>
>> =A0 =A0 =A0 =A0<operation
>> =A0 =A0 =A0 =A0 =A0 =A0name=3D"SimpleOperation"
>> =A0 =A0 =A0 =A0 =A0 =A0pattern=3D"http://www.w3.org/ns/wsdl/in-out"
>> =A0 =A0 =A0 =A0 =A0 =A0style=3D"http://www.3w.org/ns/wsdl/style/iri"
>> =A0 =A0 =A0 =A0 =A0 =A0wsdlx:safe=3D"true">
>>
>> =A0 =A0 =A0 =A0 =A0 =A0<input
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0messageLabel=3D"In"
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0element=3D"request" />
>>
>> =A0 =A0 =A0 =A0 =A0 =A0<out
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0messageLabel=3D"Out"
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0element=3D"response" />
>>
>> =A0 =A0 =A0 =A0 =A0 =A0<outfault
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0ref=3D"simpleFault"
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0messageLabel=3D"Out" />
>>
>> =A0 =A0 =A0 =A0 =A0 =A0<documentation>
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0<dc:description>This is the method's descript=
ion ...
>> </dc:description>
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0<dc:creator>Developer</dc:creator>
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0<dc:relation>AnotherOperation</dc:relation>
>> =A0 =A0 =A0 =A0 =A0 =A0</ documentation >
>> =A0 =A0 =A0</operation>
>>
>> =A0 =A0 =A0<operation
>> =A0 =A0 =A0 =A0 =A0 =A0name=3D"AnotherOperation"
>> =A0 =A0 =A0 =A0 =A0 =A0pattern=3D"http://www.w3.org/ns/wsdl/in-out" ...
>>
>> =A0...
>> </description>
>>
>>
>> The proxy's method should be annotated like the following:
>>
>> /**
>> =A0* This is the method's description ...
>> =A0* @param request This parameter represents ...
>> =A0* @return This will be returned ...
>> =A0* @see AnotherOperation
>> =A0* @throws SimpleFault Thrown if ...
>> =A0* @author Developer
>> public Response SimpleOperation (Request ...
>> =A0...
>> }
>>
>> Hope that I could explain what I intended with my proposal by providing
>> this simplified example, which has to be worked out in more detail of
>> course.
>> Thanks.
>> Marcel
>>
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: java-dev-unsubscribe@axis.apache.org
>> For additional commands, e-mail: java-dev-help@axis.apache.org
>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@axis.apache.org
> For additional commands, e-mail: java-dev-help@axis.apache.org
>
>
> --
> Sanjiva Weerawarana, Ph.D.
> Founder, Director & Chief Scientist; Lanka Software Foundation;
> http://www.opensource.lk/
> Founder, Chairman & CEO; WSO2, Inc.; http://www.wso2.com/
> Member; Apache Software Foundation; http://www.apache.org/
> Director; Sahana Software Foundation; http://www.sahanafoundation.org/
> Visiting Lecturer; University of Moratuwa; http://www.cse.mrt.ac.lk/
>
> Blog: http://sanjiva.weerawarana.org/

---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@axis.apache.org
For additional commands, e-mail: java-dev-help@axis.apache.org