Tutorial 03 Built in Annotations

Goals

In this tutorial, you are going to learn:

• How to use the built-in annotations and plugins to perform declarative transformation.
• How to communicate with the plugins via the context.

Steps

• Copy this file to your Java project and feel free to replace the package with yours.
• Import the built-in plugins.

const { PluginContractIgnore, PluginContractChangeMethod } = require('./jaspiler/jaspiler');

• Annotate certain types, properties, methods.

/// <reference types="../jaspiler/index.d.ts"/>

const { PluginContractIgnore, PluginContractChangeMethod } = require('./jaspiler/jaspiler');

const result = jaspiler.transformSync(
  `package com.test;

  public class A {
    @JaspilerContract.Ignore
    private int a; // This property is ignored.

    @JaspilerContract.Ignore(condition = "x == 1")
    private int b; // This property is ignored.

    @JaspilerContract.Ignore(condition = "x == 2")
    private int c; // This property is not ignored.

    @JaspilerContract.Ignore
    public void d() {
      // This method is ignored.
    }

    @JaspilerContract.Change(instruction = "options = { type: 'clear' }")
    public void e(String str) {
      System.out.println(str); // This method is cleared.
    }

    @JaspilerContract.Change(condition = "x == 1", instruction = "options = { type: 'clear' }")
    public int f(int x, int y) {
      return x + y; // This method is cleared.
    }

    @JaspilerContract.Change(condition = "x == 2", instruction = "options = { type: 'clear' }")
    public int g(int x, int y) {
      return x + y; // This method is not cleared.
    }
  }

  @JaspilerContract.Ignore
  interface B {} // This interface is ignored.
  `,
  {
    context: { x: 1, options: {} },
    plugins: [PluginContractIgnore, PluginContractChangeMethod],
    sourceType: 'string',
  });
console.info(result.code);

• The output is:

package com.test;

public class A {
    @JaspilerContract.Ignore(condition = "x == 2")
    private int c;

    @JaspilerContract.Change(instruction = "options = { type: 'clear' }")
    public void e(String str) {
    }

    @JaspilerContract.Change(condition = "x == 1", instruction = "options = { type: 'clear' }")
    public int f(int x, int y) {
        return 0;
    }

    @JaspilerContract.Change(condition = "x == 2", instruction = "options = { type: 'clear' }")
    public int g(int x, int y) {
      return x + y; // This method is not cleared.
    }
}

The complete code is at 03_builtin_annotations.js

Summary

• PluginContractIgnore processes @JaspilerContract.Ignore and removes the annotated types, properties, or methods by default. If condition is provided, it evaluates the condition based on the context.
• PluginContractChangeMethod processes @JaspilerContract.Change and clears the annotated methods if the type is clear and the condition is provided. It's quite smart in handling the return value per return type.