UserDataStorage
Portals can store data on the server for later retrieval. If the user is authenticated, the stored data is persisted between sessions. Otherwise, it expires when the client session expires.
There are three types of nonindexed persistent data: values, counters, and lists. Each is associated with a key. A key may have all three types of values.
Values
Values are stored via put(String, Object) and retrieved via
get(String). Values can be anything that can be serialized
as JSON, including strings, numbers, booleans, lists, and data structures.
Data values are serialized as JSON when stored in the database, and
de-serialized when retrieved. If a value is a complex non-map object when it
is stored, it will be retrieved as a map.
Lists
Lists are essentially managed arrays that can be added to or removed from
without needing to retrieve the full data structure. You create/add to lists
via push(String, Object, int) or pushUnique(String,
Object, int). The full list can be retrieved via
getList(String). Elements can be removed via
removeFromList(String, Object). You can check whether a
value exists in a list via existsInList(key). Like values,
list entries can be anything that can be serialized as JSON.
Counters
Counters are whole number values that can be easily incremented and
decremented with the atomic operation incrementCounter(String,
long). They can also be retrieved and stored via
getCounter() and setCounter().
Important: The three values are treated independently. If you set a
value via setCounter(), it must be retrieved by
getCounter(); it will not be retrieved by
get(). Similarly, lists stored with put()
cannot be modified via push(). However, if a given key has
more than one type of value - a list and a counter, for instance - calling
delete() on that key will delete all the associated data.
Categories
A category is implicitly defined by keys beginning with a certain prefix and a period. For example, deleteCategory('foo') would delete any entry with a key beginning with 'foo.' ('foo.a', 'foo.b', etc.). It would not delete 'foo'. There are a number of methods that allow the interaction with whole groups of entries by their category. This allows the development of features that involve an interaction of multiple keys such that they can be deleted.
Introduced in version 4.0.
Methods
-
void put( String dataKey, Object data) - Stores data with a key. If the data is a string, it is stored as-is. Otherwise, it is converted to JSON and then stored.
-
Object get( String dataKey) - Retrieves the data with the given key. Objects are encoded as JSON for storage, so the resulting object will be whatever type was stored, unless it's an object, in which case it will be represented as a map hierarchy.
-
void push( String listKey, Object value, int cap) - Pushes a new value onto the list with the given key.
-
void pushUnique( String listKey, Object value, int cap) - Pushes a new value onto the list with the given key. If it already exists in the list, it is removed and moved to the top.
-
boolean existsInList( String listKey, Object value) - Determines whether the given value exists in the list with the given key.
-
void removeFromList( String listKey, Object value) - Removes the given value from the list with the given key.
-
void incrementCounter( String key, long by) - Increments the counter with the given key by the given amount (which may be negative). If no such counter exists, it will be created and set to the given increment value.