facets.util.app
Class AppValues

java.lang.Object
  facets.util.Tracer
      facets.util.app.AppValues

Direct Known Subclasses:

AppSpecifier

public class AppValues
extends Tracer

Can persist/depersist configuration and session state/user preferences.

AppValues wraps two ValueNodes which can be used to read, maintain and store values on behalf of a client application.

Field Summary

java.lang.String	appName Simple name of the class passed to the constructor; expected to be the application name.
static java.lang.String	KEY_TIMEOUT Key for flag specifying instance behaviour.
static java.lang.String	KEY_TIMEOUT_SYSTEM Key for flag specifying instance behaviour.
static java.lang.String	NATURE_DEBUG Key for setting Debug.natureDebug.
static java.lang.String	NATURE_NO_SYSTEM_ACCESS Key for flag specifying instance behaviour.
static java.lang.String	NATURE_RECORD_RUNS Key for flag specifying instance behaviour.
static java.lang.String	NATURE_WRITABLE Key for flag specifying instance behaviour.
static java.lang.String	PATH_APP Type/path of values node.
static java.lang.String	PATH_CORE Type/path of values node.
static java.lang.String[]	PATH_CORE_APP Type/path of values node.
static java.lang.String[]	PATH_CORE_DEBUG Type/path of values node.
static java.lang.String	PATH_DEBUG Type/path of values node.
static java.lang.String	PATH_RUNS Type/path of values node.
static ValueNode	stateDebug Global state node for debug values.
static java.lang.String	TYPE_NATURE Type of root node, used by #storageFile(boolean).
static java.lang.String	TYPE_STATE Type of root node, used by #storageFile(boolean).

Constructor Summary

AppValues(java.lang.Class appClass)
Unique constructor.

Method Summary

protected void	addNatureDefaults(ValueNode root) Can set default configuration values.
protected void	addStateDefaults(ValueNode root) Can set default session/preferences values.
void	adjustClassValues() Can refresh class variables etc from state values.
boolean	hasSystemAccess() Can these values (and by implication the application) access the file system, clipboard etc?
ValueNode	nature(boolean core) Defines application configuration or 'nature'.
void	readValues(java.lang.String... parameters) Reads values from (in order) defaults, parameters and storage.
ValueNode	state(java.lang.String... typePath) Stores application session state and user preferences.
protected void	traceOutput(java.lang.String msg) Outputs complete trace messages to console or elsewhere.
void	tryWriteValues(java.lang.String msg) Attempts to persist current values in XML format.

Methods inherited from class facets.util.Tracer

trace, trace, trace, trace, trace, traceDebug, traceDebug, traceObjectText, traceOutputWithClass

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TYPE_STATE

public static final java.lang.String TYPE_STATE

Type of root node, used by #storageFile(boolean).

See Also:

Constant Field Values

TYPE_NATURE

public static final java.lang.String TYPE_NATURE

Type of root node, used by #storageFile(boolean).

See Also:

Constant Field Values

PATH_CORE

public static final java.lang.String PATH_CORE

Type/path of values node.

See Also:

Constant Field Values

PATH_APP

public static final java.lang.String PATH_APP

Type/path of values node.

See Also:

Constant Field Values

PATH_DEBUG

public static final java.lang.String PATH_DEBUG

Type/path of values node.

See Also:

Constant Field Values

PATH_CORE_APP

public static final java.lang.String[] PATH_CORE_APP

Type/path of values node.

PATH_CORE_DEBUG

public static final java.lang.String[] PATH_CORE_DEBUG

Type/path of values node.

PATH_RUNS

public static final java.lang.String PATH_RUNS

Type/path of values node.

See Also:

Constant Field Values

NATURE_DEBUG

public static final java.lang.String NATURE_DEBUG

Key for setting Debug.natureDebug.

Set to false for release binaries; to true in binary by passing as argument.

See Also:

Constant Field Values

NATURE_WRITABLE

public static final java.lang.String NATURE_WRITABLE

Key for flag specifying instance behaviour.

See Also:

Constant Field Values

NATURE_RECORD_RUNS

public static final java.lang.String NATURE_RECORD_RUNS

Key for flag specifying instance behaviour.

See Also:

Constant Field Values

NATURE_NO_SYSTEM_ACCESS

public static final java.lang.String NATURE_NO_SYSTEM_ACCESS

Key for flag specifying instance behaviour.

See Also:

Constant Field Values

KEY_TIMEOUT

public static final java.lang.String KEY_TIMEOUT

Key for flag specifying instance behaviour.

See Also:

Constant Field Values

KEY_TIMEOUT_SYSTEM

public static final java.lang.String KEY_TIMEOUT_SYSTEM

Key for flag specifying instance behaviour.

See Also:

Constant Field Values

stateDebug

public static final ValueNode stateDebug

Global state node for debug values.

Created empty, added as child of core state.

appName

public final java.lang.String appName

Simple name of the class passed to the constructor; expected to be the application name.

Used by storageFile(boolean).

Constructor Detail

AppValues

public AppValues(java.lang.Class appClass)

Unique constructor.

Builds data roots ready for readValues(String[]):

Parameters:

appClass - should generally be the client application class; its simple name is used for the appName field

Method Detail

addNatureDefaults

protected void addNatureDefaults(ValueNode root)

Can set default configuration values.

Called from readValues(String[]); values added are treated as defaults for nature(boolean).

Default implementation is empty.

addStateDefaults

protected void addStateDefaults(ValueNode root)

Can set default session/preferences values.

Called from readValues(String[]); values added are treated as defaults for state(String...).

Default implementation is empty.

Parameters:

root - of the state(String...) tree

readValues

public final void readValues(java.lang.String... parameters)

Reads values from (in order) defaults, parameters and storage.

Returns without effect after the first call; calls to nature(boolean) and state(String...) will fail before this method is called.

Node paths are created before reading for

• nature: PATH_CORE with basic values
• state: PATH_CORE_DEBUG and PATH_CORE_APP.

Parameters:

parameters - passed from main or constructed from applet parameters; any member not a key=value pair is interpreted as parameter=true.

adjustClassValues

public void adjustClassValues()

Can refresh class variables etc from state values.

Called from readValues(String[]); defined public to allow calls when values are changed.

Default implementation sets Debug.natureDebug.

tryWriteValues

public final void tryWriteValues(java.lang.String msg)

Attempts to persist current values in XML format.

• If NATURE_RECORD_RUNS is true, adds a child to the PATH_RUNS child of PATH_CORE.
• Will only write out the contents of nature(boolean) if NATURE_WRITABLE is true;

traceOutput

protected void traceOutput(java.lang.String msg)

Description copied from class: Tracer

Outputs complete trace messages to console or elsewhere.

Default prepends helpful classname to message.

Overrides:

traceOutput in class Tracer

Parameters:

msg - passed from one of the public methods

nature

public final ValueNode nature(boolean core)

Defines application configuration or 'nature'.

Initial contents are set by

1. reading the values returned by addNatureDefaults(ValueNode)
2. attempting to merge values from an XML .nature file named after the title passed to the constructor and accessible as a system resource.
3. Adding parameters (to both root and core nodes) as key-value pairs, verbatim if containing '=', otherwise as 'parameter=true'.

Value updates are lost after each session (which is why parameters are added to these values rather than to the ostensibly more appropriate state(String...)).

Parameters:

core - returns the framework-specific sub-node

state

public final ValueNode state(java.lang.String... typePath)

Stores application session state and user preferences.

Initial contents are set by

1. reading the values returned by addStateDefaults(ValueNode)
2. attempting to merge values from an XML .state file named after the title passed to the constructor and located in the start directory.

Value updates can be written to the .state file with tryWriteValues(String).

Parameters:

typePath - specifies a path within the state tree to a node which is created if required; no parameter specifies the root

hasSystemAccess

public boolean hasSystemAccess()

Can these values (and by implication the application) access the file system, clipboard etc?

Returns:

value of NATURE_NO_SYSTEM_ACCESS which can be passed as an argument