Skip to content

Toro Cloud Dev Center


Decorating services with Gloop annotations

Gloop annotations are a set of Java annotations used on Groovy services (methods) and Java code to provide additional information on the usage, and inputs and outputs of a service. Adding these annotations to your Groovy services makes it easier to use them in your services.

Decorating a Groovy service is as simple as adding annotations to it. These annotations will help you easily create input and output models, add properties to certain parameters, document, and hide a service from the Navigator view.

Invoke 'hidden' functions using script steps

Even if a method doesn't appear in the Navigator, you can invoke it from a Groovy script step if it's in the classpath.

Since a method in a Groovy or Java class has inputs and outputs like a service (in that they have parameters and a return type), the Groovy service editor in Martini Desktop allows you to also use the Input/Output view to add annotations. Below is an image that shows what happens when an input parameter has a default value and comment added to it using the Properties table. You will notice that the annotation is being added to and updated in the Groovy source code as the properties are being modified.

Input/Output view's label

The Input/Output view's label changes to the name of the method while editing a Groovy service.

Annotating a Groovy service using the Groovy service editor

public static please!

You can decorate any Groovy service with Gloop annotations, but for it to appear in the Navigator and be usable from Gloop, you must have a Groovy class with a public static method.

Gloop annotations

Below is a table listing all existing Gloop annotations which can be used in order to document a Groovy service, including a short description of their purpose (or usage).

Annotation Description
GloopComment Adds a comment that describes the service (method), or parameter in general. When used on a method, this comment is shown in the service editor and in the Navigator view. When used on a parameter, it's used in the Input/Output view and in the Mapper view.
GloopHide Hides a method from the Navigator view.
GloopParameter Provides information about a service's input and output variables.
GloopObjectParameter Used to describe the properties of a Gloop model.

GloopDocsDemo.groovy

The examples package contains a Groovy script named GloopDocsDemo.groovy which demonstrates how Gloop annotations can be applied to a Groovy service.

Decorating a Groovy service with Gloop annotations

This section will guide you through creating your own Gloop-decorated Groovy services, documented using Gloop annotations.

We will start by creating a Groovy service with a public static method. If a Groovy method is not public static, the Groovy service can't be used in Gloop. Consider the snippet below:

1
2
3
4
5
6
7
8
9
class Calculator {

    static Integer getSum(Integer... input) {
        int sum = 0
        input.each { sum+=it }
        sum
    }

}

You'll be able to tell a Groovy service is exposed to Gloop once you have saved your changes without compilation errors and the service is visible in the Navigator view.

Groovy service visible in the Navigator view

Groovy service visible in the Navigator view

@GloopComment

The @GloopComment annotation should be written right before the signature of the Groovy method, like any other method-level Java annotation. The @GloopComment annotation is used to document the Groovy service in Gloop.

1
2
3
4
5
6
7
8
9
class Calculator {

    @GloopComment('Computes for the sum of the given integers')
    static Integer getSum(Integer... input) {
        int sum = 0
        input.each { sum+=it }
        sum
    }
}

To import or not to import?

The code above didn't import the @GloopComment annotation. This is because the code was compiled using a compilation customizer that automatically imports it for you.

After successfully compiling your Groovy class, the value of the @GloopComment annotation will then be shown as a tooltip in the Navigator view once you hover over the Groovy method.

The value of `@GloopComment` shown as a tooltip in the Navigator view

The value of `@GloopComment` shown as a tooltip in the Navigator view

Another feature is that when you call the annotated Groovy service in a service via an invoke step, you will be able to see the value of @GloopComment as a line comment in the same step.

The value of `@GloopComment` shown as an inline comment when the annotated service is used in a step

The value of `@GloopComment` shown as an inline comment when the annotated service is used in a step

Use Markdown in your @GloopComment annotations

Martini supports the use of Markdown in your @GloopComment annotations.

Markdown usage in `@GloopComment`

Markdown usage in `@GloopComment`

@GloopHide

The @GloopHide annotation is used to stop a public static method from appearing in the Navigator view. This is useful when you have utility methods that need to be public static so other Groovy code can use it, but don't want the method appearing in the Navigator.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
class Calculator {

    @GloopHide
    @GloopComment('Computes for the sum of the given integers')
    static Integer getSum(Integer... input) {
        int sum = 0
        input.each { sum+=it }
        sum
    }
}

@GloopParameter

The @GloopParameter annotation is used to describe a method parameter or the method's return type with extra information that makes it analogous to a Gloop property. The table below describes the parameters supported by the @GloopParameter annotation and what they do, as well as links to the associated Gloop documentation. This is because Gloop will treat these annotated code parameters and return types like a Gloop property:

Property Description
value Describes the property (it's treated as a comment).
allowNull Tells Martini whether the method parameter allows null values.
name Tells Martini what the name of the returned object of a method is.
choices Allows Martini to provide you with a list of pre-determined values for the property.
allowOtherValues Tells Martini whether this property allows other values.
defaultValue If the value is null, the defaultValue will be used by Martini instead.
allowExtraProperties If this annotation is annotating a Gloop model, then this will determine whether the model allows extra properties or not.

The code below shows how this annotation and its properties may be used.

1
2
3
4
5
6
7
8
9
class Calculator {
    @GloopComment('Computes for the sum of the given integers')
    static Integer getSum(
        @GloopParameter(value = 'The integers to add', defaultValue = '[1, 2, 3, 4, 5]') Integer[] input){
        int sum = 0
        input.each { sum+=it }
        sum
    }
}

As mentioned earlier, the Groovy service editor in Martini Desktop is tied to the Input/Output view, meaning as the cursor moves around your code, the Input/Output view will update itself with the method parameters and return types of your code. When you want to start annotating your code, simply place the cursor in the appropriate section and use the Input/Output view like you would when editing a service, as shown below:

Annotating a Groovy service using the Groovy service editor

This annotation can also be used on a method. If it's used on a method, the annotation should be placed before the method signature, and will be used by Gloop to describe the method's return type.

@GloopObjectParameter

The @GloopObjectParameter annotation is used by Gloop to describe Gloop models. The value of the annotation is used to tell Gloop what the corresponding Gloop model will look like. It describes everything - from the structure of the model, the properties that make it up, their types, their names, whether the model references another, and whether the model allows extra properties or not. The annotation expects this information using a structure called GloopDoc which can be hard to understand, and which is why the editor generates it for you.

Consider the Person.newPerson(String, String, int) method defined below, which returns a GloopModel.

1
2
3
4
5
class Person {
    static GloopModel newPerson(String firstName, String lastName, int age) {
        // TODO
    }
}

In order to let Gloop know what a GloopModel returned by Person.newPerson(String, String, int) would look like, we'll use the @GloopObjectParameter annotation, which we will generate using the Groovy service editor's Input/Output view.

Generating the `@GloopObjectParameter` annotation using the Groovy service editor's Mapper view

After which, our code should now look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import io.toro.gloop.annotation.GloopObjectParameter
import io.toro.gloop.annotation.GloopParameter
import io.toro.gloop.object.property.GloopModel

class Person {

    @GloopObjectParameter("output{\n  person{\n    firstName\n    lastName\n    age:int\n  }\n}\n")
    static GloopModel newPerson(String firstName, String lastName, int age) {
        // TODO
    }

}

Now that we have documented our Groovy service's return type, let's complete the method by adding its body. For this, our objective is simple: create the promised Gloop model using method arguments and return this model.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import io.toro.gloop.annotation.GloopObjectParameter
import io.toro.gloop.annotation.GloopParameter
import io.toro.gloop.object.property.GloopModel

class Person {
    @GloopObjectParameter("output{\n  person{\n    firstName\n    lastName\n    age:int\n  }\n}\n")
    static GloopModel newPerson(String firstName, String lastName, int age) {
        GloopModel output = GloopObject.fromGloopDoc(
            'output{\n  person{\n    firstName\n    lastName\n    age:int\n  }\n}\n')
        output.person.name = name
        output.person.age = age
        output.person.gender = gender
        output
    }
}

In line 7 and 8, we make a call to GloopObject.fromGloopDoc(String). This method builds a GloopModel object using the passed in GloopDoc string.

When you write a service that uses a model, generate the Gloop annotation (as demonstrated in the short GIF image displayed earlier), then copy and paste it as the argument to the GloopObject.fromGloopDoc(String) method, as the snippet above shows.

Use on method parameters

This annotation can also be used for the method parameters (inputs) of a method that are Gloop models.