axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Hawkins, Peter" <Hawkins...@BATTELLE.ORG>
Subject emitting javadoc comments
Date Tue, 26 Aug 2003 19:03:36 GMT
I'm a newbie contributor - go easy.

In the WSDL2Java tool, we needed a way to preserve schema documentation for
types included in or imported to the WSDL.

For example:

	<element name="stateCode" type="usps:USStateCodeType"
nillable="true">
		<annotation>
			<documentation>
				A two-letter state code that represents the
state/territory/district of this address. Uses the
				enumerated type USStateCodeType. @see
				<![CDATA[
				<a
	
href="http://it.ojp.gov/jxdd/prerelease/usps_states/1.0.0.0/usps_states_full
-doc.xsd">
					USSTateCodeType Schema
				</a>
				]]></documentation>
		</annotation>
	</element>

yields:

	/** 
	 * A two-letter state code that represents the
state/territory/district of this address. Uses the enumerated type
USStateCodeType. 
	 * @see  <a
href="http://it.ojp.gov/jxdd/prerelease/usps_states/1.0.0.0/usps_states_full
-doc.xsd"> USSTateCodeType Schema </a> 
	 */
      private org.blah.USStateCodeType stateCode;

works for bean types (header comments), their fields, getter & setters.

(ignore the Eclipse files & lib jars)

[PATCH]
Index: .classpath
===================================================================
RCS file: .classpath
diff -N .classpath
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ .classpath	26 Aug 2003 18:52:14 -0000
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+    <classpathentry kind="src" path="java/src"/>
+    <classpathentry kind="con"
path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
+    <classpathentry kind="lib" path="java/lib/commons-discovery.jar"/>
+    <classpathentry kind="lib" path="java/lib/commons-logging.jar"/>
+    <classpathentry kind="lib" path="java/lib/log4j-1.2.8.jar"/>
+    <classpathentry kind="lib" path="java/lib/wsdl4j.jar"/>
+    <classpathentry kind="lib"
path="C:/DMIS_Development2_InteropShared_Pete/CMIS/lib/soap/activation.jar"/
>
+    <classpathentry kind="lib"
path="C:/DMIS_Development2_InteropShared_Pete/CMIS/lib/soap/jaxrpc.jar"/>
+    <classpathentry kind="lib"
path="C:/DMIS_Development2_InteropShared_Pete/CMIS/lib/soap/jox.jar"/>
+    <classpathentry kind="lib"
path="C:/DMIS_Development2_InteropShared_Pete/CMIS/lib/soap/log4j-1.2.8.jar"
/>
+    <classpathentry kind="lib"
path="C:/DMIS_Development2_InteropShared_Pete/CMIS/lib/soap/mail.jar"/>
+    <classpathentry kind="lib"
path="C:/DMIS_Development2_InteropShared_Pete/CMIS/lib/soap/saaj.jar"/>
+    <classpathentry kind="output" path="build_e"/>
+</classpath>
Index: .project
===================================================================
RCS file: .project
diff -N .project
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ .project	26 Aug 2003 18:52:14 -0000
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>xml-axis (CVS)</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.jdt.core.javabuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.jdt.core.javanature</nature>
+	</natures>
+</projectDescription>
Index: java/lib/activation.jar
===================================================================
RCS file: java/lib/activation.jar
diff -N java/lib/activation.jar
Binary files /dev/null and activation.jar differ
Index: java/lib/axis-ant.jar
===================================================================
RCS file: java/lib/axis-ant.jar
diff -N java/lib/axis-ant.jar
Binary files /dev/null and axis-ant.jar differ
Index: java/lib/mail.jar
===================================================================
RCS file: java/lib/mail.jar
diff -N java/lib/mail.jar
Binary files /dev/null and mail.jar differ
Index: java/lib/saaj.jar
===================================================================
RCS file: java/lib/saaj.jar
diff -N java/lib/saaj.jar
Binary files /dev/null and saaj.jar differ
Index: java/lib/servlet.jar
===================================================================
RCS file: java/lib/servlet.jar
diff -N java/lib/servlet.jar
Binary files /dev/null and servlet.jar differ
Index: java/src/org/apache/axis/wsdl/symbolTable/ElementDecl.java
===================================================================
RCS file:
/home/cvspublic/xml-axis/java/src/org/apache/axis/wsdl/symbolTable/ElementDe
cl.java,v
retrieving revision 1.5
diff -u -r1.5 ElementDecl.java
--- java/src/org/apache/axis/wsdl/symbolTable/ElementDecl.java	11 Aug 2003
21:25:28 -0000	1.5
+++ java/src/org/apache/axis/wsdl/symbolTable/ElementDecl.java	26 Aug 2003
18:52:21 -0000
@@ -67,6 +67,7 @@
 public class ElementDecl {
     private QName name;
     private TypeEntry type;
+    private String documentation;
     // The following property is set if minOccurs=0.
     // An item that is not set and has minOccurs=0 
     // should not be passed over the wire.  This
@@ -79,6 +80,16 @@
     // Indicate if the ElementDecl represents
     // an xsd:any element
     private boolean anyElement = false;
+
+	public String getDocumentation()
+	{
+		return documentation;
+	}
+
+	public void setDocumentation(String documentation)
+	{
+		this.documentation = documentation;
+	}
 
     public ElementDecl() {
     }
Index: java/src/org/apache/axis/wsdl/symbolTable/SchemaUtils.java
===================================================================
RCS file:
/home/cvspublic/xml-axis/java/src/org/apache/axis/wsdl/symbolTable/SchemaUti
ls.java,v
retrieving revision 1.26
diff -u -r1.26 SchemaUtils.java
--- java/src/org/apache/axis/wsdl/symbolTable/SchemaUtils.java	11 Aug 2003
21:25:28 -0000	1.26
+++ java/src/org/apache/axis/wsdl/symbolTable/SchemaUtils.java	26 Aug 2003
18:52:21 -0000
@@ -56,6 +56,7 @@
 
 import org.apache.axis.Constants;
 import org.apache.axis.utils.JavaUtils;
+import org.w3c.dom.DOMException;
 import org.w3c.dom.Node;
 import org.w3c.dom.NodeList;
 
@@ -65,6 +66,7 @@
 import java.util.Arrays;
 import java.util.HashSet;
 import java.util.Set;
+import java.util.StringTokenizer;
 import java.util.Vector;
 
 /**
@@ -321,7 +323,75 @@
         return v;
     }
 
+	/**
+	 * Returns named child node.
+	 * 
+	 * @param node Parent node.
+	 * @param name Element name of child node to return.
+	 */
+	private static Node getChildByName(Node parentNode, String name)
throws DOMException
+	{
+		if (parentNode == null) return null;
+		NodeList children = parentNode.getChildNodes();
+		if (children != null)
+		{
+			for (int i = 0; i < children.getLength(); i++)
+			{
+				Node child = children.item(i);
+				if (child != null)
+				{
+					if (child.getNodeName() != null &&
name.equals(child.getNodeName()))
+					{
+						return child;
+					}
+				}
+			}
+		}
+		return null;
+	}
 
+	/**
+	 * Returns all textual nodes of a subnode defined by a parent node
+	 * and a path of element names to that subnode.
+	 * 
+	 * @param node Parent node.
+	 * @param path Path of element names to text of interest, delimited
by "/". 
+	 */
+	public static String getTextByPath(Node root, String path) throws
DOMException
+	{
+		StringTokenizer st = new StringTokenizer(path, "/");
+		Node node = root;
+		while (st.hasMoreTokens())
+		{
+			String elementName = st.nextToken();
+			Node child = getChildByName(node, elementName);
+			if (child == null) 
+				throw new
DOMException(DOMException.NOT_FOUND_ERR, "could not find " + elementName);
+			node = child;	
+		}
+		
+		// should have found the node
+		String text = "";
+		NodeList children = node.getChildNodes();
+		if (children != null)
+		{
+			for (int i = 0; i < children.getLength(); i++)
+			{
+				Node child = children.item(i);
+				if (child != null)
+				{ 
+					if (child.getNodeName() != null 
+					&&
(child.getNodeName().equals("#text") 
+					||
child.getNodeName().equals("#cdata-section")))
+					{
+						text +=
child.getNodeValue();
+					}
+				}
+			}
+		}
+		return text;
+	}
+	
     /**
      * Invoked by getContainedElementDeclarations to get the child element
type
      * and child element name for a child element node.
@@ -334,7 +404,17 @@
         // Get the name qnames.
         QName nodeName = Utils.getNodeNameQName(elementNode);
         BooleanHolder forElement = new BooleanHolder();
-
+		
+		String comments = null;
+		try
+		{
+			comments = getTextByPath(elementNode,
"annotation/documentation");
+		}
+		catch (DOMException e)
+		{
+			// no comments
+		}
+		
         // The type qname is used to locate the TypeEntry, which is then
         // used to retrieve the proper java name of the type.
         QName nodeType = Utils.getTypeQName(elementNode, forElement,
false);
@@ -366,6 +446,7 @@
 
         if (type != null) {
             ElementDecl elem = new ElementDecl(type, nodeName);
+			elem.setDocumentation(comments);
             String minOccurs = Utils.getAttribute(elementNode,
"minOccurs");
             if (minOccurs != null && minOccurs.equals("0")) {
                 elem.setMinOccursIs0(true);
Index: java/src/org/apache/axis/wsdl/toJava/JavaBeanWriter.java
===================================================================
RCS file:
/home/cvspublic/xml-axis/java/src/org/apache/axis/wsdl/toJava/JavaBeanWriter
.java,v
retrieving revision 1.43
diff -u -r1.43 JavaBeanWriter.java
--- java/src/org/apache/axis/wsdl/toJava/JavaBeanWriter.java	31 Jul 2003
06:25:18 -0000	1.43
+++ java/src/org/apache/axis/wsdl/toJava/JavaBeanWriter.java	26 Aug 2003
18:52:22 -0000
@@ -60,11 +60,13 @@
 import org.apache.axis.wsdl.symbolTable.ElementDecl;
 import org.apache.axis.wsdl.symbolTable.SchemaUtils;
 import org.apache.axis.wsdl.symbolTable.TypeEntry;
+import org.w3c.dom.DOMException;
 import org.w3c.dom.Node;
 
 import javax.xml.namespace.QName;
 import java.io.IOException;
 import java.io.PrintWriter;
+import java.util.StringTokenizer;
 import java.util.Vector;
 import java.util.ArrayList;
 import java.util.Iterator;
@@ -139,6 +141,35 @@
     } // ctor
 
     /**
+	 * Write a common header, including the package name, the class
+	 * declaration, and the opening curly brace.  
+	 * Prints javadoc from WSDL documentation.  (Cannot pull up, type
DOM not avail)
+	 */
+	protected void writeFileHeader(PrintWriter pw) throws IOException {
+		writeHeaderComments(pw);
+		writePackage(pw);
+		
+		try
+		{
+			String comments =
SchemaUtils.getTextByPath(type.getNode(), "annotation/documentation");
+			comments = getJavadocDescriptionPart(comments,
false);
+			if (comments != null && comments.trim().length() >
0)
+			{
+				pw.println();
+				pw.println("/**");
+				pw.println(" * " + comments);
+				pw.println(" */");
+			}
+		}
+		catch (DOMException e)
+		{
+			// no comment
+		}		
+		// print class declaration
+		pw.println(getClassModifiers() + getClassText() +
getClassName() + ' ' + getExtendsText() + getImplementsText() + "{");
+	} // writeFileHeader
+
+    /**
      * Generate the binding for the given complex type.
      */
     protected void writeFileBody(PrintWriter pw) throws IOException {
@@ -311,10 +342,27 @@
             return;
 	}
         for (int i = 0; i < names.size(); i += 2) {
+			
+			// get comments for this field
+			String comments = "";
+			if (elements != null)
+			{
+				if (elements != null && i <
(elements.size()*2))
+				{
+					ElementDecl elem =
(ElementDecl)elements.get((int)i/2);
+					comments = elem.getDocumentation();
+				}
+			} 
+            
             String typeName = (String) names.get(i);
             String variable = (String) names.get(i + 1);
 
             // Declare the bean element
+            if (comments != null && comments.trim().length() > 0)
+            {
+				String flatComments =
getJavadocDescriptionPart(comments, true);
+				pw.println("	/** " + flatComments.trim()
+ " */");
+            }
             pw.print("    private " + typeName + " " + variable + ";");
 
             // label the attribute fields.
@@ -558,7 +606,34 @@
             }
         }
     }
-
+    
+	/**
+	 * Takes out new lines and wraps at Javadoc tags
+	 * @param documentation the raw comments from schema
+	 * @param addTab if true adds a tab character when wrapping
(methods)
+	 */
+    private String getJavadocDescriptionPart(String documentation, boolean
addTab)
+	{
+		String doc = "";
+		if (documentation == null) return null;
+		if (documentation.trim().length() == 0) return "";
+		
+		StringTokenizer st2 = new
StringTokenizer(documentation.trim(), "\n");
+		
+		while (st2.hasMoreTokens())
+		{
+			String line = st2.nextToken().trim();
+			doc += line + " ";
+		}
+		StringTokenizer st = new StringTokenizer(doc.trim(), "@");
+		String newComments = st.nextToken();
+		while (st.hasMoreTokens())
+		{
+			newComments += "\n" + (addTab ? "\t" : "") + " * @"
+ st.nextToken().trim();
+		}	
+		return newComments;
+	}
+    
     /**
      * Writes the setter and getter methods
      */
@@ -569,12 +644,35 @@
             String typeName = (String) names.get(i);
             String name = (String) names.get(i + 1);
             String capName = Utils.capitalizeFirstChar(name);
+			String documentation = "";
+			if (elements != null)
+			{
+				if (elements != null && i <
(elements.size()*2))
+				{
+					ElementDecl elem =
(ElementDecl)elements.get((int)i/2);
+					documentation =
elem.getDocumentation();
+				}
+			} 
 
             String get = "get";
             if (typeName.equals("boolean"))
                 get = "is";
 
             if (enableGetters) {
+				try
+				{
+					String comments = "Gets the " + name
+ " value for this " + getClassName() + ".";
+					pw.println();
+					pw.println("	/**");
+					pw.println("	 * " + comments);
+					pw.println("	 * ");
+					pw.println("	 * @return " + name
+ " - " + getJavadocDescriptionPart(documentation, true));
+					pw.println("	 */");
+				}
+				catch (DOMException e)
+				{
+					// no comment
+				}		
                 pw.println("    public " + typeName + " " +
                            get + capName + "() {");
                 if (isUnion()) {
@@ -586,6 +684,20 @@
                 pw.println();
             }
             if (enableSetters) {
+				try
+				{
+					String comments = "Sets the " + name
+ " value for this " + getClassName() + ".";
+					pw.println();
+					pw.println("	/**");
+					pw.println("	 * " + comments);
+					pw.println("	 * ");
+					pw.println("	 * @param " + name +
" " + getJavadocDescriptionPart(documentation, true));
+					pw.println("	 */");
+				}
+				catch (DOMException e)
+				{
+					// no comment
+				}	            	
                 if (isUnion()) {
                     pw.println("    public void setValue(" +
                            typeName + " value) {");

Mime
View raw message