On this page:

MyReverseString()

For this example, we imagine 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 class, we'll 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
    }
}

Our routine is now completed, we need to register it on the SIL. Let's modify the launcher we 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();
}

Under the hood (some explanations)

The above routine inherits a lot of the functionality from AbstractRoutine (http://confluence.kepler-rominfo.com/javadoc/katl-commons/2.5/com/keplerrominfo/jira/commons/sil/AbstractRoutine.html). The AbstractRoutine class is responsible for:

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

The AbstractRoutine class follows in fact a Template Method Pattern. You are not required to inherit AbstractRoutine. In fact you should sometimes implement Routine interface (http://confluence.kepler-rominfo.com/javadoc/katl-commons/2.5/com/keplerrominfo/jira/commons/sil/Routine.html) to avoid or implement custom checking of the parameters.

Don't forget to unit test your code (the above example lacks it, 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 a JIRA with both katl-commons and silexample add-ons installed.

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

string myString = myReverseString("Kepler"); //relpeK

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

Step 2: Creating A New SIL Routine

MyReverseString()

Under the hood (some explanations)

Running The Example