State is a wrapper around a user-defined state value. It allows StateManagement to decorate a user-defined state value with system-defined attributes and behaviors. An instance of State has at least the following conceptual attributes:
[mupton] - Proposed alternative names:
A State instance has a globally unique key. This key can be used to identify a State instance from among the space of all other State instances, regardless of type, underlying provider, etc.
This key is composed of (at least) two components
The user should be able to retrieve and manipulate the State instance via the user-defined key even though the system thinks of it in terms of its GUID.
A value may represent any type of data. It may or may not be a 'data structure'. Values could represent data streams, etc. Regardless of the type of data held in the value, we must have a Java type to represent the value. StateManagement does not provide any native Java type for values. The Java type is always user-defined.
The java type for a value may define an interface to manipulate or change the data within a value. If such an interface is available, the value is considered 'mutable'. If not, the value is considered 'immutable'. For example, a Java POJO might be mutable whereas a Java String is always immutable.
In order to support flexible handling of mutable and immutable values, State must include a method to make a wholesale replacement of the value contained within a State instance.
The StateManagerProvider may need to track certain information about a State object, and users may find it useful to have some tracking information as well. Common tracking information might be:
StateManager is a manager for State instances and the lifecycle control of State instances. At a minimum, StateManager must allow:
This is a factory for StateManager instances, and used by clients. It is backed/implemented by a StateManagerProvider. The provider is invisible to the client as the client never uses it directly.
The client is matched with a StateManagerFactory by performing a 'factory query' specifying any of the following:
This is the main interface providers for StateManagement use to expose their capabilities. The StateManagerProvider interface is also a StateManagerFactory, a factory for StateManager instances. The provider that implements StateManagerProvider also implements StateManagerFactory, StateManager and StateContainer, so it is the source of all behavior for those interfaces.
A provider must implement the base StateManagement interfaces (StateManagerProvider, StateManager, StateContainer). It can then choose to implement any other capabiliities it wishes. The provider makes its capabilties known via the StateManagerProvider interface.
StateManagerProvider instances are then registered (at runtime). This registration makes the provider's StateManagerFactory available to clients.
A capability is some behavior or function that a provider offers that goes above and beyond those defined in the base interfaces for StateManagement (StateManagerProvider, StateManager, State). Capabilities may define a specific quality of service (QoS) such as the ability to durably store state data in the face of machine crashes. Capabilities may define specific behaviors like the ability to group operations on state data into transactions that allow the entire group of operations to be committed or rolled back as a unit. In some cases, these specific behaviors may require an extra functional interface, beyond those defined in the core of StateManagement.
A capability definition includes: