ElementHelper

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

All Implemented Interfaces:

Cloneable, UserAdjustable, UserDetails, Initializable, PropertySupplying, ResourceSupplying
```
public class ElementHelper
extends PropertyResources
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

Nested Classes
Modifier and Type Class and Description

static class ElementHelper.Valid
Test the validity of an element helper.
- Nested classes/interfaces inherited from class util.PropertyResources
  PropertyResources.Load, PropertyResources.URLResource

Nested Classes
Modifier and Type	Class and Description
`static class`	`ElementHelper.Valid` Test the validity of an element helper.

Field Summary

Fields
Modifier and Type	Field and Description
`private List<BooleanNode>`	`check` The boolean expression parser, initialized at construction.
`private Map<String,String>`	`choices` Variable names to comma-separated choices as strings.
`private Map<String,Object>`	`constants` The mapping of constant names to their values or to null if undefined.
`private Map<String,ExpressionNode>`	`follows` These variables follow from expressions.
`private BuildingHandler`	`handled` If an error handler was assigned to the element helper.
`static String`	`KEY_APPENDIX` The appendix to link a single key to two values.
`static String`	`KEY_CHECKS` After everything is set up and valid, this checks may be performed.
`static String`	`KEY_CHOICES` For these variable names, we have a mapping to possible values.
`static String`	`KEY_FOLLOWFROM` A mapping of variables that follow from others.
`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_LISTMULTIPLY` If this is set, it is the separator for a multiplicative list.
`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 BooleanNode`	`requires` The boolean expression parser, initialized at construction.
`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.PropertyResources
KEY_NOINITONCREATE, POSTFIX_ALPHABET, POSTFIX_BYTES, POSTFIX_DIR, POSTFIX_EXT, POSTFIX_FILE, POSTFIX_LIST, POSTFIX_MODTIME, POSTFIX_URL

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

Constructors
Constructor and Description

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

Constructors
Constructor and Description
`ElementHelper(Map<String,String> prop)` Constructs a new constant helper.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`assignBuildingHandler(BuildingHandler bh)` Assigns a (new) building handler to this element handler.
`private void`	`checkFollow(String name, Object to)`
`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 `ElementHelper`s 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 `ElementHelper`s 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 `ElementHelper`s 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 `ElementHelper`s to keys queried from the helpers by asking their property named according to the second argument.
`void`	`erase()` Sets up the lookup table of constant names to constant values.
`protected void`	`error(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.
`List<Object>`	`getChoices(String name)` If the variable is listed as having possible choices, we return the list of objects it can assume.
`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.
`Map<String,ExpressionNode>`	`getFollows()` Returns all variable names whose value follows from other variables.
`Object`	`getID()` Returns the value of the id-varibale.
`Map<String,Object>`	`getMissing()` Returns a list of names of all constants that are still not set.
`List<String>`	`getMissingRequired()` Tries to infer the variables missing that hinder this element from becoming valid.
`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.
`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.
`private boolean`	`validChecks()`
`private boolean`	`validRequirement()`

Methods inherited from class util.PropertyResources
clone, createFrom, createFrom, createFrom, createInstance, getApplet, getAsResources, getLocate, getPropertiesToKey, getPropertiesToKey, getResource, getResourceAsStream, getResourceFromKey, getResources, hasLocalURLs, initProperties, keyCreate, keyCreate, reload, setApplet

Methods inherited from class util.PropertyContainer
augment, augment, 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, parseObject, reload, removeProperty, requires, 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.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_LISTMULTIPLY
```
public static final String KEY_LISTMULTIPLY
```
    If this is set, it is the separator for a multiplicative list.
    
    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_CHOICES
```
public static final String KEY_CHOICES
```
    For these variable names, we have a mapping to possible values.
    
    See Also:
    
    Constant Field Values
  - KEY_CHECKS
```
public static final String KEY_CHECKS
```
    After everything is set up and valid, this checks may be performed.
    
    See Also:
    
    Constant Field Values
  - KEY_FOLLOWFROM
```
public static final String KEY_FOLLOWFROM
```
    A mapping of variables that follow from others. Name to expression.
    
    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
  - requires
```
private BooleanNode requires
```
    The boolean expression parser, initialized at construction.
  - check
```
private List<BooleanNode> check
```
    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.
  - follows
```
private Map<String,ExpressionNode> follows
```
    These variables follow from expressions.
  - types
```
private Map<String,String> types
```
    The mapping of constant names to their class types.
  - choices
```
private Map<String,String> choices
```
    Variable names to comma-separated choices as strings.
  - settable
```
private List<String> settable
```
    The list of variable names that are settable by the user.
  - handled
```
private BuildingHandler handled
```
    If an error handler was assigned to the element helper.
- 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
  - getFollows
```
public Map<String,ExpressionNode> getFollows()
```
    Returns all variable names whose value follows from other variables. As a convenience, the entire expressions are also carried along.
  - 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
  - validRequirement
```
private boolean validRequirement()
```
    Returns:
  - validChecks
```
private boolean validChecks()
```
    Returns:
  - getMissing
```
public Map<String,Object> getMissing()
```
    Returns a list of names of all constants that are still not set. Note that this is independent 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. If all this variables are set, the element should be valid.
    
    Specified by:
    
    getRequired in interface UserAdjustable
  - getMissingRequired
```
public List<String> getMissingRequired()
```
    Tries to infer the variables missing that hinder this element from becoming valid. We return a join of getMissing() and getRequired() such that variables in both, missing and required, are returned. This might still over-estimate the number of required variables, as an undefined variable, e.g., can be overcome in an OR clause
  - 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
  - getChoices
```
public List<Object> getChoices(String name)
```
    If the variable is listed as having possible choices, we return the list of objects it can assume. The objects are already parsed to correct class types.
    
    Parameters:
    
    name -
    
    Returns:
    
    Alist of possible choices or null, if no choices are specified.
  - 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 previous value of the constant.
  - 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:
    
    True, if val could be assigned
  - checkFollow
```
private void checkFollow(String name,
                         Object to)
```
  - assignBuildingHandler
```
public void assignBuildingHandler(BuildingHandler bh)
```
    Assigns a (new) building handler to this element handler.
    
    Parameters:
    
    bh -
  - error
```
protected void error(String warn)
```
    Issues an error message. This class pipes directly to Syslog.error.
  - 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.

Class ElementHelper

Nested Class Summary

Nested classes/interfaces inherited from class util.PropertyResources

Field Summary

Fields inherited from class util.PropertyResources

Fields inherited from class util.PropertyContainer

Fields inherited from interface util.ResourceSupplying

Fields inherited from interface util.PropertySupplying

Constructor Summary

Method Summary

Methods inherited from class util.PropertyResources

Methods inherited from class util.PropertyContainer

Methods inherited from class java.lang.Object

Methods inherited from interface util.PropertySupplying

Field Detail

KEY_HELPERCLASS

KEY_ID

KEY_TYPEMAP

KEY_LISTMULTIPLY

KEY_SETTABLE

KEY_INIT

KEY_REQUIREMENT

KEY_CHOICES

KEY_CHECKS

KEY_FOLLOWFROM

KEY_VALUEDETAILS

KEY_APPENDIX

requires

check

constants

follows

types

choices

settable

handled

Constructor Detail

ElementHelper

Method Detail

init

getFollows

erase

getID

isValid

validRequirement

validChecks

getMissing

getRequired

getMissingRequired

getDefined

getVariables

getSettable

getDetails

getValue

getChoices

getType

update

setValue

setValue

checkFollow

assignBuildingHandler

error

toString

toLongString

createElementHelper

fromResourceName

fromResourceName

createElementHelpers

createElementHelpers

createHelperMap

createHelperMap