Skip to content

Overview

Development

Overview

IDEs

API Explorer

Decorating Gloop Services with Gloop Annotations

Gloop annotations are a set of Java annotations that are 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 Gloop 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 Coder Navigator view.

Invoke 'hidden' one-liners using Gloovy steps

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

Since a method in a Groovy or Java class has inputs and outputs like a Gloop service (in that they have parameters and a return type), the Groovy service editor in Coder Studio allows you to use the Input/Output view to add the annotations for you! Below is a GIF 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 Coder 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 the 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 Gloop service editor and in the Coder 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 Coder 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 on how to create your own Gloop-decorated Groovy services, documented through the use of 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 Coder Navigator view.

Groovy service visible in the Coder Navigator view

Groovy service visible in the Coder 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 nifty 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 Coder Navigator view once you hover over the Groovy method.

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

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

Another feature is that when you call the annotated Groovy service in a Gloop 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

Coder and Gloop both support 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 Coder 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 Coder 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 Gloop whether the method parameter allows null values
name Tells Gloop what the name of the returned object of a method is
choices Allows Coder to provide you with a list of pre-determined values for the property
allowOtherValues Tells Coder and Gloop whether this property allows other values
defaultValue If the value is null, the defaultValue will be used by Gloop 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 stated earlier, the Groovy service editor in Coder Studio is tied to the Gloop 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 Gloop 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.

Gloop-Enabled Groovy Editor

As stated earlier, the default Groovy service editor in Coder Studio is called the "Gloop-enabled Groovy editor". This editor provides additional functionality to 'decorate' Groovy services. It is connected to the Input/Output view which can be used to decorate method parameters and return types, respectively.

Properties view

The Properties view can also be used to add additional object properties of an input or return value of the method.

For example, when you write with Groovy, you will see the input parameters of the method is generated in the Input view while the return type of the method is displayed in the Output view. It will be shown while your text cursor is on the signature of the method.

Groovy service parameters map to input properties in the Input view; return type to property in Output view