You are viewing a plain text version of this content. The canonical link for it is here.
Posted to rampart-dev@ws.apache.org by "Heusinger, Marcel" <ma...@uni-due.de> on 2010/04/08 10:20:31 UTC
Apache mentoring programme
Dear Axis2-developer community,
some days ago I read about the Apache Mentoring Programme
(http://community.apache.org/mentoringprogramme.html
<http://community.apache.org/mentoringprogramme.html> ) and I thought it
would be a chance to contribute to one of the Apache projects. As I
worked with Axis2 during the last few month, I wondered if one of the
contributors would declare her-/himself ready to comply with mentoring
me. As you can see below I already got some experiences in software
development, so I feel confident to achieve the project idea outlined at
the e-mail's end. Although mentoring causes some extra work, I think the
proposed project is straightforward so that I could familiarize myself
with the Axis2 project and make valuable contributions after the program
in the form of patches and so on. Below you find some more about myself
and my proposed Mentoring Programme idea. Thank you for your attention.
A brief CV
---------------------
My name is Marcel Heusinger, 28 years old, finished my studies of
information systems some month ago, and I live in Essen, Germany.
Currently, I am working in my fourth year at the University of
Duisburg-Essen (most of the time as part-time student assistant; the
last five month as research assistant), where I worked on projects with
Java and PHP. The source code of two of my projects can be found at
http://www.mycore.de/viewvc/viewvc.cgi/miless/trunk/module-blackboard/
<http://www.mycore.de/viewvc/viewvc.cgi/miless/trunk/module-blackboard/>
and http://www.mycore.de/viewvc/viewvc.cgi/miless/trunk/module-moodle/
<http://www.mycore.de/viewvc/viewvc.cgi/miless/trunk/module-moodle/> .
Both of these projects integrated the Web service functionalities of the
open-source documentation and publication server miless
(http://duepublico.uni-duisburg-essen.de/
<http://duepublico.uni-duisburg-essen.de/> ) into the e-learning
management systems Moodle and Blackboard respectively. At the moment I
am working on a jBPM-based workflow application to support the library's
processes.
During all these projects I gained solid understanding of Web service
standards like Xml Schemas, WSDL, and SOAP and I worked with tools like
Eclipse, Ant, and Maven. Furthermore, I already had a quick flip through
the Axis2 source code. So the mentoring related extra work would narrow
down to Axis2 implementation questions and how to integration my
contribution into the total project structure.
My project idea
---------------------
Main idea: Generate JavaDoc documentation for client-side code/Web
service proxy that was generated with Axis2. It would be much easier to
work with generated proxies if its method would be documented.
How it should be accomplished: As it is possible to annotate Xml schema
files with an annotation element which itself could contain Dublin core
elements. As these Dublin Core elements could be refined without
jeopardizing applications that do not understand the refinement as long
as they are able to understand the RDF-based refinement mechanism. This
mechanism could be used to define a Dublin Core Application Profile
(http://dublincore.org/documents/profile-guidelines/
<http://dublincore.org/documents/profile-guidelines/> and
http://dublincore.org/documents/singapore-framework/
<http://dublincore.org/documents/singapore-framework/> ) that could be
used to create a mapping between the refined elements and JavaDoc tags.
This application profile and the mapping could be used to add JavaDoc
tags to the proxy code that is generated by Axis2, if the Xml schema
uses the annotation element in conjunction with refined Dublin Core
elements.
As I am not that deep into Axis2 and its roadmap, and you think that
idea would be useless or have any other plans, I would be happy to
participate at the project anyway. Thank you!
If you have any questions, do not hesitate to ask.=20
Looking forward to hear from you.
Kind regards,
Marcel Heusinger
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
On Tue, May 4, 2010 at 09:57, Heusinger, Marcel
<ma...@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’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 names[7]:
>
> (1) documentation should be added to xs:documentation instead of xs:appinfo
>
> (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 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 documenting.
>
> -------------------------
>
> 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 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 “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 process.”[5]
>
> 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.
>
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 into
> such a project.
>
> Therefore: Does anybody has another idea or an appropriate issue that could
> 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 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 [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 on
> things you can do?
>
>
>
> Sanjiva.
>
> On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen <an...@gmail.com>
> 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=172
> [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
>
> <ma...@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="http://www.w3.org/ns/wsdl"
>> xmlns:dc="http://purl.org/dc/terms/" ...>
>> <types>
>> <xs:schema ...
>> <xs:element name="request" type="xs:string">
>> <xs:annotation>
>> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
>> <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="http://purl.org/dc/terms/">
>> <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="http://purl.org/dc/terms/">
>> <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="http://www.w3.org/ns/wsdl/in-out"
>> style="http://www.3w.org/ns/wsdl/style/iri"
>> 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="http://www.w3.org/ns/wsdl/in-out" ...
>>
>> ...
>> </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 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
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
On Tue, May 4, 2010 at 09:57, Heusinger, Marcel
<ma...@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’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 names[7]:
>
> (1) documentation should be added to xs:documentation instead of xs:appinfo
>
> (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 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 documenting.
>
> -------------------------
>
> 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 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 “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 process.”[5]
>
> 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.
>
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 into
> such a project.
>
> Therefore: Does anybody has another idea or an appropriate issue that could
> 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 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 [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 on
> things you can do?
>
>
>
> Sanjiva.
>
> On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen <an...@gmail.com>
> 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=172
> [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
>
> <ma...@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="http://www.w3.org/ns/wsdl"
>> xmlns:dc="http://purl.org/dc/terms/" ...>
>> <types>
>> <xs:schema ...
>> <xs:element name="request" type="xs:string">
>> <xs:annotation>
>> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
>> <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="http://purl.org/dc/terms/">
>> <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="http://purl.org/dc/terms/">
>> <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="http://www.w3.org/ns/wsdl/in-out"
>> style="http://www.3w.org/ns/wsdl/style/iri"
>> 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="http://www.w3.org/ns/wsdl/in-out" ...
>>
>> ...
>> </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 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
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
On Tue, May 4, 2010 at 09:57, Heusinger, Marcel
<ma...@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’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 names[7]:
>
> (1) documentation should be added to xs:documentation instead of xs:appinfo
>
> (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 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 documenting.
>
> -------------------------
>
> 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 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 “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 process.”[5]
>
> 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.
>
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 into
> such a project.
>
> Therefore: Does anybody has another idea or an appropriate issue that could
> 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 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 [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 on
> things you can do?
>
>
>
> Sanjiva.
>
> On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen <an...@gmail.com>
> 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=172
> [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
>
> <ma...@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="http://www.w3.org/ns/wsdl"
>> xmlns:dc="http://purl.org/dc/terms/" ...>
>> <types>
>> <xs:schema ...
>> <xs:element name="request" type="xs:string">
>> <xs:annotation>
>> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
>> <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="http://purl.org/dc/terms/">
>> <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="http://purl.org/dc/terms/">
>> <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="http://www.w3.org/ns/wsdl/in-out"
>> style="http://www.3w.org/ns/wsdl/style/iri"
>> 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="http://www.w3.org/ns/wsdl/in-out" ...
>>
>> ...
>> </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 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
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
On Tue, May 4, 2010 at 09:57, Heusinger, Marcel
<ma...@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’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 names[7]:
>
> (1) documentation should be added to xs:documentation instead of xs:appinfo
>
> (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 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 documenting.
>
> -------------------------
>
> 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 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 “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 process.”[5]
>
> 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.
>
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 into
> such a project.
>
> Therefore: Does anybody has another idea or an appropriate issue that could
> 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 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 [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 on
> things you can do?
>
>
>
> Sanjiva.
>
> On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen <an...@gmail.com>
> 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=172
> [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
>
> <ma...@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="http://www.w3.org/ns/wsdl"
>> xmlns:dc="http://purl.org/dc/terms/" ...>
>> <types>
>> <xs:schema ...
>> <xs:element name="request" type="xs:string">
>> <xs:annotation>
>> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
>> <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="http://purl.org/dc/terms/">
>> <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="http://purl.org/dc/terms/">
>> <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="http://www.w3.org/ns/wsdl/in-out"
>> style="http://www.3w.org/ns/wsdl/style/iri"
>> 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="http://www.w3.org/ns/wsdl/in-out" ...
>>
>> ...
>> </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 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
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
On Tue, May 4, 2010 at 09:57, Heusinger, Marcel
<ma...@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’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 names[7]:
>
> (1) documentation should be added to xs:documentation instead of xs:appinfo
>
> (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 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 documenting.
>
> -------------------------
>
> 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 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 “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 process.”[5]
>
> 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.
>
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 into
> such a project.
>
> Therefore: Does anybody has another idea or an appropriate issue that could
> 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 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 [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 on
> things you can do?
>
>
>
> Sanjiva.
>
> On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen <an...@gmail.com>
> 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=172
> [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
>
> <ma...@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="http://www.w3.org/ns/wsdl"
>> xmlns:dc="http://purl.org/dc/terms/" ...>
>> <types>
>> <xs:schema ...
>> <xs:element name="request" type="xs:string">
>> <xs:annotation>
>> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
>> <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="http://purl.org/dc/terms/">
>> <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="http://purl.org/dc/terms/">
>> <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="http://www.w3.org/ns/wsdl/in-out"
>> style="http://www.3w.org/ns/wsdl/style/iri"
>> 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="http://www.w3.org/ns/wsdl/in-out" ...
>>
>> ...
>> </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 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
AW: Apache mentoring programme
Posted by "Heusinger, Marcel" <ma...@uni-due.de>.
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
names[7]:
(1) documentation should be added to xs:documentation instead of
xs:appinfo
(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
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
documenting.
-------------------------
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
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 "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
process."[5]
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,
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
<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
<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
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 [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 on things you can do?
Sanjiva.
On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen
<an...@gmail.com> 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=172
[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
<ma...@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="http://www.w3.org/ns/wsdl"
> xmlns:dc="http://purl.org/dc/terms/" ...>
> <types>
> <xs:schema ...
> <xs:element name="request" type="xs:string">
> <xs:annotation>
> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://www.w3.org/ns/wsdl/in-out"
> style="http://www.3w.org/ns/wsdl/style/iri"
> 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="http://www.w3.org/ns/wsdl/in-out" ...
>
> ...
> </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
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/
AW: Apache mentoring programme
Posted by "Heusinger, Marcel" <ma...@uni-due.de>.
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
names[7]:
(1) documentation should be added to xs:documentation instead of
xs:appinfo
(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
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
documenting.
-------------------------
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
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 "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
process."[5]
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,
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
<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
<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
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 [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 on things you can do?
Sanjiva.
On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen
<an...@gmail.com> 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=172
[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
<ma...@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="http://www.w3.org/ns/wsdl"
> xmlns:dc="http://purl.org/dc/terms/" ...>
> <types>
> <xs:schema ...
> <xs:element name="request" type="xs:string">
> <xs:annotation>
> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://www.w3.org/ns/wsdl/in-out"
> style="http://www.3w.org/ns/wsdl/style/iri"
> 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="http://www.w3.org/ns/wsdl/in-out" ...
>
> ...
> </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
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/
AW: Apache mentoring programme
Posted by "Heusinger, Marcel" <ma...@uni-due.de>.
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
names[7]:
(1) documentation should be added to xs:documentation instead of
xs:appinfo
(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
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
documenting.
-------------------------
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
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 "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
process."[5]
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,
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
<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
<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
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 [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 on things you can do?
Sanjiva.
On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen
<an...@gmail.com> 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=172
[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
<ma...@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="http://www.w3.org/ns/wsdl"
> xmlns:dc="http://purl.org/dc/terms/" ...>
> <types>
> <xs:schema ...
> <xs:element name="request" type="xs:string">
> <xs:annotation>
> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://www.w3.org/ns/wsdl/in-out"
> style="http://www.3w.org/ns/wsdl/style/iri"
> 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="http://www.w3.org/ns/wsdl/in-out" ...
>
> ...
> </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
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/
AW: Apache mentoring programme
Posted by "Heusinger, Marcel" <ma...@uni-due.de>.
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
names[7]:
(1) documentation should be added to xs:documentation instead of
xs:appinfo
(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
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
documenting.
-------------------------
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
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 "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
process."[5]
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,
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
<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
<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
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 [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 on things you can do?
Sanjiva.
On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen
<an...@gmail.com> 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=172
[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
<ma...@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="http://www.w3.org/ns/wsdl"
> xmlns:dc="http://purl.org/dc/terms/" ...>
> <types>
> <xs:schema ...
> <xs:element name="request" type="xs:string">
> <xs:annotation>
> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://www.w3.org/ns/wsdl/in-out"
> style="http://www.3w.org/ns/wsdl/style/iri"
> 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="http://www.w3.org/ns/wsdl/in-out" ...
>
> ...
> </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
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/
AW: Apache mentoring programme
Posted by "Heusinger, Marcel" <ma...@uni-due.de>.
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
names[7]:
(1) documentation should be added to xs:documentation instead of
xs:appinfo
(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
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
documenting.
-------------------------
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
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 "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
process."[5]
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,
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
<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
<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
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 [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 on things you can do?
Sanjiva.
On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen
<an...@gmail.com> 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=172
[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
<ma...@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="http://www.w3.org/ns/wsdl"
> xmlns:dc="http://purl.org/dc/terms/" ...>
> <types>
> <xs:schema ...
> <xs:element name="request" type="xs:string">
> <xs:annotation>
> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://www.w3.org/ns/wsdl/in-out"
> style="http://www.3w.org/ns/wsdl/style/iri"
> 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="http://www.w3.org/ns/wsdl/in-out" ...
>
> ...
> </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
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/
Re: Apache mentoring programme
Posted by Sanjiva Weerawarana <sa...@opensource.lk>.
+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?
Sanjiva.
On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen
<an...@gmail.com>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=172
> [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
> <ma...@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="http://www.w3.org/ns/wsdl"
> > xmlns:dc="http://purl.org/dc/terms/" ...>
> > <types>
> > <xs:schema ...
> > <xs:element name="request" type="xs:string">
> > <xs:annotation>
> > <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> > <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="http://purl.org/dc/terms/">
> > <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="http://purl.org/dc/terms/">
> > <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="http://www.w3.org/ns/wsdl/in-out"
> > style="http://www.3w.org/ns/wsdl/style/iri"
> > 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="http://www.w3.org/ns/wsdl/in-out" ...
> >
> > ...
> > </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 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/
Re: Apache mentoring programme
Posted by Sanjiva Weerawarana <sa...@opensource.lk>.
+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?
Sanjiva.
On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen
<an...@gmail.com>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=172
> [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
> <ma...@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="http://www.w3.org/ns/wsdl"
> > xmlns:dc="http://purl.org/dc/terms/" ...>
> > <types>
> > <xs:schema ...
> > <xs:element name="request" type="xs:string">
> > <xs:annotation>
> > <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> > <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="http://purl.org/dc/terms/">
> > <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="http://purl.org/dc/terms/">
> > <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="http://www.w3.org/ns/wsdl/in-out"
> > style="http://www.3w.org/ns/wsdl/style/iri"
> > 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="http://www.w3.org/ns/wsdl/in-out" ...
> >
> > ...
> > </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 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/
Re: Apache mentoring programme
Posted by Sanjiva Weerawarana <sa...@opensource.lk>.
+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?
Sanjiva.
On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen
<an...@gmail.com>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=172
> [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
> <ma...@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="http://www.w3.org/ns/wsdl"
> > xmlns:dc="http://purl.org/dc/terms/" ...>
> > <types>
> > <xs:schema ...
> > <xs:element name="request" type="xs:string">
> > <xs:annotation>
> > <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> > <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="http://purl.org/dc/terms/">
> > <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="http://purl.org/dc/terms/">
> > <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="http://www.w3.org/ns/wsdl/in-out"
> > style="http://www.3w.org/ns/wsdl/style/iri"
> > 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="http://www.w3.org/ns/wsdl/in-out" ...
> >
> > ...
> > </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 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/
Re: Apache mentoring programme
Posted by Sanjiva Weerawarana <sa...@opensource.lk>.
+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?
Sanjiva.
On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen
<an...@gmail.com>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=172
> [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
> <ma...@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="http://www.w3.org/ns/wsdl"
> > xmlns:dc="http://purl.org/dc/terms/" ...>
> > <types>
> > <xs:schema ...
> > <xs:element name="request" type="xs:string">
> > <xs:annotation>
> > <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> > <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="http://purl.org/dc/terms/">
> > <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="http://purl.org/dc/terms/">
> > <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="http://www.w3.org/ns/wsdl/in-out"
> > style="http://www.3w.org/ns/wsdl/style/iri"
> > 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="http://www.w3.org/ns/wsdl/in-out" ...
> >
> > ...
> > </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 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/
Re: Apache mentoring programme
Posted by Sanjiva Weerawarana <sa...@opensource.lk>.
+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?
Sanjiva.
On Tue, Apr 20, 2010 at 2:22 AM, Andreas Veithen
<an...@gmail.com>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=172
> [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
> <ma...@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="http://www.w3.org/ns/wsdl"
> > xmlns:dc="http://purl.org/dc/terms/" ...>
> > <types>
> > <xs:schema ...
> > <xs:element name="request" type="xs:string">
> > <xs:annotation>
> > <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> > <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="http://purl.org/dc/terms/">
> > <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="http://purl.org/dc/terms/">
> > <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="http://www.w3.org/ns/wsdl/in-out"
> > style="http://www.3w.org/ns/wsdl/style/iri"
> > 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="http://www.w3.org/ns/wsdl/in-out" ...
> >
> > ...
> > </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 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/
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
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=172
[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
<ma...@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="http://www.w3.org/ns/wsdl"
> xmlns:dc="http://purl.org/dc/terms/" ...>
> <types>
> <xs:schema ...
> <xs:element name="request" type="xs:string">
> <xs:annotation>
> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://www.w3.org/ns/wsdl/in-out"
> style="http://www.3w.org/ns/wsdl/style/iri"
> 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="http://www.w3.org/ns/wsdl/in-out" ...
>
> ...
> </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 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
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
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=172
[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
<ma...@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="http://www.w3.org/ns/wsdl"
> xmlns:dc="http://purl.org/dc/terms/" ...>
> <types>
> <xs:schema ...
> <xs:element name="request" type="xs:string">
> <xs:annotation>
> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://www.w3.org/ns/wsdl/in-out"
> style="http://www.3w.org/ns/wsdl/style/iri"
> 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="http://www.w3.org/ns/wsdl/in-out" ...
>
> ...
> </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 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
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
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=172
[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
<ma...@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="http://www.w3.org/ns/wsdl"
> xmlns:dc="http://purl.org/dc/terms/" ...>
> <types>
> <xs:schema ...
> <xs:element name="request" type="xs:string">
> <xs:annotation>
> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://www.w3.org/ns/wsdl/in-out"
> style="http://www.3w.org/ns/wsdl/style/iri"
> 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="http://www.w3.org/ns/wsdl/in-out" ...
>
> ...
> </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 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
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
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=172
[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
<ma...@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="http://www.w3.org/ns/wsdl"
> xmlns:dc="http://purl.org/dc/terms/" ...>
> <types>
> <xs:schema ...
> <xs:element name="request" type="xs:string">
> <xs:annotation>
> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://www.w3.org/ns/wsdl/in-out"
> style="http://www.3w.org/ns/wsdl/style/iri"
> 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="http://www.w3.org/ns/wsdl/in-out" ...
>
> ...
> </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 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
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
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=172
[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
<ma...@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="http://www.w3.org/ns/wsdl"
> xmlns:dc="http://purl.org/dc/terms/" ...>
> <types>
> <xs:schema ...
> <xs:element name="request" type="xs:string">
> <xs:annotation>
> <xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://purl.org/dc/terms/">
> <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="http://www.w3.org/ns/wsdl/in-out"
> style="http://www.3w.org/ns/wsdl/style/iri"
> 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="http://www.w3.org/ns/wsdl/in-out" ...
>
> ...
> </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 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
AW: Apache mentoring programme
Posted by "Heusinger, Marcel" <ma...@uni-due.de>.
>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="http://www.w3.org/ns/wsdl"
xmlns:dc="http://purl.org/dc/terms/" ...>
<types>
<xs:schema ...
<xs:element name="request" type="xs:string">
<xs:annotation>
<xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
<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="http://purl.org/dc/terms/">
<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="http://purl.org/dc/terms/">
<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="http://www.w3.org/ns/wsdl/in-out"
style="http://www.3w.org/ns/wsdl/style/iri"
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="http://www.w3.org/ns/wsdl/in-out" ...
...
</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 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
AW: Apache mentoring programme
Posted by "Heusinger, Marcel" <ma...@uni-due.de>.
>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="http://www.w3.org/ns/wsdl"
xmlns:dc="http://purl.org/dc/terms/" ...>
<types>
<xs:schema ...
<xs:element name="request" type="xs:string">
<xs:annotation>
<xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
<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="http://purl.org/dc/terms/">
<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="http://purl.org/dc/terms/">
<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="http://www.w3.org/ns/wsdl/in-out"
style="http://www.3w.org/ns/wsdl/style/iri"
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="http://www.w3.org/ns/wsdl/in-out" ...
...
</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 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
AW: Apache mentoring programme
Posted by "Heusinger, Marcel" <ma...@uni-due.de>.
>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="http://www.w3.org/ns/wsdl"
xmlns:dc="http://purl.org/dc/terms/" ...>
<types>
<xs:schema ...
<xs:element name="request" type="xs:string">
<xs:annotation>
<xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
<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="http://purl.org/dc/terms/">
<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="http://purl.org/dc/terms/">
<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="http://www.w3.org/ns/wsdl/in-out"
style="http://www.3w.org/ns/wsdl/style/iri"
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="http://www.w3.org/ns/wsdl/in-out" ...
...
</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 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
AW: Apache mentoring programme
Posted by "Heusinger, Marcel" <ma...@uni-due.de>.
>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="http://www.w3.org/ns/wsdl"
xmlns:dc="http://purl.org/dc/terms/" ...>
<types>
<xs:schema ...
<xs:element name="request" type="xs:string">
<xs:annotation>
<xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
<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="http://purl.org/dc/terms/">
<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="http://purl.org/dc/terms/">
<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="http://www.w3.org/ns/wsdl/in-out"
style="http://www.3w.org/ns/wsdl/style/iri"
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="http://www.w3.org/ns/wsdl/in-out" ...
...
</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 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
AW: Apache mentoring programme
Posted by "Heusinger, Marcel" <ma...@uni-due.de>.
>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="http://www.w3.org/ns/wsdl"
xmlns:dc="http://purl.org/dc/terms/" ...>
<types>
<xs:schema ...
<xs:element name="request" type="xs:string">
<xs:annotation>
<xs:appinfo xmlns:dc="http://purl.org/dc/terms/">
<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="http://purl.org/dc/terms/">
<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="http://purl.org/dc/terms/">
<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="http://www.w3.org/ns/wsdl/in-out"
style="http://www.3w.org/ns/wsdl/style/iri"
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="http://www.w3.org/ns/wsdl/in-out" ...
...
</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 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
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
On Thu, Apr 8, 2010 at 10:20, Heusinger, Marcel
<ma...@uni-due.de> wrote:
> Dear Axis2-developer community,
>
>
>
> some days ago I read about the Apache Mentoring Programme
> (http://community.apache.org/mentoringprogramme.html) and I thought it would
> be a chance to contribute to one of the Apache projects. As I worked with
> Axis2 during the last few month, I wondered if one of the contributors would
> declare her-/himself ready to comply with mentoring me. As you can see below
> I already got some experiences in software development, so I feel confident
> to achieve the project idea outlined at the e-mail's end. Although mentoring
> causes some extra work, I think the proposed project is straightforward so
> that I could familiarize myself with the Axis2 project and make valuable
> contributions after the program in the form of patches and so on. Below you
> find some more about myself and my proposed Mentoring Programme idea. Thank
> you for your attention.
>
>
>
> A brief CV
>
> ---------------------
>
> My name is Marcel Heusinger, 28 years old, finished my studies of
> information systems some month ago, and I live in Essen, Germany.
>
> Currently, I am working in my fourth year at the University of
> Duisburg-Essen (most of the time as part-time student assistant; the last
> five month as research assistant), where I worked on projects with Java and
> PHP. The source code of two of my projects can be found at
> http://www.mycore.de/viewvc/viewvc.cgi/miless/trunk/module-blackboard/
>
> and http://www.mycore.de/viewvc/viewvc.cgi/miless/trunk/module-moodle/.
>
> Both of these projects integrated the Web service functionalities of the
> open-source documentation and publication server miless
> (http://duepublico.uni-duisburg-essen.de/) into the e-learning management
> systems Moodle and Blackboard respectively. At the moment I am working on a
> jBPM-based workflow application to support the library's processes.
>
> During all these projects I gained solid understanding of Web service
> standards like Xml Schemas, WSDL, and SOAP and I worked with tools like
> Eclipse, Ant, and Maven. Furthermore, I already had a quick flip through the
> Axis2 source code. So the mentoring related extra work would narrow down to
> Axis2 implementation questions and how to integration my contribution into
> the total project structure.
>
>
>
> My project idea
>
> ---------------------
>
> Main idea: Generate JavaDoc documentation for client-side code/Web service
> proxy that was generated with Axis2. It would be much easier to work with
> generated proxies if its method would be documented.
>
> How it should be accomplished: As it is possible to annotate Xml schema
> files with an annotation element which itself could contain Dublin core
> elements. As these Dublin Core elements could be refined without
> jeopardizing applications that do not understand the refinement as long as
> they are able to understand the RDF-based refinement mechanism. This
> mechanism could be used to define a Dublin Core Application Profile
> (http://dublincore.org/documents/profile-guidelines/ and
>
> http://dublincore.org/documents/singapore-framework/) that could be used to
> create a mapping between the refined elements and JavaDoc tags.
>
> This application profile and the mapping could be used to add JavaDoc tags
> to the proxy code that is generated by Axis2, if the Xml schema uses the
> annotation element in conjunction with refined Dublin Core elements.
>
>
>
> As I am not that deep into Axis2 and its roadmap, and you think that idea
> would be useless or have any other plans, I would be happy to participate at
> the project anyway. Thank you!
>
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
>
> If you have any questions, do not hesitate to ask.=20
>
>
>
> Looking forward to hear from you.
>
>
>
> Kind regards,
>
>
>
> Marcel Heusinger
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@axis.apache.org
For additional commands, e-mail: java-dev-help@axis.apache.org
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
On Thu, Apr 8, 2010 at 10:20, Heusinger, Marcel
<ma...@uni-due.de> wrote:
> Dear Axis2-developer community,
>
>
>
> some days ago I read about the Apache Mentoring Programme
> (http://community.apache.org/mentoringprogramme.html) and I thought it would
> be a chance to contribute to one of the Apache projects. As I worked with
> Axis2 during the last few month, I wondered if one of the contributors would
> declare her-/himself ready to comply with mentoring me. As you can see below
> I already got some experiences in software development, so I feel confident
> to achieve the project idea outlined at the e-mail's end. Although mentoring
> causes some extra work, I think the proposed project is straightforward so
> that I could familiarize myself with the Axis2 project and make valuable
> contributions after the program in the form of patches and so on. Below you
> find some more about myself and my proposed Mentoring Programme idea. Thank
> you for your attention.
>
>
>
> A brief CV
>
> ---------------------
>
> My name is Marcel Heusinger, 28 years old, finished my studies of
> information systems some month ago, and I live in Essen, Germany.
>
> Currently, I am working in my fourth year at the University of
> Duisburg-Essen (most of the time as part-time student assistant; the last
> five month as research assistant), where I worked on projects with Java and
> PHP. The source code of two of my projects can be found at
> http://www.mycore.de/viewvc/viewvc.cgi/miless/trunk/module-blackboard/
>
> and http://www.mycore.de/viewvc/viewvc.cgi/miless/trunk/module-moodle/.
>
> Both of these projects integrated the Web service functionalities of the
> open-source documentation and publication server miless
> (http://duepublico.uni-duisburg-essen.de/) into the e-learning management
> systems Moodle and Blackboard respectively. At the moment I am working on a
> jBPM-based workflow application to support the library's processes.
>
> During all these projects I gained solid understanding of Web service
> standards like Xml Schemas, WSDL, and SOAP and I worked with tools like
> Eclipse, Ant, and Maven. Furthermore, I already had a quick flip through the
> Axis2 source code. So the mentoring related extra work would narrow down to
> Axis2 implementation questions and how to integration my contribution into
> the total project structure.
>
>
>
> My project idea
>
> ---------------------
>
> Main idea: Generate JavaDoc documentation for client-side code/Web service
> proxy that was generated with Axis2. It would be much easier to work with
> generated proxies if its method would be documented.
>
> How it should be accomplished: As it is possible to annotate Xml schema
> files with an annotation element which itself could contain Dublin core
> elements. As these Dublin Core elements could be refined without
> jeopardizing applications that do not understand the refinement as long as
> they are able to understand the RDF-based refinement mechanism. This
> mechanism could be used to define a Dublin Core Application Profile
> (http://dublincore.org/documents/profile-guidelines/ and
>
> http://dublincore.org/documents/singapore-framework/) that could be used to
> create a mapping between the refined elements and JavaDoc tags.
>
> This application profile and the mapping could be used to add JavaDoc tags
> to the proxy code that is generated by Axis2, if the Xml schema uses the
> annotation element in conjunction with refined Dublin Core elements.
>
>
>
> As I am not that deep into Axis2 and its roadmap, and you think that idea
> would be useless or have any other plans, I would be happy to participate at
> the project anyway. Thank you!
>
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
>
> If you have any questions, do not hesitate to ask.=20
>
>
>
> Looking forward to hear from you.
>
>
>
> Kind regards,
>
>
>
> Marcel Heusinger
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@axis.apache.org
For additional commands, e-mail: java-dev-help@axis.apache.org
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
On Thu, Apr 8, 2010 at 10:20, Heusinger, Marcel
<ma...@uni-due.de> wrote:
> Dear Axis2-developer community,
>
>
>
> some days ago I read about the Apache Mentoring Programme
> (http://community.apache.org/mentoringprogramme.html) and I thought it would
> be a chance to contribute to one of the Apache projects. As I worked with
> Axis2 during the last few month, I wondered if one of the contributors would
> declare her-/himself ready to comply with mentoring me. As you can see below
> I already got some experiences in software development, so I feel confident
> to achieve the project idea outlined at the e-mail's end. Although mentoring
> causes some extra work, I think the proposed project is straightforward so
> that I could familiarize myself with the Axis2 project and make valuable
> contributions after the program in the form of patches and so on. Below you
> find some more about myself and my proposed Mentoring Programme idea. Thank
> you for your attention.
>
>
>
> A brief CV
>
> ---------------------
>
> My name is Marcel Heusinger, 28 years old, finished my studies of
> information systems some month ago, and I live in Essen, Germany.
>
> Currently, I am working in my fourth year at the University of
> Duisburg-Essen (most of the time as part-time student assistant; the last
> five month as research assistant), where I worked on projects with Java and
> PHP. The source code of two of my projects can be found at
> http://www.mycore.de/viewvc/viewvc.cgi/miless/trunk/module-blackboard/
>
> and http://www.mycore.de/viewvc/viewvc.cgi/miless/trunk/module-moodle/.
>
> Both of these projects integrated the Web service functionalities of the
> open-source documentation and publication server miless
> (http://duepublico.uni-duisburg-essen.de/) into the e-learning management
> systems Moodle and Blackboard respectively. At the moment I am working on a
> jBPM-based workflow application to support the library's processes.
>
> During all these projects I gained solid understanding of Web service
> standards like Xml Schemas, WSDL, and SOAP and I worked with tools like
> Eclipse, Ant, and Maven. Furthermore, I already had a quick flip through the
> Axis2 source code. So the mentoring related extra work would narrow down to
> Axis2 implementation questions and how to integration my contribution into
> the total project structure.
>
>
>
> My project idea
>
> ---------------------
>
> Main idea: Generate JavaDoc documentation for client-side code/Web service
> proxy that was generated with Axis2. It would be much easier to work with
> generated proxies if its method would be documented.
>
> How it should be accomplished: As it is possible to annotate Xml schema
> files with an annotation element which itself could contain Dublin core
> elements. As these Dublin Core elements could be refined without
> jeopardizing applications that do not understand the refinement as long as
> they are able to understand the RDF-based refinement mechanism. This
> mechanism could be used to define a Dublin Core Application Profile
> (http://dublincore.org/documents/profile-guidelines/ and
>
> http://dublincore.org/documents/singapore-framework/) that could be used to
> create a mapping between the refined elements and JavaDoc tags.
>
> This application profile and the mapping could be used to add JavaDoc tags
> to the proxy code that is generated by Axis2, if the Xml schema uses the
> annotation element in conjunction with refined Dublin Core elements.
>
>
>
> As I am not that deep into Axis2 and its roadmap, and you think that idea
> would be useless or have any other plans, I would be happy to participate at
> the project anyway. Thank you!
>
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
>
> If you have any questions, do not hesitate to ask.=20
>
>
>
> Looking forward to hear from you.
>
>
>
> Kind regards,
>
>
>
> Marcel Heusinger
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@axis.apache.org
For additional commands, e-mail: java-dev-help@axis.apache.org
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
On Thu, Apr 8, 2010 at 10:20, Heusinger, Marcel
<ma...@uni-due.de> wrote:
> Dear Axis2-developer community,
>
>
>
> some days ago I read about the Apache Mentoring Programme
> (http://community.apache.org/mentoringprogramme.html) and I thought it would
> be a chance to contribute to one of the Apache projects. As I worked with
> Axis2 during the last few month, I wondered if one of the contributors would
> declare her-/himself ready to comply with mentoring me. As you can see below
> I already got some experiences in software development, so I feel confident
> to achieve the project idea outlined at the e-mail's end. Although mentoring
> causes some extra work, I think the proposed project is straightforward so
> that I could familiarize myself with the Axis2 project and make valuable
> contributions after the program in the form of patches and so on. Below you
> find some more about myself and my proposed Mentoring Programme idea. Thank
> you for your attention.
>
>
>
> A brief CV
>
> ---------------------
>
> My name is Marcel Heusinger, 28 years old, finished my studies of
> information systems some month ago, and I live in Essen, Germany.
>
> Currently, I am working in my fourth year at the University of
> Duisburg-Essen (most of the time as part-time student assistant; the last
> five month as research assistant), where I worked on projects with Java and
> PHP. The source code of two of my projects can be found at
> http://www.mycore.de/viewvc/viewvc.cgi/miless/trunk/module-blackboard/
>
> and http://www.mycore.de/viewvc/viewvc.cgi/miless/trunk/module-moodle/.
>
> Both of these projects integrated the Web service functionalities of the
> open-source documentation and publication server miless
> (http://duepublico.uni-duisburg-essen.de/) into the e-learning management
> systems Moodle and Blackboard respectively. At the moment I am working on a
> jBPM-based workflow application to support the library's processes.
>
> During all these projects I gained solid understanding of Web service
> standards like Xml Schemas, WSDL, and SOAP and I worked with tools like
> Eclipse, Ant, and Maven. Furthermore, I already had a quick flip through the
> Axis2 source code. So the mentoring related extra work would narrow down to
> Axis2 implementation questions and how to integration my contribution into
> the total project structure.
>
>
>
> My project idea
>
> ---------------------
>
> Main idea: Generate JavaDoc documentation for client-side code/Web service
> proxy that was generated with Axis2. It would be much easier to work with
> generated proxies if its method would be documented.
>
> How it should be accomplished: As it is possible to annotate Xml schema
> files with an annotation element which itself could contain Dublin core
> elements. As these Dublin Core elements could be refined without
> jeopardizing applications that do not understand the refinement as long as
> they are able to understand the RDF-based refinement mechanism. This
> mechanism could be used to define a Dublin Core Application Profile
> (http://dublincore.org/documents/profile-guidelines/ and
>
> http://dublincore.org/documents/singapore-framework/) that could be used to
> create a mapping between the refined elements and JavaDoc tags.
>
> This application profile and the mapping could be used to add JavaDoc tags
> to the proxy code that is generated by Axis2, if the Xml schema uses the
> annotation element in conjunction with refined Dublin Core elements.
>
>
>
> As I am not that deep into Axis2 and its roadmap, and you think that idea
> would be useless or have any other plans, I would be happy to participate at
> the project anyway. Thank you!
>
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
>
> If you have any questions, do not hesitate to ask.=20
>
>
>
> Looking forward to hear from you.
>
>
>
> Kind regards,
>
>
>
> Marcel Heusinger
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@axis.apache.org
For additional commands, e-mail: java-dev-help@axis.apache.org
Re: Apache mentoring programme
Posted by Andreas Veithen <an...@gmail.com>.
On Thu, Apr 8, 2010 at 10:20, Heusinger, Marcel
<ma...@uni-due.de> wrote:
> Dear Axis2-developer community,
>
>
>
> some days ago I read about the Apache Mentoring Programme
> (http://community.apache.org/mentoringprogramme.html) and I thought it would
> be a chance to contribute to one of the Apache projects. As I worked with
> Axis2 during the last few month, I wondered if one of the contributors would
> declare her-/himself ready to comply with mentoring me. As you can see below
> I already got some experiences in software development, so I feel confident
> to achieve the project idea outlined at the e-mail's end. Although mentoring
> causes some extra work, I think the proposed project is straightforward so
> that I could familiarize myself with the Axis2 project and make valuable
> contributions after the program in the form of patches and so on. Below you
> find some more about myself and my proposed Mentoring Programme idea. Thank
> you for your attention.
>
>
>
> A brief CV
>
> ---------------------
>
> My name is Marcel Heusinger, 28 years old, finished my studies of
> information systems some month ago, and I live in Essen, Germany.
>
> Currently, I am working in my fourth year at the University of
> Duisburg-Essen (most of the time as part-time student assistant; the last
> five month as research assistant), where I worked on projects with Java and
> PHP. The source code of two of my projects can be found at
> http://www.mycore.de/viewvc/viewvc.cgi/miless/trunk/module-blackboard/
>
> and http://www.mycore.de/viewvc/viewvc.cgi/miless/trunk/module-moodle/.
>
> Both of these projects integrated the Web service functionalities of the
> open-source documentation and publication server miless
> (http://duepublico.uni-duisburg-essen.de/) into the e-learning management
> systems Moodle and Blackboard respectively. At the moment I am working on a
> jBPM-based workflow application to support the library's processes.
>
> During all these projects I gained solid understanding of Web service
> standards like Xml Schemas, WSDL, and SOAP and I worked with tools like
> Eclipse, Ant, and Maven. Furthermore, I already had a quick flip through the
> Axis2 source code. So the mentoring related extra work would narrow down to
> Axis2 implementation questions and how to integration my contribution into
> the total project structure.
>
>
>
> My project idea
>
> ---------------------
>
> Main idea: Generate JavaDoc documentation for client-side code/Web service
> proxy that was generated with Axis2. It would be much easier to work with
> generated proxies if its method would be documented.
>
> How it should be accomplished: As it is possible to annotate Xml schema
> files with an annotation element which itself could contain Dublin core
> elements. As these Dublin Core elements could be refined without
> jeopardizing applications that do not understand the refinement as long as
> they are able to understand the RDF-based refinement mechanism. This
> mechanism could be used to define a Dublin Core Application Profile
> (http://dublincore.org/documents/profile-guidelines/ and
>
> http://dublincore.org/documents/singapore-framework/) that could be used to
> create a mapping between the refined elements and JavaDoc tags.
>
> This application profile and the mapping could be used to add JavaDoc tags
> to the proxy code that is generated by Axis2, if the Xml schema uses the
> annotation element in conjunction with refined Dublin Core elements.
>
>
>
> As I am not that deep into Axis2 and its roadmap, and you think that idea
> would be useless or have any other plans, I would be happy to participate at
> the project anyway. Thank you!
>
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
>
> If you have any questions, do not hesitate to ask.=20
>
>
>
> Looking forward to hear from you.
>
>
>
> Kind regards,
>
>
>
> Marcel Heusinger
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@axis.apache.org
For additional commands, e-mail: java-dev-help@axis.apache.org