USE_CASES.md

When to use the generation plugins

Use case #1: adding a @deprecated annotation

Firstly, write the code that will add the annotation. The code generator uses JavaPoet to generate the java code.

public class AddDeprecatedAnnotationToTypePlugin implements TypeExtension {

  @Override
  public TypeSpec.Builder onType(TypeContext context, TypeSpec.Builder builder, V10GType type, BuildPhase btype) {

    builder.addAnnotation(AnnotationSpec.builder(Deprecated.class).build());
    return builder;
  }
}

Secondly, in your raml project RAML file, import the ramltojaxrs annotations:

uses:
  ramltojaxrs: ramltojaxrs.raml

Annotate the type you need to deprecate:

annotationTypes:
  types:
    allowedTargets: [TypeDeclaration,API]
    properties:
      className?:
...
types:
    Network:
        (ramltojaxrs.types):
            onTypeCreation: [org.raml.jaxrs.features.AddDeprecatedAnnotationToTypePlugin]
        type: object
        properties:
            name:
                required: true
                type: string
            dns-address:
                required: true
                type: string

Both the implementation and declaration will be marked @Deprecated

Annotations must be declared in the annotationTypes node in the root of the RAML file, and then they must annotate the corresponding nodes (types, properties, ...).

Use case #2: suppressing the generation of a type

Plugins that return null values suppress the generation. The Switch type in our RAML file will be suppressed, as org.raml.jaxrs.features.SuppressTypePlugin returns null.

Use case #3: chainable setters

The ChainableRouter type in our RAML file uses the ChainSetter extension. The idea is that, to replace the method, we use the JavaPoet builders, building the original builder, creating a new builder and then copying the important features, such as the parameters and annotations.