Extracting RADL from Java code

Extracting RADL from Java code

RADL Java tooling currently supports working with JAX-RS and Spring.

What Information Is Extracted

The following information is extracted from code and added to the RADL file:

• Resources and their URIs
  These are found through Java annotations. JAX-RS uses @Path, while Spring uses @RequestMapping. These annotations may be present on a class or method.
  The name of the extracted resource is derived from the class or method name. Common suffixes like Controller, RestResource, and Resource are stripped. The package name is included if needed to make the resource name unique. Parts of the package name that are very non-descriptive, like com can be configured to be ignored (see below). If you don't like the end result, you can also completely override the name.
• Documentation on resources
  This is extracted from the JavaDoc comments on the class or method.
• HTTP methods
  These are found through annotations again. For JAX-RS, these are @GET, @POST, @PUT, and @DELETE, while Spring uses @RequestMapping.
• Documentation on HTTP methods
  This is extracted from JavaDoc comments on the annotated Java method. Any @param and @return documentation is excluded.
• Media types
  These are extracted from Java annotations on methods. JAX-RS uses @Consumes and @Produces, while Spring uses @RequestMapping. For well-known media types, like image/jpeg or text/html, a link to the specification describing the media type is automatically added.

Configuration

The extraction code is sensitive to the following configuration properties:

• annotation.processor.options
  Example: jaxrs.patch:com.company.product.PATCH Comma-separated list of key-value pairs, where each key-value pair is separated by a colon. The only options currently recognized is jaxrs.patch: fully qualified name of the Java class that implements the PATCH HTTP method for JAX-RS.
• delete.compiler.options.file
  Whether to delete the file containing compiler options after compilation. Default is true. Set this to false to debug issues with the compilation step.
• resources.log
  Example: com.company.product.feature.FeatureRestResource Comma-separated list of resources to log. All operations on these resources are logged for debugging purposes.
• resources.ignore.package.parts
  Example: com,company,product,rest,dev,impl
  Comma-spearated list of package name parts to ignore. Ignored parts will not make it into the final name. For the example, the resource com.company.product.feature.rest.impl.FeatureRestResource would lead to a resource named feature.Feature
• resources.ignore.parts
  Example: feature
  Comma-separated list of package name parts of resources to ignore. For the example, the resource com.company.product.feature.FeatureRestResource would not make it into the resource model.
• resources.override.names
  Example: StupidName:NiceName,TechnicalName:FriendlyName
  Comma-separated list of resource overrides, where each override is a from-to pair separated by a colon.
• resources.simplify
  Example: false
  Whether to simplify resource names. Default is true.

Running the Extraction Tool

The radl.java.extraction.FromJavaRadlExtractor class implements extracting RADL from Java code. You can run this class directly, or integrate the extraction into your automated build.

Due to the number and size of the arguments, it's best to use an arguments file: provide one argument that starts with @ and ends with the name of a file that contains the arguments. For example, @extraction.properties. The arguments file should follow the Java Properties file format.

The following arguments are supported in the arguments file:

• service.name (required)
  The value of the name attribute of the service element in the generated RADL file
• base.dir (required)
  The root of the directory tree to process
• radl.file (required)
  The location of the RADL file to generate or update
• configuration.file (optional)
  Properties file containing any of the configuration properties documented above
• extra.source (optional)
  Source outside the base directory that also should be processed. This is a list of files separated by the platform path separator (; on Windows and : on *nix)
• extra.processors (optional)
  Additional annotation processors that help build the resource model
• classpath (required)
  The classpath for compiling the Java source
• java.version (optional)
  The Java version of the code to process. The default is 1.6.
• source.code.management.system (optional)
  The source code management system used to store the source code. The default is default, which doesn't do anything. The only other supported value is p4, which calls appropriate Perforce commands to edit and delete source files.