burst.props.AbstractProperties Class Reference

Inheritance diagram for burst.props.AbstractProperties:

List of all members.

---

Detailed Description

Abstract base class for anything that can hold named values.

Possible such sources of values are:

• a URL query string
• a DOM node's attributes
• an ECMAScript object acting as an associative array

There are many antecedants for such an interface. Java alone seems to include yet another similar interface in every release (java.util.Properties, java.util.prefs, javax.naming, etc.)

This interface has several deliberate decisions reflected in it:

• It is a mapping from String names to String values. This differs from JNDI, which can lookup Object values.

• The getProperty() function is guaranteed to either return a non-empty trimmed String, or undefined. It should never return null, '', or an all-white string. This differs from some other systems that do not provide trimming guarantees, or that attempt to distinguish an empty value from no value.

• It supports a naming hierarchy, but only a very simple one. A getSubProperty(prefix, name) just does a getProperty(prefix + '.' + name) (at least if the base class is not overridden).

• We do not mandate an iterator ability.

• Unless otherwise specified, name lookup is always case-sensitive.

This class is designed to work with burst.reflect.PropertyDef, which can be used to convert a String value from a AbstractProperties instance into some Object value. It is possible to also use a AbstractProperties without burst.reflect.PropertyDef.

Public Member Functions
	AbstractProperties (String implicit_prefix)
	protected constructor, only for use by subclasses.
String	getProperty (String name)
	Given a property name, returns either a non-empty trimmed String, or undefined.
String	getSubProperty (String prefix, String name)
	Same as getProperty(prefix + '.' + name) .
Object	getValue (burst.reflect.PropertyDef propdef, Object dflt)
	A convenience to lookup a property string and parse it in one step.
Object	getSubValue (String prefix, burst.reflect.PropertyDef propdef, Object dflt)
	Like getValue, but uses getSubProperty.
Boolean	setObjectValue (Object obj, burst.reflect.PropertyDef propdef, String prefix)
	Convenience to set a member of some object from this burst.props.AbstractProperties source.
Object	setObjectValues (Object obj, Array propdefs, String prefix, Boolean do_defaults, Boolean do_mandatory)
	Calls setObjectValue for each of the burst.reflect.PropertyDef in the Array.
abstract String	getPropertyImpl (String name)
	must be overridden by subclass.

---

Constructor & Destructor Documentation

burst.props.AbstractProperties.AbstractProperties (  String  implicit_prefix  )

protected constructor, only for use by subclasses. If an implicit_prefix is specified, then all names looked up via getPropertyImpl must have that prefix removed, and any name not starting with that prefix are not in this instance. If specified, this must typically have a trailing '.' in it. Parameters: implicit_prefix  Optional. If specified, the implicit prefix.

---

Member Function Documentation

abstract String burst.props.AbstractProperties.getPropertyImpl (  String  name  )  [pure virtual]

must be overridden by subclass. Need not worry about trimming etc, as getProperty does that.

Object burst.props.AbstractProperties.getValue (  burst.reflect.PropertyDef  propdef, Object  dflt )

A convenience to lookup a property string and parse it in one step. First calls str = getProperty(propdef.name). Then it returns propdef.parse(str, dflt). Parameters: propdef  The property definition dflt  optional, defaults to undefined. Returns: Same as burst.reflect.PropertyDef.parse Exceptions: burst.props.PropertyError

Boolean burst.props.AbstractProperties.setObjectValue (  Object  obj, burst.reflect.PropertyDef  propdef, String  prefix )

Convenience to set a member of some object from this burst.props.AbstractProperties source. If the property is already defined in the destination object, then nothing is done and false is returned. Otherwise getValue(propdef) is called. If it returns undefined, nothing is done, and false is returned. Else obj[name] is set to the result, and true is returned. Note that no defaulting is done with this function, either from a passed in default value, or a static default from propdef. Parameters: obj  The object to set values in. propdef  The burst.reflect.PropertyDef defining the property in question. prefix  Optional. If specified, getSubValue is used instead of getValue. Returns: true if a value was set. Exceptions: burst.props.PropertyError  If the property string is not valid.

Object burst.props.AbstractProperties.setObjectValues (  Object  obj, Array  propdefs, String  prefix, Boolean  do_defaults, Boolean  do_mandatory )

Calls setObjectValue for each of the burst.reflect.PropertyDef in the Array. Optionally, as a convenience, this function can also set any static defaults (suitable if there are no more sources for dynamic values), and/or can validate that the object has values for all mandatory properties. If prefix is specified, it is prepended to each property name in propdefs prior looking up in this burst.props.AbstractProperties instance. Note that the prefix is not used when setting values Parameters: obj  The object to set. propdefs  The Array of burst.reflect.PropertyDef instances prefix  The prefix to use in front of each property name before looking up each value. do_defaults  optional. If true, also call burst.reflect.PropertyDef.setDefaultEach do_mandatory  optioal. If true, also call burst.reflect.PropertyDef.checkMandatoryEach Returns: the obj argument Exceptions: burst.props.PropertyError  If any property string used is not valid.

---

The documentation for this class was generated from the following file:

• props/AbstractProperties.java

---