Complex Persistent Variables

In addition to storing simple data types as variables in a variable manager, you can create your own complex variable types to use in Flux. If you choose to use a custom variable in Flux, it must follow the standards described below.

For a complete working example of a complex variable in action, see the examples/software_developers/binary_key directory under your Flux installation directory.

Note: This document describes the process for creating a custom variable type in Flux 7.10 and above. If you have a complex variable from Flux 7.9 or lower, however, it will still be fully supported and you will not need to make any changes to your existing variable code. In the interest of clarity and simplicity, variable techniques for Flux 7.9 and lower are not discussed on this page but can be found in the documentation and examples for the particular Flux version the variable was created for.

Defining the Variable Class

To create a complex variable type, you will simply need to design a new POJO Java class to represent your variable. This POJO class must have three things:

1. A default public constructor
2. A private field to store the value of each property that should be persisted
3. Public getter and setter methods for each property that should be persisted

Each property that should be persisted must also follow the rules for persistent variables. These rules are applied recursively to each property (so, for example, if the property is itself a custom variable type, the rules for persistence are applied to each property within that type, and so forth).

For example, consider the following variable classes:

public class MyVariable {

    private String recordNumber;
    private Person person;

    public MyVariable() {}

    public String getRecordNumber() {
        return recordNumber;
    }

    public void setRecordNumber(String recordNumber) {
        this.recordNumber = recordNumber;
    }

    public Person getPerson() {
        return person;
    }

    public void setPerson(Person person) {
        this.person = person;
    }
}

public class Person {

    private String name;
    private String emailAddress;

    public Person() {}

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getEmailAddress() {
        return emailAddress;
    }

    public void setEmailAddress(String emailAddress) {
        this.emailAddress = emailAddress;
    }
}

The MyVariable JavaBean stores a String (one of the supported persistent data types) and a second JavaBean, Person. The Person JavaBean itself stores two String values. From this example, you can see how the rules for persistence are applied to all complex variables that are referenced from within another variable class.

Recommended Usage

Persistent variables should only be used to store a small or moderate amount of data. If you require a significant amount of data, it is more efficient to store the data separately in your database, then store the key to the data as its own persistent variable. This will let your workflow use the key to retrieve and modify the data, without requiring the additional overhead of Flux managing the data itself (this can be costly due to the way Flux must tie the data storage and retrieval into the workflow’s execution).

Persistent Variable Lifecycle Event Callbacks

Persistent variables have a simple lifecycle. They are created and populated from data in the database. Later, after they have been changed and updated, they are stored back in the database.

If you need to perform additional work on your persistent variables after they are retrieved from the database or before they are stored back in the database, you can register for lifecycle event callbacks. To do so, simply have your persistent variable class implement the flux.PersistentVariableListener interface. Each persistent variable object whose class implements flux.PersistentVariableListener will receive callbacks during the lifecycle of the persistent variable.

These lifecycle callbacks permit you to initialize and prepare your persistent variable data as you see fit.