You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@cxf.apache.org by Graham Leggett <mi...@sharp.fm> on 2014/03/12 13:47:15 UTC
wadl2java and the generation of documentation
Hi all,
I have managed to get the maven cxf-wadl2java-plugin working and generating some interfaces from wadl, and this is working well.
One missing piece is documentation - our wadl file contains doc elements, but these doc elements aren't ending up in the code, either as code comments (for the purposes of javadocs) or as Description annotation:
@GET
@Produces("application/json")
Response get(@QueryParam("page") Long page, @QueryParam("pageSize") Long pageSize, @QueryParam("sort") String sort, @QueryParam("fl") String fl,
@HeaderParam("If-Modified-Since") java.util.Date If_Modified_Since);
According to http://cxf.apache.org/docs/jaxrs-services-description.html the docs tell us "Description annotations can be applied to input parameters", but then the docs forget to tell us how.
Most specifically, I want the docs tags in the wadl to end up in the generated code. Can anyone confirm how this is done?
Regards,
Graham
--
Re: wadl2java and the generation of documentation
Posted by Sergey Beryozkin <sb...@gmail.com>.
Hi Graham, thanks for your contribution.
I should've mentioned I've already fixed it earlier today. The import
optimization went into 2.7.x and trunk, the parameter name fix - to the
trunk, otherwise 2.7.x can see the compilation issues after migrating to
2.7.11...
Please keep your contributions coming.
Re the grammar question: there's nothing specific in CXF about
supporting WADL grammars, except that you can control the way the
grammar is used to do the code generation. You can inline it or
reference the external grammars per WADL spec rules.
For example:
https://git-wip-us.apache.org/repos/asf?p=cxf.git;a=tree;f=systests/jaxrs/src/test/resources/wadl;h=b481ed05def7f7ba1963e4d987e80c8fd9193a7d;hb=HEAD
Sergey
On 12/03/14 21:32, Graham Leggett wrote:
> On 12 Mar 2014, at 11:28 PM, Graham Leggett <mi...@sharp.fm> wrote:
>
>> A quick patch for that one:
>
> git left off the added test cases:
>
> diff --git a/core/src/test/java/org/apache/cxf/helpers/JavaUtilsTest.java b/core/src/test/java/org/apache/cxf/helpers/JavaUtilsTest.java
> new file mode 100644
> index 0000000..0dbd31b
> --- /dev/null
> +++ b/core/src/test/java/org/apache/cxf/helpers/JavaUtilsTest.java
> @@ -0,0 +1,37 @@
> +/**
> + * Licensed to the Apache Software Foundation (ASF) under one
> + * or more contributor license agreements. See the NOTICE file
> + * distributed with this work for additional information
> + * regarding copyright ownership. The ASF licenses this file
> + * to you under the Apache License, Version 2.0 (the
> + * "License"); you may not use this file except in compliance
> + * with the License. You may obtain a copy of the License at
> + *
> + * http://www.apache.org/licenses/LICENSE-2.0
> + *
> + * Unless required by applicable law or agreed to in writing,
> + * software distributed under the License is distributed on an
> + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
> + * KIND, either express or implied. See the License for the
> + * specific language governing permissions and limitations
> + * under the License.
> + */
> +package org.apache.cxf.helpers;
> +
> +
> +
> +import org.junit.Assert;
> +import org.junit.Test;
> +
> +public class JavaUtilsTest extends Assert {
> +
> +
> + @Test
> + public void testToJavaIdentifier() throws Exception {
> +
> + assertEquals("not equal", "expected", JavaUtils.toJavaIdentifier("expected"));
> + assertEquals("not equal", "public_arg", JavaUtils.toJavaIdentifier("public"));
> + assertEquals("not equal", "ifModifiedSince", JavaUtils.toJavaIdentifier("If-Modified-Since"));
> +
> + }
> +}
>
> Regards,
> Graham
> --
>
--
Sergey Beryozkin
Talend Community Coders
http://coders.talend.com/
Blog: http://sberyozkin.blogspot.com
Re: wadl2java and the generation of documentation
Posted by Graham Leggett <mi...@sharp.fm>.
On 12 Mar 2014, at 11:28 PM, Graham Leggett <mi...@sharp.fm> wrote:
> A quick patch for that one:
git left off the added test cases:
diff --git a/core/src/test/java/org/apache/cxf/helpers/JavaUtilsTest.java b/core/src/test/java/org/apache/cxf/helpers/JavaUtilsTest.java
new file mode 100644
index 0000000..0dbd31b
--- /dev/null
+++ b/core/src/test/java/org/apache/cxf/helpers/JavaUtilsTest.java
@@ -0,0 +1,37 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.cxf.helpers;
+
+
+
+import org.junit.Assert;
+import org.junit.Test;
+
+public class JavaUtilsTest extends Assert {
+
+
+ @Test
+ public void testToJavaIdentifier() throws Exception {
+
+ assertEquals("not equal", "expected", JavaUtils.toJavaIdentifier("expected"));
+ assertEquals("not equal", "public_arg", JavaUtils.toJavaIdentifier("public"));
+ assertEquals("not equal", "ifModifiedSince", JavaUtils.toJavaIdentifier("If-Modified-Since"));
+
+ }
+}
Regards,
Graham
--
Re: wadl2java and the generation of documentation
Posted by Graham Leggett <mi...@sharp.fm>.
On 12 Mar 2014, at 3:55 PM, Sergey Beryozkin <sb...@gmail.com> wrote:
>> I've opened an enhancement request:
>> https://issues.apache.org/jira/browse/CXF-5606
>>
>> I can also seed a minor issue on the generated signature above,
>> 'java.util.Date' should be just 'Date' with 'java.util.Date' going into
>> the imports....This is done for complex references but not for 'complex'
>> parameter types...needs to be fixed
>>
> And the parameter name for it needs to start from the lower case, 3 issues found :-)
A quick patch for that one:
diff --git a/core/pom.xml b/core/pom.xml
index 199024f..e55d641 100644
--- a/core/pom.xml
+++ b/core/pom.xml
@@ -201,6 +201,11 @@
<optional>true</optional>
<scope>provided</scope>
</dependency>
+ <dependency>
+ <groupId>commons-lang</groupId>
+ <artifactId>commons-lang</artifactId>
+ <version>2.6</version>
+ </dependency>
</dependencies>
<build>
<plugins>
diff --git a/core/src/main/java/org/apache/cxf/helpers/JavaUtils.java b/core/src/main/java/org/apache/cxf/helpers/JavaUtils.java
index e29e388..1374366 100644
--- a/core/src/main/java/org/apache/cxf/helpers/JavaUtils.java
+++ b/core/src/main/java/org/apache/cxf/helpers/JavaUtils.java
@@ -19,10 +19,13 @@
package org.apache.cxf.helpers;
+import java.beans.Introspector;
import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;
+import org.apache.commons.lang.WordUtils;
+
public final class JavaUtils {
/** Use this character as suffix */
@@ -66,4 +69,22 @@ public final class JavaUtils {
return KEYWORD_PREFIX + keyword;
}
+ /**
+ * Convert the given string into a Java identifier, first by converting to camel
+ * case, and then lowercasing the initial letter as per Introspector.decapitalize()
+ *
+ * @return String identifier
+ */
+ public static String toJavaIdentifier(String name) {
+ char[] delimiters = {'_'};
+ String paramName;
+ if (JavaUtils.isJavaKeyword(name)) {
+ paramName = name.concat("_arg");
+ } else {
+ paramName = Introspector.decapitalize(WordUtils.capitalizeFully(
+ name.replaceAll("[:\\.\\-]", "_"), delimiters).replaceAll("_", ""));
+ }
+ return paramName;
+ }
+
}
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 26874b4..39c00b3 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
@@ -960,13 +960,7 @@ public class SourceGenerator {
addImport(imports, List.class.getName());
type = "List<" + type + ">";
}
- String paramName;
- if (JavaUtils.isJavaKeyword(name)) {
- paramName = name.concat("_arg");
- } else {
- paramName = name.replaceAll("[:\\.\\-]", "_");
- }
- sbCode.append(type).append(" ").append(paramName);
+ sbCode.append(type).append(" ").append(JavaUtils.toJavaIdentifier(name));
if (i + 1 < inParamEls.size()) {
sbCode.append(", ");
if (i + 1 >= 4 && ((i + 1) % 4) == 0) {
Regards,
Graham
--
Re: wadl2java and the generation of documentation
Posted by Sergey Beryozkin <sb...@gmail.com>.
On 12/03/14 13:42, Sergey Beryozkin wrote:
> Hi
> On 12/03/14 12:47, Graham Leggett wrote:
>> Hi all,
>>
>> I have managed to get the maven cxf-wadl2java-plugin working and
>> generating some interfaces from wadl, and this is working well.
>>
>> One missing piece is documentation - our wadl file contains doc
>> elements, but these doc elements aren't ending up in the code, either
>> as code comments (for the purposes of javadocs) or as Description
>> annotation:
>>
>> @GET
>> @Produces("application/json")
>> Response get(@QueryParam("page") Long page,
>> @QueryParam("pageSize") Long pageSize, @QueryParam("sort") String
>> sort, @QueryParam("fl") String fl,
>> @HeaderParam("If-Modified-Since") java.util.Date
>> If_Modified_Since);
>>
>> According to
>> http://cxf.apache.org/docs/jaxrs-services-description.html the docs
>> tell us "Description annotations can be applied to input parameters",
>> but then the docs forget to tell us how.
>>
>> Most specifically, I want the docs tags in the wadl to end up in the
>> generated code. Can anyone confirm how this is done?
>>
> I've opened an enhancement request:
> https://issues.apache.org/jira/browse/CXF-5606
>
> I can also seed a minor issue on the generated signature above,
> 'java.util.Date' should be just 'Date' with 'java.util.Date' going into
> the imports....This is done for complex references but not for 'complex'
> parameter types...needs to be fixed
>
And the parameter name for it needs to start from the lower case, 3
issues found :-)
> Thanks, Sergey
>
>> Regards,
>> Graham
>> --
>>
>
>
Re: wadl2java and the generation of documentation
Posted by Sergey Beryozkin <sb...@gmail.com>.
Hi
On 12/03/14 12:47, Graham Leggett wrote:
> Hi all,
>
> I have managed to get the maven cxf-wadl2java-plugin working and generating some interfaces from wadl, and this is working well.
>
> One missing piece is documentation - our wadl file contains doc elements, but these doc elements aren't ending up in the code, either as code comments (for the purposes of javadocs) or as Description annotation:
>
> @GET
> @Produces("application/json")
> Response get(@QueryParam("page") Long page, @QueryParam("pageSize") Long pageSize, @QueryParam("sort") String sort, @QueryParam("fl") String fl,
> @HeaderParam("If-Modified-Since") java.util.Date If_Modified_Since);
>
> According to http://cxf.apache.org/docs/jaxrs-services-description.html the docs tell us "Description annotations can be applied to input parameters", but then the docs forget to tell us how.
>
> Most specifically, I want the docs tags in the wadl to end up in the generated code. Can anyone confirm how this is done?
>
I've opened an enhancement request:
https://issues.apache.org/jira/browse/CXF-5606
I can also seed a minor issue on the generated signature above,
'java.util.Date' should be just 'Date' with 'java.util.Date' going into
the imports....This is done for complex references but not for 'complex'
parameter types...needs to be fixed
Thanks, Sergey
> Regards,
> Graham
> --
>