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) {");
|