Field Actors

The Field Actors are used for three purposes: conversion to a Value from a native value, conversion from a Value to a native value, and validation. They are written in a Java class and are intended to be re-used in many parts of the application as required. The native value is the value used for the conversion, generally String or KString, but supports any Java Object. The validation is done on the Value itself (i.e. has already passed the conversion stage to a Value).

The VSFieldEvent parameter has access methods to what you need to perform the task, and is also used to set a validation message for conversion or validation failures.

The actor is an instance method of a name of your choice, annotated by @OnVSField in the class that is attached to the namespace, or it can be a static class located in Java libraries (Jar files) or other Java projects annotated with @OnVSFieldStatic.

Example of namespace class instance:

package mypkg;

import com.iizix.api.vs.OnVSField;
import com.iizix.api.vs.VSFieldEvent;
import com.iizix.api.vs.VSFieldEvent.Category;
import com.iizix.api.vs.VSFieldEvent.Op;
import com.iizix.api.vs.VirtualSpace;
import com.iizix.text.KString;

/**
 * JavaDoc shown in tooltips when hovering mouse over the class reference.
 */
@VirtualSpace(ref = "FirstProject:/vs/start")
public class StartNameSpaceListener {

    /**
     * This JavaDoc is shown in when hovering mouse over a method reference.
     * 
     * @param event
     *            The VS Field event.
     */
    @OnVSField(name = "fld", descr = "MyFieldActor ABC 123", ops = { Op.VALIDATE },
               source = { String.class })
    public void onField(VSFieldEvent event) {
        Object value = event.getConvertedValue();
        if (value instanceof String) {
            // Do your validation.
            String s = (String) value;
            if (s.equals("123")) {
                event.setMessage(
                        KString.newPlainKString("123 is not a valid value"),
                        Category.WARNING);
            }
        }
    }
}

In the context menu of the field actors, select New Field Actor, then the dialog box will list all available methods from the namespace attached class, and those that would match that are on the project’s classpath (including static methods in libraries and other projects):

When you select a method in the list, its description taken from the descr = "string" of the method annotation. When you close the dialog box, the tooltip of the field actor could look like: