[prev in list] [next in list] [prev in thread] [next in thread] 

List:       axis-dev
Subject:    thoughts on getting documentation into auto-generated WSDL files
From:       "Jay Glanville" <Jay.Glanville () naturalconvergence ! com>
Date:       2005-06-30 14:30:24
Message-ID: AF72D46D56403D45AF5441A2D92F8670841A41 () server01 ! NaturalConvergence ! com
[Download RAW message or body]

I rely upon the java2wsdl utilities to generate my WSDL (yes, I know
that it should be the other way around [WSDL first, then code], but in
my department, the API comes first as more people rely upon it then the
web service).
 
It would be excellent if I could get my documentation from the javadocs
into the WSDL.  This would be great as it would make my WSDL document a
single point of reference for my customers.  If they want a human
readable version of the document, they could run wsdldoc on it or
something similar.
 
I know that several other people have stated that they would love such a
feature.  I've also gleamed from the mailing list that there is a
problem getting the documentation from the source as java2wsdl doesn't
actually look at the source: it looks at the compiled classes, which
don't contain any comments.
 
As I was thinking about this on the drive home yesterday, two possible
solutions occurred to me.  I thought I'd throw them out into the
development community to get some feedback, or to spark an even better
idea.



Solution 1: use java 5's annotation feature.

Sol 1 Implementation -- Axis creates some annotation structures that can
be used by developers to indicate several things:
- which methods are service methods
- which classes should be exported as complexTypes, plus
  - the beanMapping information
  - the typeMapping information (de/serializer, etc)
- the documentation that should be attached with each of the above
(messages, complexTypes, complexType's elements, etc)

Sol 1 Pros -- imagine, no need to maintain configuration files (well,
not "no need".  There would probably still be some configuration files
necessary, but their maintenance would be drastically reduced).  Imagine
the configuration: write a set of java files that define your service
(messages/methods and complexTypes/classes), jar them, and then simply
hand it off to Axis.  Axis could then scan the jar file looking for
message implementers and complex types using an annotation processor,
and then run your service.

Sol 1 Cons -- the biggest problem with JDK 5 Annotations, is, well, that
it requires JDK 5.  Not everybody that uses Axis wants to be forced to
use this version.



Solution 2: "Tag" the generated WSDL file

Sol 2 Implementation -- when axis's internal WSDL generator (or the
external java2wsdl tool) generates the file, it tags the entries with
computer parsible information indicating where the source of this entry
was found.  Then, the WSDL file could be post-processed by a tool (that
the developer would write themselves) that could parse the WSDL,
replacing the tags with the desired information.

For example, have a look at this WSDL snippet:
   <complexType name="SystemProperty">
    <!-- source:com.mycompany.domain.SystemPropertyBean -->
    <sequence>
     <element name="systemId" ...>
      <!-- source:com.mycompany.domain.SystemPropertyBean.systemId -->
     </element>
    </sequence>
   </complexType>
   <complexType name="Zone">
    <!-- source:com.mycompany.domain.ZoneBean -->
    <complexContent>
     <extension base="tns2:AbstractDomainObject">
      <sequence>
       <element name="timeZone" ...>
        <!-- source:com.mycompany.domain.ZoneBean.timeZone -->
       </element>
...
   <wsdl:message name="performActionX">
      <!-- source:com.mycompany.api.Service.performActionX -->
      <wsdl:part name="paramOne" type="xsd:int">
        <!-- source:com.mycompany.api.Service.performActionX.paramOne
-->
      </wsdl:part>
   </wsdl:message>
You can see that the complexType elements had a comment inside of them
giving the fully qualified class name.  For the elements within the
complexType, the comment contained the fully qualified attribute name.
For messages, the comment contained the fully qualified method name.
For message parameters / parts, the comment was the fully qualified
method name cat-ed with the parameter name.

Sol 2 Pros -- the WSDL generator wouldn't need to change that much.  It
already has the fully-qualified names of the components in question.
The tags are just XML comments, and the comments themselves are absolute
(1-to-1).  Then, all I would have to do is make a simple tool that would
look for regular expressions of the type "<!-- source:(.*) -->", and
look up in the comment for that element in a mapping file or the source.
Once I have that comment, I can replace the line with a <wsdl:document>
tag.

Sol 2 Cons -- A very minor con with this solution is that somebody might
say, "putting the fully-qualified names into the WSDL exposes how we do
things internally."  Well, the comments can be stripped out.  Other then
that, I can't really think of any cons.



I'm assuming that someone is going to say, "Use XDoclet".  As it stands
now, XDoclet provides only minimal support for axis.  It will generate
the message portion of the WSDL.  It does not support complexTypes.
Further custom tags would need to be implemented in order to get this
functionality.  If someone can point me to an XDoclet solution that will
generate my WSDL file plus documentation, PLEASE LET ME KNOW, please.



So, what do you think?

Is there another solution out there?

Is there a better way to implement the solutions I've presented?



 

If you've gotten to this line, thanks for reading the entire thing.  ;-)

JDG 
 
---
Jay Dickon Glanville


[prev in list] [next in list] [prev in thread] [next in thread]