Generating Java Rest Client based on CXF

[peteryhwong]

As there is now a provision to generate Java CXF-specific Rest server stub (#1854), we would like to see codegen to support generation of Java CXF-specific Rest client. This is because we use CXF as our JAX-RS implementation and would like to leverage this implementation for our client libraries (specifically for inter-service interaction). The current client generator uses Jersey which causes conflict when being used in conjunction with CXF.

[wing328]

@peteryhwong the Java API client supports many HTTP libraries (e.g. Retrofit, Jersey2.x, etc). Please run java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l java for a list of HTTP libraries support.

Ref: https://github.com/swagger-api/swagger-codegen#customizing-the-generator

[peteryhwong]

@wing328 thanks for this. If I understand correctly, the JavaClientCodeGen supports the following:

        <default> - HTTP client: Jersey client 1.18. JSON processing: Jackson 2.4.2
        jersey2 - HTTP client: Jersey client 2.6
        feign - HTTP client: Netflix Feign 8.1.1.  JSON processing: Jackson 2.6.3
        okhttp-gson - HTTP client: OkHttp 2.4.0. JSON processing: Gson 2.3.1
        retrofit - HTTP client: OkHttp 2.4.0. JSON processing: Gson 2.3.1 (Retrofit 1.9.0)
        retrofit2 - HTTP client: OkHttp 2.5.0. JSON processing: Gson 2.4 (Retrofit 2.0.0-beta2)

which do not include CXF client (http://cxf.apache.org/docs/jax-rs-client-api.html), unless you are suggesting an alternative to CXF?

[wing328]

Yes, that's the list of HTTP libraries supported. CXF client is not supported yet and we would welcome contribution from the community to support that.

You mentioned Jersey (1.x) has conflicts when being used in conjunction with CXF and that's why I suggested other HTTP libraries, which might work with CXF. Do you also encounter conflicts when using other HTTP libraries with CXF?

[wing328]

And here is the contributing guideline: https://github.com/swagger-api/swagger-codegen/blob/master/CONTRIBUTING.md

[wing328]

@peteryhwong do you need help from us to add CXF client support to the Java client?

[peteryhwong]

@wing328 thanks for asking.

Actually I was thinking if it would not be better if the generation for jersey2, default and cxf would be abstracted to the level of JAX-RS. So that the only difference between them would be the binding at build time. This is so that they would share the same code base.

The problem is that CXF does not provide a thread safe implementation of JAX-RS client. See https://issues.apache.org/jira/browse/CXF-6774

Let me know what you think.

[wing328]

@peteryhwong Is it correct to say that you can use the Java API client with Jersey2 library to talk to your Java CXF-specific Rest server without issue and you're trying to make the API client (jersey2) conforms to Java CXF following some sort of best practice?

cc @fehguy to see if he's any feedback on this particular topic.

[fehguy]

@peteryhwong there are many ways to solve this--in most cases, people are very happy to choose a compatible client runtime and have a stand-alone client SDK. They don't care about the abstraction necessarily, and the selection of the base library is all that matters. I don't personally think that complicating the generator with levels of abstraction helps the end users much at all.

[peteryhwong]

@fehguy @wing328 Thanks for this.

I agree end users might not care as long as if they do not mind the quality or the correctness of the generated code or ever needing to debug through them...

I am thinking in terms of maintaining different implementation of JAX-RS client templates when we could use the same JAX-RS client template for all these implementations. My thinking is around helping to increase the quality of the template, the generated code and also to reduce the complexity of maintaining them.

The same reason applies to JAX-RS server code generation...

[jfiala]

@wing328 I currently deal with CXF2/3 and would like to improve the CXF server part (to assemble a full usable server) and CXF client part, best both with bean-validation support and same model (#2549). You can assign me #2017 + #2549 if you like, I plan to do this in the next week(s)...

[wing328]

@jfiala thanks for offering contributions for the improvement. Please let us know if you need any help (e.g. testing)

[cbornet]

@jfiala IMO, CXF should be done as a library of the jax-rs generator.
Today it differs from JavaJerseyServerCodegen in that it uses JAXB instead of Jackson (I think it can and should use Jackson), it groups the operations by tag and not by path (I don't know cxf but this looks suspicious : what happens if two methods have the same path ? How will CXF resolve the path mapping ?) and it doesn't use the swagger annotations (there should be no harm in adding them even if it cannot produce the online swagger spec).

Other notes :

• Resteasy should also be done as a lib as the difference with jersey is even smaller.
• The common templates between jersey1 and jersey2 should be put in the root/common dir.

[jfiala]

@cbornet: I'd start from the existing Server CXF generator:
https://github.com/swagger-api/swagger-codegen#java-jax-rs-apache-cxf-2--3

I'm using CXF + Jackson right now (as jettison didn't work properly). I'll add this with the lastest CXF/Jackson versions...

Since CXF3 it offers the Swagger2Feature (http://cxf.apache.org/docs/swagger2feature.html) which allows you to generate the Swagger-spec in addition to WADL, looks really nice and also supports Bean-Validation-Annotations + Swagger-Annotations, only more advanced features like nested query parameters or Multiparts are not generated correctly. So one could start off with the Swagger spec and later do code first using the Swagger2Feature after the CXF-generator for server+client is done...

[jfiala]

@cbornet: added the cxf client with PR #3281

• Jackson is used as provider (is already included as dependency of swagger-jaxrs)
• only cxf-rt-rs-client necessary to allow full client support
• added bean-validation-api support (currently not supported by CXF wadl2java...)
• added test templates to generate test classes (currently not supported by CXF wadl2java...)

The current implementation jaxrs-cxf / JavaCXFServerCodegen is in fact the client (interfaces + model).
It would only become the server after adding the implementation stubs.
I suggest renaming it to JavaCXFCodegen and adding a switch to also generate the implementation classes?

[jfiala]

added the complete server WAR (including CXF3 Swagger2Feature + WADL).

[sberyozkin]

@peteryhwong, re your earlier comment about https://issues.apache.org/jira/browse/CXF-6774, the thread-safe client code was supported for a long time, it is JAX-RS 2.0 Client API which does not provide for a way to have a single thread-safe Client/WebTarget be created and reused, so this is what we did with CXF-6774, added a property to pass to the underlying CXF WebClient via a JAX-RS 2,0 config...
Note CXF WADL and Swagger code will be split into different modules shortly
cheers

[jfiala]

updated the wiki
https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO
added "(scheduled for 2.1.5)" to indicate that it's not yet released...

[rynger]

Is there particular reason the Path annotation in the JavaJaxRS CXF api template does not use the base path as other implementations do?

https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/main/resources/JavaJaxRS/cxf/api.mustache

Line 15: @path("/")

Would expect @path("/{{baseName}}") as others have surely?

[wing328]

@rynger I think you actually mean {{basePath}} instead of {{baseName}}.

Do you have time to contribute a PR so that we can review the fix?

[rynger]

I'll try to get a PR sorted for review (would be my first so will need to learn the process).

I pulled the @path("/{{baseName}}") from the resteasy api.mustache template, so I'd assumed that "baseName" was the template property that referred to the swagger basePath.

[jfiala]

@rynger I had to correct the @path annotation at the interface level to @path("/"), as the @path annotation including the full path is already part of the operations. Having the @path annotation at both positions leads to wrong results.

With the annotation at the interface level, the generated code looks like:

@Path("/contextname/myservices")
public interface {{classname}}  {
    @Path("/myservices/mymethod")
    public Response mymethod (String param1);
}

Then users have to access the REST api using /contextname/myservices/myservices/mymethod (duplicate myservices part).

(also see #4003)

[jfiala]

added cxf3 JAXRS client in PR #4003

[jfiala]

@wing328: I think this one is complete with the merge of #4003?

[wing328]

@jfiala yup, closed via #4003

@peteryhwong please pull the latest master to give it a try.