Form Object and Factory

The form object and its associated factory are optional and only need to be implemented if the schedule task requires a custom configuration user interface.

• Form Object
• Task Configuration Object
• Form Factory

Form Object

Interface: de.espirit.firstspirit.scheduling.ScheduleTaskForm
FirstSpirit Developer API: ScheduleTaskForm <D extends ScheduleTaskData>

The form object provides a custom configuration user interface for the task. The class implementation of ScheduleTaskForm must be parameterized with the type of the custom data object.

/**
 * This class handles configuration of the task. It provides functionality which displays a
 * configuration UI and methods which loads and stores task configuration data around that UI.
 */
public class MyScheduleTaskForm implements ScheduleTaskForm<MyScheduleTaskData> {

    private final SpecialistsBroker _broker;
    private boolean _customTextShown;

    public MyScheduleTaskForm(@NotNull final SpecialistsBroker broker) {
        _broker = broker;
    }

    /**
     * Load data from the custom data object so that this data is available when the configuration UI
     * is drawn (when MyScheduleTaskForm#openAndWait(...) is called).
     */
    @Override
    public void load(@NotNull final ScheduleTaskConfiguration<MyScheduleTaskData> configuration) {
        final MyScheduleTaskData myScheduleTaskData = configuration.getCustomData();
        if (myScheduleTaskData != null) {
            final String customText = myScheduleTaskData.getText();
            _customTextShown = customText != null && !customText.isEmpty());
            return;
        }
        _customTextShown = false;
    }

    /**
     * Store the current configuration data in a custom data object (after the call to
     * MyScheduleTaskForm#openAndWait(...) is finished).
     */
    @Override
    public void store(@NotNull final ScheduleTaskConfiguration<MyScheduleTaskData> configuration) {
        final MyScheduleTaskData myScheduleTaskData = configuration.getCustomData();
        if (_customTextShown) {
            myScheduleTaskData.setText("Here's some custom text.");
        } else {
            myScheduleTaskData.setText(null);
        }
        configuration.setCustomData(myScheduleTaskData);
    }

    /**
     * Create a configuration UI, wait for user input, and finally process that user input.
     *
     * In this specific case, we use a message box which asks the user if the custom text should
     * (continue to) be displayed. If the user answers "yes", the custom data object will be configured
     * with a custom text, and if the user answers "no", the custom data object will be configured with
     * a null object as custom text.
     */
    @Override
    public boolean openAndWait(@NotNull final Window parent, @NotNull final String title) {
        final OperationAgent operationAgent = _broker.requireSpecialist(OperationAgent.TYPE);
        final RequestOperation requestOperation = operationAgent.getOperation(RequestOperation.TYPE);
        if (requestOperation != null) {
            // Configure the message box which we'll draw using the RequestOperation.
            requestOperation.setKind(RequestOperation.Kind.QUESTION);
            requestOperation.setTitle(title);
            final Answer yesAnswer = requestOperation.addYes();
            final Answer noAnswer = requestOperation.addNo();
            requestOperation.addCancel();

            // Display a message box as configured, using a text which reflects the current data object.
            Answer givenAnswer;
            if (_customTextShown) {
                givenAnswer = requestOperation.perform("A custom text is currently being shown for this task." +
                        "\n\nWould you like to continue showing the custom text?");
            } else {
                givenAnswer = requestOperation.perform("A custom text is currently not being shown for this task." +
                        "\n\nWould you like to start showing the custom text?");
            }

            // Handle the returned answer.
            if (yesAnswer.equals(givenAnswer)) {
                _customTextShown = true;
                return true;
            } else if (noAnswer.equals(givenAnswer)) {
                _customTextShown = false;
                return true;
            } else {
                return false;
            }
        }
        return false;
    }
}

Task Configuration Object

FirstSpirit Developer API: ScheduleTaskForm$ScheduleTaskConfiguration <D extends ScheduleTaskData>

This object holds configuration data associated with the current task. First and foremost, it provides the custom data object stored with the task and allows updates of this data. The object also provides methods to read and write the task name and description information.

Form Factory

Interface: de.espirit.firstspirit.scheduling.ScheduleTaskFormFactory
FirstSpirit Developer API: ScheduleTaskFormFactory <D extends ScheduleTaskData>

The factory object is registered in the component descriptor for the schedule task plug-in and is used to instantiate and configure a form object. Its only method createForm receives a SpecialistsBroker object as a parameter which is able to access most user interface-based agents and operations (see OperationAgent for more information) in order to allow the form object to provide interactive functionality based on FirstSpirit API functionality. The class implementation of ScheduleTaskFormFactory must be parameterized with the type of the custom data object.

/**
 * This class provides a method that instantiates and returns a ScheduleTaskForm object. In this specific
 * case, the MyScheduleTaskForm object is constructed with an instance of SpecialistsBroker in order to
 * use FirstSpirit API functionality to create a configuration UI.
 */
public class MyScheduleTaskFormFactory implements ScheduleTaskFormFactory<MyScheduleTaskData> {

    @Override
    ScheduleTaskForm<MyScheduleTaskData> createForm(@NotNull final SpecialistsBroker broker) {
        return new MyScheduleTaskForm(broker);
    }
}