• eclipse IDE ( Integrated Development Environment) for Java with DSL (Domain Specific Languages) Tools, version Oxygen.2 Release (4.7.2) : the minimum required eclipse development framework.  The download site for this is: https://www.eclipse.org/downloads/packages/release/oxygen/2/eclipse-ide-java-and-dsl-developers
• Maven plug-in : a build automation tool used, in this case, for a Java project.  The maven plug-in is available through the site: http://download.eclipse.org/technology/m2e/releases.  How to install the plug-in (from within eclipse) is explained there.  The maven plug-in makes use of libraries downloaded from the maven repository at https://mvnrepository.com/.
• Apache CXF™ libraries : an open source services framework that is used in building and developing services using frontend programming APIs, like JAX-WS and JAX-RS.
• (Glassfish) Jersey libraries : providing the JAX-RS implementation
• Jackson libraries : a high-performance JSON processor for Java
• OpenAPI/Swagger 3.0 libraries : OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI / Swagger file allows you to describe your entire API, including available endpoints (/users) and operations on each endpoint (GET /users, POST /users), operation parameters Input and output for each operation, authentication methods and other ancillary information. API specifications can be written in JSON or YAML. The format is easy to learn and readable to both humans and machines, and there is also JSON and YAML editing support in eclipse.
• Log4j libraries : the Apache CXF™ logger is set to Log4j using "-Dorg.apache.cxf.Logger=org.apache.cxf.common.logging.Log4jLogger" as a VM argument in the provided run/debug configurations mdm91RestClient_LoginApiTest, mdm91RestClient_RecordsApiTest, mdm91RestClient_FastcacheApiTest

Within the provided eclipse project, the dependencies between the project and other libraries are expressed in the project's Project Object Model (POM) file, pom.xml:

The POM is what Maven uses to manage the dependencies between this project and the libraries needed to build and execute the classes defined in the project: using the provided Maven builder configuration entry mdm91RestClient_CreateFromJSON, with its goal matching pattern:

io.swagger.codegen.v3:swagger-codegen-maven-plugin:3.0.5:generate

the Java code needed to generate the (required) RESTful requests and process the resultant responses is automatically generated for the project by the Swagger code generator swagger-codegen-maven-plugin - for this to work properly, however, it is first necessary to make sure the required libraries identified in the Maven dependency entries in the POM file have been downloaded to a locally accessible directory. 

In eclipse, Maven is instructed to download the libraries specified in the POM file to a locally accessibl directory by right-clicking on the project folder and then selecting Maven - Update Project (Alt+F5) and clicking on the OK button (it is recommended clicking on the checkbox (tickbox) Force Update of Snapshots/Releases before clicking on the OK button to ensure a clean build).  The libraries named in the POM are then downloaded from https://mvnrepository.com to a directory local to the user performing the operation (providing, of course, there is Internet access to allow this to happen). Once downloaded, the libraries appear in the (Java) build path under Maven Dependencies: for most of the libraries, their source code can also be downloaded during code debugging, useful when trying to gain a detailed understanding of what is going on in the code being debugged.

Returning to Maven, with all the needed libraries downloaded, running the mdm91RestClient_CreateFromJSON builder from the eclipse Run option generates a set of classes under src/test/java:

• a set of POJOs implementing the objects defined under definitions in the SwaggerJson.json file are created in the com.example.client.provider package
• a set of classes implementing the RESTful apis (operations) defined under paths in the SwaggerJson.json file (or other JSON/YAML file) are created in the com.example.client.api package
• the common set of RESTful Web Services Api invocation classes required by the RESTful Api classes are created in the com.example.client.invoker  and  com.example.client.invoker.auth  packages.

• a set of JUnit test classes created in the com.example.client.provider package in the project's  src/main/java directory

To understand what happens when running the Maven builder configuration entry mdm91RestClient_CreateFromJSON, the POM descriptor pattern in the configuration entry:

io.swagger.codegen.v3:swagger-codegen-maven-plugin:3.0.5:generate 

matches the following build plugin in the POM file pom.xml:

(Note: the 3.0.5 in the match pattern matches the version ${io.swagger.codegen.v3.version} specified in the given POM : it can be omitted or changed - for example when  ${io.swagger.codegen.v3.version} is changed.).

This build descriptor instructs the swagger-codegen-maven-plugin to access the SwaggerJson.json descriptor file  ${project.basedir}/src/main/resources/SwaggerJson.json. as the input specification (schema) and generate the required POJOs and APIs from that schema.  As a reminder, the SwaggerJson.json file is a JSON description of the MDM 9.1.0 RESTful web services provided by the MDM 9.1.0 server (note: a YAML file could also have been used, but MDM comes with a JSON descriptor, so that is what is used).  The SwaggerJson.json file also contains the hostname, port and basePath to be used by the generated ApiClient class to reference the RESTful server providing the Web Services being accessed by the project code (as client):

It is likely that the host details will need to be changed, so please do so before generating any code, although that having been said, should a change to the hostname and/or port and/or baseUrl be required after the code has been generated, it is not necessary to regenerate the code, rather it is just necessary to change the following line in the generated ApiClient class:

Although the Swagger builder generates most of the needed classes, one set of classes is not generated by the builder: these are the JAX-RS Provider classes used to write Java objects out to the HTTP output stream (as a part of the RESTful Web Services request being sent by the client).  For the project provided, two such classes are needed: one to handle simple messages (simple objects such as Integer, String, and so on) and one to handle multi-part messages.  The simple request messages are handled "out-of-the-box" by the Jackson provider org.codehaus.jackson.jaxrs.JacksonJsonProvider.  For the multi-part messages, however, no such "out-of-the-box" class exists.  The reader will be happy to hear, then, that this project provides the needed class: com.example.client.provider. MultiPartMessageBodyWriter is a JAX-RS Provider injection class for writing multipart/form-data data out to an HTTP output stream.  Of course, as it is manually generated, any changes to its functionality do need to be provided manually as well.  Also, as an aside, JAX-RS Providers are plugins used to provide extra functionality to the main invoker class for RESTful Web Services (in the case of the auto-generated code, this is com.example.client.invoker.ApiClient<MultiPart>):  JAX-RS Providers come in three distinct "flavors":

• Entity Providers control the mapping of data representations (like XML, JSON, CSV) to their Java object equivalents: com.example.client.provider.MultiPartMessageBodyWriter is one of these
• Context Providers control the context that resources can access via @Context annotations.
• Exception Providers control the mapping of Java exceptions to a JAX-RS Response instance

With the automatically generated code and provided JAX-RS Producer classes in place, time can now be given to writing the code needed to implement the Business Logic requiring RESTful Web Service access to MDM: this project is intended to act both as the basis for Java projects needing access MDM (and other) RESTful Web Services and as a test project and demonstrator by which to test out and demomstrate MDM RESTful web service access to a wider audience - it is, in other words, intended as both a development and teaching aid.

Now, although automatically generating the code need to handle RESTful web service request and responses is useful, it is even more useful when examples are also  provided as to how to actually generate the Web Service requests in Java.  To this end,the attached mdm91RestClient eclipse project, also provides a set of RESTful API tests under src/test/java in the com.example.client.api package:.  The test classes have been developed 1.0 according to the main MDM RESTful Apis categories of MDM 9.1.0. These are:

• LoginApiTestMain.java for the LoginApi category
• FastcacheApiTestMain.java for the FastcacheApi category
• RecordsApiTestMain.java for the RecordsApi category

Using these classes, together with a packet sniffer such as Wireshark to examine HTTP traffic between the MDM 9.1.0 Rest Client and the MDM 9.1.0 server, an understanding of the specific RESTful web services provided by MDM (in terms of understanding of Web Service request and response Objects) can quickly be developed - as well as any suspected issues investigated should the need arise.

Now, as has been highlighted, in addition to the Maven pom.xml file (used to manage this project's dependencies on libraries it needs), the attached project also contains the MDM SwaggerJson.json description file:

Finally, in this knowledge article, details of the manual edits required following the generation of classes using the eclipse IDE, Maven plug-in and Apache CXF™, (Glassfish) Jersey, Jackson, OpenAPI/Swagger 3.0 and Log4j libraries are provided:

1. A new JAX-RS provider injection class, com.example.client.provider.MultiPartMessageBodyWriter (extends org.glassfish.jersey.message.internal. AbstractMessageReaderWriterProvider<MultiPart>) was provided to "consume" multipart/form-data data and write it out to the output stream as part of the JAX_RS request:

2. Three classes, com.example.client.api.LoginApiTestMain, com.example.client.api.RecordsApiTestMain, com.example.client.api.FastcacheApiTestMain were provided to test out generating requests and handling responses for the MDM Login, Records and Fastcache RESTful Web Services respectively (with Records and Fastcache testing necessarily using the LoginApi to login to MDM and log out again at the end of the test run). The test classes all access the properties file config.properties in src/test/resources to read properties required for testing: these property values will all likely need to be localized to the testing environment, but this need only be done the once for each environment.

 

3.Minor changes were required to the auto-generated classes com.example.client.invoker.ApiClient, com.example.client.api.LoginApi, com.example.client.api.RecordsApi and com.example.client.api.FastcacheApi:

a) to register the JacksonJsonProvider and MultiPartMessageBodyWriter with the Api Client com.example.client.invoker.ApiClient

b) to set the localVarPostBody object to be "" instead of null for the the Login Api com.example.client.api.LoginApi that invokes the Client Api for the MDM Login RESTful Web Services:

c) to define each file attachment individually as a form parameter for the the Record Api com.example.client.api.RecordApi that invokes the Client Api and replace "multipart/form-data" with "multipart/form-data; charset=utf-8; boundary=--sectionBoundary" for correct multi-part processing for the MDM Record RESTful Web Services:

4. Prior to the automatic generation of the RESTful Apis (operations), operation objects and base swagger codegen files, it was first necessary to set the correct hostname and port in the SwaggerJson.json file, so that the generated ApiClient class references the correct host: