stella.xml
Class ElementHelper

java.lang.Object
  util.PropertyContainer
      util.PropertyResources
          util.PropertyBundles
              stella.xml.ElementHelper

All Implemented Interfaces:

Cloneable, UserAdjustable, UserDetails, Initializable, LocalizedSupplying, PropertySupplying, ResourceSupplying

Direct Known Subclasses:

JElementHelper, MeritHelper, ObjectHelper, SequenceHelper

public class ElementHelper
extends PropertyBundles
implements Initializable, UserAdjustable, UserDetails

A class that allows xml-elements that require or support constant lists to easily verify if the user-supplied input is sufficient. To do so, each element helper holds a boolean expression of parameter names, e.g.

 (ExposureTime|SignalToNoise)&FilterName
 

As soon as the user supplies a value for a parameter, it toggles to boolean true and the entire requirement can be checked for fullfillment with a call to isValid(). To get the list of still unset parameters, call getMissing(). Note that this method will always return all the missing parameters, even if they are not any more needed for validity. In particular, the example above will still list the ExposureTime as missing, even if the SignalToNoise has been specified.

Nested Class Summary

static class

ElementHelper.Valid Test the validity of an element helper.

Nested classes/interfaces inherited from class util.PropertyResources

PropertyResources.URLResource

Field Summary

private BooleanNode	bol The boolean expression parser, initialized at construction.
private Map<String,Object>	constants The mapping of constant names to their values or to null if undefined.
static String	KEY_APPENDIX The appendix to link a single key to two values.
static String	KEY_HELPERCLASS The key mapping to the element helper class name.
static String	KEY_ID The key mapping to ID key name.
static String	KEY_INIT Matches constant names to their initial values.
static String	KEY_REQUIREMENT The boolean expression defining the validity requirement.
static String	KEY_SETTABLE Matches variable names that are settable.
static String	KEY_TYPEMAP Matches variable names to class type names.
static String	KEY_VALUEDETAILS The mapping of variable names to a more detailed description.
private List<String>	settable The list of variable names that are settable by the user.
private Map<String,String>	types The mapping of constant names to their class types.

Fields inherited from class util.PropertyBundles

KEY_LOCALECOUNTRY, KEY_LOCALELANGUAGE, KEY_RESOURCEBUNDLES

Fields inherited from class util.PropertyResources

KEY_NOINITONCREATE, localurl, locate, POSTFIX_DIR, POSTFIX_EXT, POSTFIX_FILE, POSTFIX_LIST, POSTFIX_URL, urlset

Fields inherited from class util.PropertyContainer

KEY_LISTSEPARATOR, KEY_MAPKEYVALUECHAR, KEY_MAPSEPARATOR

Fields inherited from interface util.ResourceSupplying

KEY_URLRESOURCES, KEY_URLUSECONFIG, KEY_URLUSECURRENT, KEY_URLUSEHOME

Fields inherited from interface util.PropertySupplying

CONFIG, KEY_CLASS

Constructor Summary

ElementHelper(Map<String,String> prop)
Constructs a new constant helper.

Method Summary

static ElementHelper	createElementHelper(Map<String,String> prop) Creates a ElementHelper using the provided properties.
static List<ElementHelper>	createElementHelpers(ResourceSupplying i, String props) Converts a comma-separated list of property files into a list of ElementHelpers by reading the properties and passing them to the element helper constructor.
protected List<ElementHelper>	createElementHelpers(String props) Converts a comma-separated list of property files into a list of ElementHelpers by reading the properties and passing them to the element helper constructor.
static Map<Object,ElementHelper>	createHelperMap(ResourceSupplying i, String props) Converts a comma-separted list of property files into a mapping of ElementHelpers to keys queried from the helpers by asking their property named according to the second argument.
protected Map<Object,ElementHelper>	createHelperMap(String props) Converts a comma-separted list of property files into a mapping of ElementHelpers to keys queried from the helpers by asking their property named according to the second argument.
protected void	debug(String warn) Issues an info message.
void	erase() Sets up the lookup table of constant names to constant values.
protected void	error(String warn) Issues an error message.
protected void	fatal(String warn) Issues an error message.
static ElementHelper	fromResourceName(ResourceSupplying i, String file) Creates a single element helper from a specified named resource, normally a properties file.
protected ElementHelper	fromResourceName(String file) Creates a single element helper from a specified named resource, normally a properties file.
Map<String,Object>	getDefined() Returns all mappings to non-null values, thus returns all constants that are set.
Map<String,String>	getDetails() Returns detailed description to the settable variables as found in the properties.
Object	getID() Returns the value of the id-varibale.
Map<String,Object>	getMissing() Returns a list of names of all constants that are still unset.
Map<String,Object>	getRequired() Returns all variables that are named in the requirement section.
Map<String,Object>	getSettable() Returns a mapping of all settable variables against their current values, including unset variables.
Class<?>	getType(String name) Returns the entry in the types map as a class object.
Object	getValue(String name) Returns the present value of the constant.
Map<String,Object>	getVariables() Returns all mappings present, valid and invalid ones.
protected void	info(String warn) Issues an info message.
void	init() Initializes the types look-up table and the boolean node.
boolean	isValid() Checks if the required constants have been set.
boolean	setValue(String name, Object val) Sets the constant of the given name to the given value.
private boolean	setValue(String name, Object val, boolean force) Sets the constant of the given name to the given value.
String	toLongString()
String	toString() Returns a description of this element helper.
boolean	update() Returns true, as normal element helpers do not have dependant variables.
protected void	warn(String warn) Issues a warning message.

Methods inherited from class util.PropertyBundles

clone, getLocalized, getLocalized, getLocalizedString, getLocalizedString, loadResource

Methods inherited from class util.PropertyResources

createFrom, createFrom, createFrom, getApplet, getAsResources, getLocalClassLoader, getPropertiesToKey, getPropertiesToKey, getResource, getResourceAsStream, getResourceFromKey, getResources, keyCreate, keyCreate, reload, setApplet

Methods inherited from class util.PropertyContainer

augment, augment, augment, defaultBoolean, defaultChar, defaultDouble, defaultFloat, defaultInt, defaultLong, defaultObject, defaultObject, defaultProperties, defaultProperty, getAsBoolean, getAsChar, getAsDouble, getAsEnums, getAsFloat, getAsInt, getAsList, getAsLong, getAsMap, getAsMap, getAsObject, getAsObject, getProperties, getProperty, has, isNew, parseObject, reload, removeProperty, rescanned, setObject, setProperties, setProperty, stringProperties

Methods inherited from class java.lang.Object

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

Methods inherited from interface util.ResourceSupplying

getResource, getResourceAsStream, getResources

Methods inherited from interface util.PropertySupplying

defaultBoolean, defaultChar, defaultDouble, defaultFloat, defaultInt, defaultLong, defaultObject, defaultObject, defaultProperties, defaultProperty, getAsBoolean, getAsChar, getAsDouble, getAsFloat, getAsInt, getAsList, getAsLong, getAsMap, getAsObject, getAsObject, getProperties, getProperty, has, parseObject, removeProperty, setObject, setProperty, stringProperties

Field Detail

KEY_HELPERCLASS

public static final String KEY_HELPERCLASS

The key mapping to the element helper class name.

See Also:

Constant Field Values

KEY_ID

public static final String KEY_ID

The key mapping to ID key name.

See Also:

Constant Field Values

KEY_TYPEMAP

public static final String KEY_TYPEMAP

Matches variable names to class type names. All variables present.

See Also:

Constant Field Values

KEY_SETTABLE

public static final String KEY_SETTABLE

Matches variable names that are settable.

See Also:

Constant Field Values

KEY_INIT

public static final String KEY_INIT

Matches constant names to their initial values.

See Also:

Constant Field Values

KEY_REQUIREMENT

public static final String KEY_REQUIREMENT

The boolean expression defining the validity requirement.

See Also:

Constant Field Values

KEY_VALUEDETAILS

public static final String KEY_VALUEDETAILS

The mapping of variable names to a more detailed description.

See Also:

Constant Field Values

KEY_APPENDIX

public static final String KEY_APPENDIX

The appendix to link a single key to two values.

See Also:

Constant Field Values

bol

private BooleanNode bol

The boolean expression parser, initialized at construction.

constants

private Map<String,Object> constants

The mapping of constant names to their values or to null if undefined.

types

private Map<String,String> types

The mapping of constant names to their class types.

settable

private List<String> settable

The list of variable names that are settable by the user.

Constructor Detail

ElementHelper

public ElementHelper(Map<String,String> prop)

Constructs a new constant helper. Calls the erase() method to ensure proper functionality.

Method Detail

init

public void init()

Initializes the types look-up table and the boolean node. Calls the erase() method.

Specified by:

init in interface Initializable

Overrides:

init in class PropertyResources

erase

public void erase()

Sets up the lookup table of constant names to constant values. Erases all previously set variable values.

getID

public Object getID()

Returns the value of the id-varibale. The name of this variable is given by the KEY_ID key.

Specified by:

getID in interface UserAdjustable

Returns:

A unique identifier, normally a string.

isValid

public boolean isValid()

Checks if the required constants have been set. Each constant set toggles the boolean value in the KEY_REQUIREMENT section to true, undefined constants are false. The evaluation of the entrie string is then returned.

Specified by:

isValid in interface UserAdjustable

getMissing

public Map<String,Object> getMissing()

Returns a list of names of all constants that are still unset. Note that this is independend from the requirement, thus even variables in an OR context will be returned as missing. For convenience, this method returns a mapping of the missing names to null values.

Specified by:

getMissing in interface UserAdjustable

getRequired

public Map<String,Object> getRequired()

Returns all variables that are named in the requirement section.

Specified by:

getRequired in interface UserAdjustable

getDefined

public Map<String,Object> getDefined()

Returns all mappings to non-null values, thus returns all constants that are set. Independent of the requirement. This method is useful to return only the constants set to a value, as soon as the requirement is fulfilled.

Specified by:

getDefined in interface UserAdjustable

getVariables

public Map<String,Object> getVariables()

Returns all mappings present, valid and invalid ones.

Specified by:

getVariables in interface UserAdjustable

getSettable

public Map<String,Object> getSettable()

Returns a mapping of all settable variables against their current values, including unset variables.

Specified by:

getSettable in interface UserAdjustable

getDetails

public Map<String,String> getDetails()

Returns detailed description to the settable variables as found in the properties.

Specified by:

getDetails in interface UserDetails

getValue

public Object getValue(String name)

Returns the present value of the constant. If the constant was not set, null is returned.

Specified by:

getValue in interface UserAdjustable

getType

public Class<?> getType(String name)

Returns the entry in the types map as a class object.

Specified by:

getType in interface UserAdjustable

update

public boolean update()

Returns true, as normal element helpers do not have dependant variables.

Specified by:

update in interface UserAdjustable

Returns:

False, if update failed for whatever reason.

setValue

public boolean setValue(String name,
                        Object val)

Sets the constant of the given name to the given value. The value needs not to be a string, but if it is, the KEY_TYPEMAP is queried for the correct class type and a new instance of this class is stored in the constants look-up table, instantiated with the string as the only argument in the constructor.
If called with a value of null, the constant is erased.

Specified by:

setValue in interface UserAdjustable

Returns:

The previuos value of the constant.

fatal

protected void fatal(String warn)

Issues an error message. This class pipes directly to Syslog.error.

error

protected void error(String warn)

Issues an error message. This class pipes directly to Syslog.error.

warn

protected void warn(String warn)

Issues a warning message. This class pipes directly to Syslog.warning.

info

protected void info(String warn)

Issues an info message. This class pipes directly to Syslog.info .

debug

protected void debug(String warn)

Issues an info message. This class pipes directly to Syslog.info .

setValue

private boolean setValue(String name,
                         Object val,
                         boolean force)

Sets the constant of the given name to the given value. The value needs not to be a string, but if it is, the KEY_TYPEMAP is queried for the correct class type and a new instance of this class is stored in the constants look-up table, instantiated with the string as the only argument in the constructor.
If called with a value of null, the constant is erased.

Parameters:

force - If true, even non-settable variables are set. This is done during initialization.

Returns:

The previuos value of the constant.

toString

public String toString()

Returns a description of this element helper.

Overrides:

toString in class PropertyContainer

toLongString

public String toLongString()

createElementHelper

public static ElementHelper createElementHelper(Map<String,String> prop)

Creates a ElementHelper using the provided properties. If the properties do not contain a PropertySupplying.KEY_CLASS property the standard ElementHelper class is used. If one wants to create daughter classes of the ElementHelper, e.g. to provide GUI-enhanced functionality, the properties should contain a class entry of this telescope helper subclass.

fromResourceName

protected ElementHelper fromResourceName(String file)

Creates a single element helper from a specified named resource, normally a properties file.

fromResourceName

public static ElementHelper fromResourceName(ResourceSupplying i,
                                             String file)

Creates a single element helper from a specified named resource, normally a properties file.

createElementHelpers

public static List<ElementHelper> createElementHelpers(ResourceSupplying i,
                                                       String props)

Converts a comma-separated list of property files into a list of ElementHelpers by reading the properties and passing them to the element helper constructor.

createElementHelpers

protected List<ElementHelper> createElementHelpers(String props)

Converts a comma-separated list of property files into a list of ElementHelpers by reading the properties and passing them to the element helper constructor.

createHelperMap

public static Map<Object,ElementHelper> createHelperMap(ResourceSupplying i,
                                                        String props)

Converts a comma-separted list of property files into a mapping of ElementHelpers to keys queried from the helpers by asking their property named according to the second argument. A warning is issued if two identical mappings exist, in which case only the later on is kept. Note that this method can only work correctly if the value of the ID-field is already set after initialization, i.e. it must be specified in the KEY_INIT section.

createHelperMap

protected Map<Object,ElementHelper> createHelperMap(String props)

Converts a comma-separted list of property files into a mapping of ElementHelpers to keys queried from the helpers by asking their property named according to the second argument. A warning is issued if two identical mappings exist, in which case only the later on is kept. Note that this method can only work correctly if the value of the ID-field is already set after initialization, i.e. it must be specified in the KEY_INIT section.