MyReverseString()

For this example, let's suppose that we need to reverse certain strings within Jira, and a reverse string routine might be handy. Since SIL™ does not provide such a function, let's implement it.

In the main package (com.mycompany.silexample) create a new class and name it ReverseStringRoutine.

The code is presented below, along with the comments.

/*
 * Created at Sep 2, 2011T5:39:27 PM+02.
 *
 * File: ReverseStringRoutine.java
 */
package com.mycompany.silexample;

import java.util.*;

import com.keplerrominfo.common.util.MutableString;
import com.keplerrominfo.sil.lang.*;
import com.keplerrominfo.sil.lang.type.TypeInst;
import com.keplerrominfo.sil.lang.SILValue;
import com.keplerrominfo.sil.lang.SILValueFactory;

/**
 * Reverses a string
 *
 * @author Radu Dumitriu (rdumitriu@gmail.com)
 * @since 1.0
 */
public class ReverseStringRoutine extends AbstractRoutine<MutableString> {
    private static final SILType[][] types = {{ TypeInst.STRING }}; //all possible type combinations are listed here

    public ReverseStringRoutine(String name) {
        super(name, types);
    }

    /**
     * Returns the type of the returned value. For routines that return
     * a value of variable type, this should return null
     *
     * @return the type of the returned value
     */
    @Override
    public SILType<MutableString> getReturnType() {
        return TypeInst.STRING;
    }

    /**
     * The execution of the routine
     * @param silValues the list of values (parameters)
     * @return the SIL value
     */
    @Override
    protected SILValue<MutableString> executeRoutine(SILContext context, List<SILValue<?>> silValues) {

        //AbstractRoutine checks the parameters and their types
        SILValue param = silValues.get(0);

        //We know for sure this is a string
        String val = param.toStringValue();

        //we calculate the reversed value
        String reversedVal = new StringBuilder(val).reverse().toString();

        //We'll prepare the return here
        return SILValueFactory.string(reversedVal);
    }

    /**
     * This returns the description of the parameters
     * @return the part that will be appended to the routine at editing time
     */
    @Override
    public String getParams() {
        return "(str)"; //that's all
    }
}

The routine is now completed, now you need to register it on the SIL™. To do this, modify the launcher you created in the previous step.

@Override
public void doAtLaunch() {
    super.doAtLaunch();

    //register the routine
    RoutineRegistry.register(new ReverseStringRoutine("myReverseString"));
}

@Override
public void doAtStop() {
    //first, make sure that super is called, even if will have an exception here
    try {
        //unregister the routine
        RoutineRegistry.unregister("myReverseString");
    } catch(Exception e) {
        LOG.error("Failed to unregister!", e);
    }
    
    super.doAtStop();
}

Things happening under the hood

The above routine inherits a lot of the functionality from AbstractRoutine, and this class is responsible for:

Checking the type of the parameters
Converting the parameters to the required types automatically
Calling the real execution code with the parameters transformed.

The AbstractRoutine class follows a Template Method Pattern. You are not required to inherit AbstractRoutine. In fact, sometimes you should implement a routine interface to avoid or implement custom checking of the parameters.

Don't forget to unit test your code. We didn't include it in the example, but you should feel obliged to do it.

Running the example

Open a terminal or a console and run atlas-debug in the root of the project. It will launch Jira with both SIL Engine™ and silexample add-ons installed.

In the SIL Manager, open a test .sil file and write something like:

string myString = myReverseString("Appfire");

If everything is fine, the editor will auto-complete the routine.

Power Suite Apps for Jira

Step 2: Creating A New SIL Routine

MyReverseString()

Things happening under the hood

Running the example