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.
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 |
|
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.
@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 |
|
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.
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.
Use Markdown in your @GloopComment
annotations
Martini supports the use of Markdown in your @GloopComment
annotations.
@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 |
|
@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 |
|
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:
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 |
|
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.
After which, our code should now look like:
1 2 3 4 5 6 7 8 9 10 11 12 |
|
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 |
|
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.