You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by se...@apache.org on 2015/10/07 17:44:22 UTC
cxf git commit: [CXF-5606] Optionally translating WADL docs into Java
docs
Repository: cxf
Updated Branches:
refs/heads/master 7656bb7d8 -> 013051c78
[CXF-5606] Optionally translating WADL docs into Java docs
Project: http://git-wip-us.apache.org/repos/asf/cxf/repo
Commit: http://git-wip-us.apache.org/repos/asf/cxf/commit/013051c7
Tree: http://git-wip-us.apache.org/repos/asf/cxf/tree/013051c7
Diff: http://git-wip-us.apache.org/repos/asf/cxf/diff/013051c7
Branch: refs/heads/master
Commit: 013051c78de7fdedc2a2a2663e7fe51f918e7c73
Parents: 7656bb7
Author: Sergey Beryozkin <sb...@gmail.com>
Authored: Wed Oct 7 16:44:04 2015 +0100
Committer: Sergey Beryozkin <sb...@gmail.com>
Committed: Wed Oct 7 16:44:04 2015 +0100
----------------------------------------------------------------------
.../cxf/tools/wadlto/WadlToolConstants.java | 1 +
.../cxf/tools/wadlto/jaxrs/JAXRSContainer.java | 1 +
.../cxf/tools/wadlto/jaxrs/SourceGenerator.java | 165 ++++++++++++++++---
.../cxf/tools/wadlto/jaxrs/jaxrs-toolspec.xml | 4 +
.../tools/wadlto/jaxrs/JAXRSContainerTest.java | 2 +-
.../jaxrs/src/test/resources/wadl/test.xml | 18 +-
6 files changed, 163 insertions(+), 28 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cxf/blob/013051c7/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/WadlToolConstants.java
----------------------------------------------------------------------
diff --git a/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/WadlToolConstants.java b/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/WadlToolConstants.java
index 42026f5..673f7a5 100644
--- a/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/WadlToolConstants.java
+++ b/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/WadlToolConstants.java
@@ -54,6 +54,7 @@ public final class WadlToolConstants {
public static final String CFG_WADL_NAMESPACE = "wadlNamespace";
public static final String CFG_GENERATE_ENUMS = "generateEnums";
public static final String CFG_INHERIT_PARAMS = "inheritResourceParams";
+ public static final String CFG_CREATE_JAVA_DOCS = "javaDocs";
public static final String CFG_GENERATE_RESPONSE_IF_HEADERS_SET = "generateResponseIfHeadersSet";
public static final String CFG_GENERATE_RESPONSE_FOR_METHODS = "generateResponseForMethods";
public static final String CFG_VALIDATE_WADL = "validate";
http://git-wip-us.apache.org/repos/asf/cxf/blob/013051c7/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/JAXRSContainer.java
----------------------------------------------------------------------
diff --git a/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/JAXRSContainer.java b/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/JAXRSContainer.java
index 49b690a..687e533 100644
--- a/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/JAXRSContainer.java
+++ b/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/JAXRSContainer.java
@@ -133,6 +133,7 @@ public class JAXRSContainer extends AbstractCXFToolContainer {
}
sg.setSupportMultipleXmlReps(context.optionSet(WadlToolConstants.CFG_MULTIPLE_XML_REPS));
+ sg.setCreateJavaDocs(context.optionSet(WadlToolConstants.CFG_CREATE_JAVA_DOCS));
// set the base path
sg.setWadlPath(wadlURL);
http://git-wip-us.apache.org/repos/asf/cxf/blob/013051c7/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/SourceGenerator.java
----------------------------------------------------------------------
diff --git a/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/SourceGenerator.java b/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/SourceGenerator.java
index b0bca1f..53e937a 100644
--- a/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/SourceGenerator.java
+++ b/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/SourceGenerator.java
@@ -221,6 +221,7 @@ public class SourceGenerator {
private boolean validateWadl;
private SchemaCollection schemaCollection = new SchemaCollection();
private String encoding;
+ private boolean createJavaDocs;
public SourceGenerator() {
this(Collections.<String, String>emptyMap());
@@ -491,7 +492,10 @@ public class SourceGenerator {
sbImports.append(getClassComment()).append(getLineSep());
sbImports.append("package " + classPackage)
.append(";").append(getLineSep()).append(getLineSep());
-
+ boolean doCreateJavaDocs = isJavaDocNeeded(info);
+ if (doCreateJavaDocs) {
+ writeClassDocs(rElement, sbCode);
+ }
if (isRoot && writeAnnotations(info.isInterfaceGenerated())) {
String path = rElement.getAttribute("path");
writeAnnotation(sbCode, imports, Path.class, path, true, false);
@@ -681,6 +685,17 @@ public class SourceGenerator {
ContextInfo info,
boolean isRoot,
String currentPath) {
+ StringBuilder sbMethodCode = sbCode;
+ StringBuilder sbMethodDocs = null;
+ StringBuilder sbMethodRespDocs = null;
+
+ boolean doCreateJavaDocs = isJavaDocNeeded(info);
+ if (doCreateJavaDocs) {
+ sbMethodCode = new StringBuilder();
+ sbMethodDocs = startMethodDocs(methodEl);
+ sbMethodRespDocs = new StringBuilder();
+ }
+
boolean isResourceElement = "resource".equals(methodEl.getLocalName());
Element resourceEl = isResourceElement ? methodEl : (Element)methodEl.getParentNode();
@@ -694,10 +709,7 @@ public class SourceGenerator {
String methodName = methodEl.getAttribute("name");
final String methodNameLowerCase = methodName.toLowerCase();
- String id = methodEl.getAttribute("id");
- if (id.length() == 0) {
- id = methodNameLowerCase;
- }
+ String id = getMethodId(methodEl, methodNameLowerCase);
final boolean responseRequired = isMethodMatched(responseMethods, methodNameLowerCase, id);
final boolean suspendedAsync = responseRequired ? false
: isMethodMatched(suspendedAsyncMethods, methodNameLowerCase, id);
@@ -731,39 +743,41 @@ public class SourceGenerator {
requestReps = Collections.singletonList(requestRepWithElement);
}
if (writeAnnotations(info.isInterfaceGenerated())) {
- sbCode.append(TAB);
+ sbMethodCode.append(TAB);
if (methodNameLowerCase.length() > 0) {
if (HTTP_METHOD_ANNOTATIONS.containsKey(methodNameLowerCase)) {
- writeAnnotation(sbCode, imports,
+ writeAnnotation(sbMethodCode, imports,
HTTP_METHOD_ANNOTATIONS.get(methodNameLowerCase), null, true, true);
} else {
- writeCustomHttpMethod(info, classPackage, methodName, sbCode, imports);
+ writeCustomHttpMethod(info, classPackage, methodName, sbMethodCode, imports);
}
- writeFormatAnnotations(requestReps, sbCode, imports, true, null);
+ writeFormatAnnotations(requestReps, sbMethodCode, imports, true, null);
writeFormatAnnotations(getWadlElements(getOKResponse(responseEls), "representation"),
- sbCode, imports, false, requestRepWithElement);
+ sbMethodCode, imports, false, requestRepWithElement);
}
if (!isRoot && !"/".equals(currentPath)) {
- writeAnnotation(sbCode, imports, Path.class, currentPath, true, true);
+ writeAnnotation(sbMethodCode, imports, Path.class, currentPath, true, true);
}
} else {
- sbCode.append(getLineSep()).append(TAB);
+ sbMethodCode.append(getLineSep()).append(TAB);
}
if (!info.isInterfaceGenerated()) {
- sbCode.append("public ");
+ sbMethodCode.append("public ");
}
boolean responseTypeAvailable = true;
if (methodNameLowerCase.length() > 0) {
responseTypeAvailable = writeResponseType(responseEls,
requestRepWithElement,
- sbCode,
+ sbMethodCode,
+ sbMethodRespDocs,
imports,
info,
responseRequired,
suspendedAsync);
+
String genMethodName = id + suffixName;
if (methodNameLowerCase.equals(genMethodName)) {
List<PathSegment> segments = JAXRSUtils.getPathSegments(currentPath, true, true);
@@ -778,29 +792,112 @@ public class SourceGenerator {
}
genMethodName += firstCharToUpperCase(sb.toString());
}
- sbCode.append(genMethodName.replace("-", ""));
+ sbMethodCode.append(genMethodName.replace("-", ""));
} else {
- writeSubresourceMethod(resourceEl, imports, sbCode, info, id, suffixName);
+ writeSubresourceMethod(resourceEl, imports, sbMethodCode, info, id, suffixName);
}
- sbCode.append("(");
+ sbMethodCode.append("(");
List<Element> inParamElements = getParameters(resourceEl, info.getInheritedParams(),
!isRoot && !isResourceElement && resourceEl.getAttribute("id").length() > 0);
Element repElement = getActualRepElement(allRequestReps, requestRepWithElement);
writeRequestTypes(firstRequestEl, classPackage, repElement, inParamElements,
- jaxpSourceRequired, sbCode, imports, info, suspendedAsync);
- sbCode.append(")");
+ jaxpSourceRequired, sbMethodCode, sbMethodDocs, imports, info, suspendedAsync);
+ sbMethodCode.append(")");
if (info.isInterfaceGenerated()) {
- sbCode.append(";");
+ sbMethodCode.append(";");
} else {
- generateEmptyMethodBody(sbCode, responseTypeAvailable);
+ generateEmptyMethodBody(sbMethodCode, responseTypeAvailable);
}
- sbCode.append(getLineSep()).append(getLineSep());
+ sbMethodCode.append(getLineSep()).append(getLineSep());
+ }
+ finalizeMethodDocs(doCreateJavaDocs, sbCode, sbMethodDocs, sbMethodRespDocs, sbMethodCode);
+
+ }
+
+ private String getMethodId(Element methodEl, String methodNameLowerCase) {
+ String id = methodEl.getAttribute("id");
+ if (id.length() == 0) {
+ id = methodNameLowerCase;
+ }
+ return id;
+ }
+
+ private void finalizeMethodDocs(boolean doCreateJavaDocs, StringBuilder sbCode, StringBuilder sbJavaDocs,
+ StringBuilder sbRespDocs, StringBuilder sbMethodCode) {
+ if (doCreateJavaDocs) {
+ sbJavaDocs.append(sbRespDocs);
+ if (sbJavaDocs.length() > 0) {
+ openJavaDocs(sbCode, true);
+ sbCode.append(sbJavaDocs);
+ closeJavaDocs(sbCode);
+ }
+ sbCode.append(sbMethodCode);
+ }
+ }
+
+ private boolean isJavaDocNeeded(ContextInfo info) {
+ return createJavaDocs && (generateInterfaces && !generateImpl
+ || !generateInterfaces && generateImpl
+ || generateImpl && info.isInterfaceGenerated());
+ }
+
+ private void openJavaDocs(StringBuilder sbDoc, boolean tab) {
+ if (tab) {
+ sbDoc.append(TAB);
+ }
+ sbDoc.append("/**").append(getLineSep());
+ if (tab) {
+ sbDoc.append(TAB);
+ }
+ }
+
+ private void closeJavaDocs(StringBuilder sbDoc) {
+ sbDoc.append(" */").append(getLineSep());
+ }
+ private void writeClassDocs(Element resourceEl, StringBuilder sbDoc) {
+ String text = getDocText(resourceEl);
+ if (text != null) {
+ openJavaDocs(sbDoc, false);
+ sbDoc.append(" * ").append(text).append(getLineSep());
+ closeJavaDocs(sbDoc);
+ }
+ }
+ private StringBuilder startMethodDocs(Element methodEl) {
+ StringBuilder sbDoc = new StringBuilder();
+ String text = getDocText(methodEl);
+ if (text != null) {
+ sbDoc.append(" * ").append(text).append(getLineSep()).append(TAB);
}
+ return sbDoc;
}
+ private void writeMethodParamDocs(Element paramEl, String name, StringBuilder sbDoc) {
+ String text = getDocText(paramEl);
+ if (text != null) {
+ sbDoc.append(" * @param ").append(name).append(" ").append(text)
+ .append(getLineSep()).append(TAB);
+ }
+ }
+
+ private void writeMethodResponseDocs(Element responseEl, StringBuilder sbDoc) {
+ String text = getDocText(responseEl);
+ if (text != null) {
+ sbDoc.append(" * @return ").append(text).append(getLineSep()).append(TAB);
+ }
+ }
+
+ private String getDocText(Element el) {
+ Element doc = DOMUtils.getFirstChildWithName(el, getWadlNamespace(), "doc");
+ if (doc != null) {
+ return DOMUtils.getContent(doc);
+ } else {
+ return null;
+ }
+ }
+
private void writeCustomHttpMethod(ContextInfo info,
String classPackage,
String methodName,
@@ -987,19 +1084,23 @@ public class SourceGenerator {
}
return repElements.isEmpty() ? null : repElements.get(0);
}
-
+ //CHECKSTYLE:OFF
private boolean writeResponseType(List<Element> responseEls,
Element requestRepWithElement,
StringBuilder sbCode,
+ StringBuilder sbRespDocs,
Set<String> imports,
ContextInfo info,
boolean responseRequired,
boolean suspendedAsync) {
-
+ //CHECKSTYLE:ON
Element okResponse = !suspendedAsync ? getOKResponse(responseEls) : null;
List<Element> repElements = null;
if (okResponse != null) {
+ if (sbRespDocs != null) {
+ writeMethodResponseDocs(okResponse, sbRespDocs);
+ }
repElements = getWadlElements(okResponse, "representation");
} else {
repElements = CastUtils.cast(Collections.emptyList(), Element.class);
@@ -1090,7 +1191,8 @@ public class SourceGenerator {
Element repElement,
List<Element> inParamEls,
boolean jaxpRequired,
- StringBuilder sbCode,
+ StringBuilder sbCode,
+ StringBuilder sbMethodDocs,
Set<String> imports,
ContextInfo info,
boolean suspendedAsync) {
@@ -1159,13 +1261,17 @@ public class SourceGenerator {
} else {
paramName = name.replaceAll("[:\\.\\-]", "_");
}
- sbCode.append(type).append(" ").append(firstCharToLowerCase(paramName));
+ String javaParamName = firstCharToLowerCase(paramName);
+ sbCode.append(type).append(" ").append(javaParamName);
if (i + 1 < inParamEls.size()) {
sbCode.append(", ");
if (i + 1 >= 4 && ((i + 1) % 4) == 0) {
sbCode.append(getLineSep()).append(TAB).append(TAB).append(TAB).append(TAB);
}
}
+ if (sbMethodDocs != null) {
+ writeMethodParamDocs(paramEl, javaParamName, sbMethodDocs);
+ }
}
String elementParamType = null;
String elementParamName = null;
@@ -1205,6 +1311,9 @@ public class SourceGenerator {
}
sbCode.append(elementParamType).append(" ").append(elementParamName);
}
+ if (sbMethodDocs != null && repElement != null) {
+ writeMethodParamDocs(repElement, elementParamName, sbMethodDocs);
+ }
if (suspendedAsync) {
if (inParamEls.size() > 0 || elementParamType != null) {
sbCode.append(", ");
@@ -1860,6 +1969,10 @@ public class SourceGenerator {
this.encoding = encoding;
}
+ public void setCreateJavaDocs(boolean createJavaDocs) {
+ this.createJavaDocs = createJavaDocs;
+ }
+
private static class GrammarInfo {
private Map<String, String> nsMap = new HashMap<String, String>();
private Map<String, String> elementTypeMap = new HashMap<String, String>();
http://git-wip-us.apache.org/repos/asf/cxf/blob/013051c7/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/jaxrs-toolspec.xml
----------------------------------------------------------------------
diff --git a/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/jaxrs-toolspec.xml b/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/jaxrs-toolspec.xml
index 5e8ccbd..5a27e42 100644
--- a/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/jaxrs-toolspec.xml
+++ b/tools/wadlto/jaxrs/src/main/java/org/apache/cxf/tools/wadlto/jaxrs/jaxrs-toolspec.xml
@@ -247,6 +247,10 @@ Examples:
</annotation>
<switch>validate</switch>
</option>
+ <option id="javaDocs" maxOccurs="1">
+ <annotation>Convert WADL doc elements to JavaDocs</annotation>
+ <switch>javaDocs</switch>
+ </option>
</optionGroup>
<optionGroup id="common_options">
<option id="help" maxOccurs="1">
http://git-wip-us.apache.org/repos/asf/cxf/blob/013051c7/tools/wadlto/jaxrs/src/test/java/org/apache/cxf/tools/wadlto/jaxrs/JAXRSContainerTest.java
----------------------------------------------------------------------
diff --git a/tools/wadlto/jaxrs/src/test/java/org/apache/cxf/tools/wadlto/jaxrs/JAXRSContainerTest.java b/tools/wadlto/jaxrs/src/test/java/org/apache/cxf/tools/wadlto/jaxrs/JAXRSContainerTest.java
index e3d9104..7c3e826 100644
--- a/tools/wadlto/jaxrs/src/test/java/org/apache/cxf/tools/wadlto/jaxrs/JAXRSContainerTest.java
+++ b/tools/wadlto/jaxrs/src/test/java/org/apache/cxf/tools/wadlto/jaxrs/JAXRSContainerTest.java
@@ -102,7 +102,7 @@ public class JAXRSContainerTest extends ProcessorTestBase {
"{http://www.w3.org/2001/XMLSchema}anyType="
+ "java.io.InputStream");
context.put(WadlToolConstants.CFG_INHERIT_PARAMS, "last");
-
+ context.put(WadlToolConstants.CFG_CREATE_JAVA_DOCS, "true");
container.setContext(context);
container.execute();
http://git-wip-us.apache.org/repos/asf/cxf/blob/013051c7/tools/wadlto/jaxrs/src/test/resources/wadl/test.xml
----------------------------------------------------------------------
diff --git a/tools/wadlto/jaxrs/src/test/resources/wadl/test.xml b/tools/wadlto/jaxrs/src/test/resources/wadl/test.xml
index 5604970..ec6a9c6 100644
--- a/tools/wadlto/jaxrs/src/test/resources/wadl/test.xml
+++ b/tools/wadlto/jaxrs/src/test/resources/wadl/test.xml
@@ -2,9 +2,22 @@
<grammars />
<resources>
<resource id="Test" path="/repository">
- <param name="top" style="template" type="xs:string"/>
+ <doc>
+ Repository Resource
+ </doc>
+ <param name="top" style="template" type="xs:string">
+ <doc>
+ Repository Index
+ </doc>
+ </param>
<method name="GET" id="listRepositories">
+ <doc>
+ List Repositories
+ </doc>
<response>
+ <doc>
+ JSON Repository Representation
+ </doc>
<representation mediaType="application/json" />
</response>
</method>
@@ -24,6 +37,9 @@
<method name="POST">
<request>
<representation mediaType="text/plain">
+ <doc>
+ Text Plain representation
+ </doc>
<param name="id" style="plain" type="xsd:anyType"/>
</representation>
</request>