Reference

AmiScript: Custom Classes

Overview

AmiScript is an object oriented language with declarable objects according to different class types, each with their own associated methods.

Many of these classes are familiar, e.g: data types like Int, while others are unique to AMI to maximize developer customizability options.

3forge supports the implementation of user-written custom classes, backed by Java code, which can be imported into AMI.

Setup

Creating custom AmiScript classes follows the same general setup as other custom Java plugins. The key steps are:

1. Write the custom class in Java, implementing the necessary interfaces (listed below).
2. Export the class(es) to a .jar file.
3. Add the .jar to the amione/lib directory of the AMI installation.
4. Configure local.properties to load the custom class(es).

Requirements

The Java classes must implement the following:

1. Reference the out.jar and autocode.jar libraries in the build path of the project. The instructions for this can be found in setting up custom plugins.

2. The com.f1.ami.amicommon.customobjects.AmiScriptAccessible annotation

   • This ensures that constructors and other methods are accessible via AmiScript
   • Allows for overriding of the name of a method and its parameters within AMI

3. Extend the com.f1.ami.amicommon.library.AmiAbstractLibraryPlugin plugin

   • Custom classes are treated by AMI as plugins and need an associated unique plugin ID to be loaded in AMI

4. The name of the Java class must start with the prefix Ami

   • This allows for AMI to pick up the custom class
   • E.g: the MyClass.java would need to be AmiMyClass.java

Properties

Custom AmiScript classes and objects can be made available in both Center (AMIDB) and Web.

This can be configured with the following two properties:

ami.web.amiscript.custom.classes=comma_delimited_list_of_fully_qualified_java_class_names
ami.center.amiscript.custom.classes=comma_delimited_list_of_fully_qualified_java_class_names

Note

You must configure both properties to have the custom class accessible in both Center and Web.

To have the class available in either Center or Web, set the property for only the respective component.

Example: A Calculator Class

This is a basic guide that shows how to create a simple Calculator object.

Setup

Follow the general steps laid out above.

1. Create a Java package called "main" within your IDE of choice and add the following to your local.properties file:

   ami.web.amiscript.custom.classes=main.AmiCalculator
   ami.center.amiscript.custom.classes=main.AmiCalculator
   

   This will make the calculator available in both Web and Center

2. Within the package "main", create the class file AmiCalculator.java. Add the out.jar and autocode.jar files to the classpath of the project.

3. Import the following libraries into AmiCalculator.java class file:

   package main; 
   
   import com.f1.ami.amicommon.customobjects.AmiScriptAccessible;
   import com.f1.ami.amicommon.library.AmiAbstractLibraryPlugin;
   import com.f1.container.ContainerTools;
   import com.f1.utils.PropertyController; 
   

4. Follow the instructions below for implementing the logic in AmiCalculator.java.

Java Files

AmiCalculator.java

Within this class, we need to do the following:

1. Extend the existing AmiAbstractLibraryPlugin library to enable integration into AMI as an external plugin
2. Define the calculator AmiScript class, methods, and how it is called in AMI using AmiScriptAccessible notation

Create the class AmiCalculator which extends AmiAbstractLibraryPlugin. There are two inherited plugin methods that this class will then override:

• getPluginId()
• init()

package main; 

import com.f1.ami.amicommon.customobjects.AmiScriptAccessible;
import com.f1.ami.amicommon.library.AmiAbstractLibraryPlugin;
import com.f1.container.ContainerTools;
import com.f1.utils.PropertyController; 

public class AmiCalculator extends AmiAbstractLibraryPlugin {

    private static final String PLUGIN_ID = "Calculator";
    @Override
    public String getPluginId() {
        // TODO Auto-generated method stub
        return PLUGIN_ID;
    }

    @Override
    public void init(ContainerTools tools, PropertyController props) {
        super.init(tools, props);
    }
}

This ensures that the class is recognized by AMI.

Now, we need to define the class' functionality within AmiScript. The AmiScriptAccessible notation enables the class to be accessible within AMI. The following parameters can be set this way:

• name: the name of the method or class as called in AmiScript
• params: the name of the parameters as they are called in AmiScript
• help: the helper text associated to that method or class in AmiScript

Add the following annotations and methods to AmiCalculator.java:

package main;

import com.f1.ami.amicommon.customobjects.AmiScriptAccessible;
import com.f1.ami.amicommon.library.AmiAbstractLibraryPlugin;
import com.f1.container.ContainerTools;
import com.f1.utils.PropertyController;

@AmiScriptAccessible(name = "Calculator", help = "A custom calculator object for calculating numbers")
public class AmiCalculator extends AmiAbstractLibraryPlugin {

    private static final String PLUGIN_ID = "Calculator";
    @Override
    public String getPluginId() {
        // TODO Auto-generated method stub
        return PLUGIN_ID;
    }

    @Override
    public void init(ContainerTools tools, PropertyController props) {
        super.init(tools, props);
    }

    @AmiScriptAccessible(help = "Constructs an instance of calculator")
    public AmiCalculator() {
    }

    @AmiScriptAccessible(name = "add", params = { "left", "right" }, help = "Adds two numbers")
    public int add(int a, int b) {
        return a + b;
    }
}

The class should now be callable in AMI as Calculator with a constructor and a method named add().

Export Calculator into 3forge

Export the package as a .jar file into the amione/lib directory of your 3forge installation. Ensure that the fully qualified class names of the calculator are listed correctly in local.properties:

ami.web.amiscript.custom.classes=main.AmiCalculator
ami.center.amiscript.custom.classes=main.AmiCalculator

The Calculator class should now be available in both Center and Web when AMI is next launched.

Center (AMIDB)

Within the AMIDB shell tool, run the following command:

Calculator c = new Calculator();
c.add(1,2);

You should see the following output:

Within the same shell tool, check what methods are available:

show methods where TargetType=="Calculator"

Web

In any window that takes AmiScript, begin creating a Calculator object. You should find that as you type, AMI will autocomplete and find your Calculator class:

Similarly, any methods should also automatically be suggested:

For the same AmiScript as the AMIDB tool, you should see the following output when tested in Web: