cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From serg...@apache.org
Subject cxf git commit: [CXF-5606] Optionally translating WADL docs into Java docs
Date Wed, 07 Oct 2015 15:44:22 GMT
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 <sberyozkin@gmail.com>
Authored: Wed Oct 7 16:44:04 2015 +0100
Committer: Sergey Beryozkin <sberyozkin@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>


Mime
View raw message