com.pholser.util.properties
Class PropertyBinder<T>

java.lang.Object
  com.pholser.util.properties.PropertyBinder<T>

Type Parameters:

T - the type of accessor proxies the binder is to create

public class PropertyBinder<T>
extends Object

Creates proxies that provide typed access to values in sources of property configuration via the PICA technique.

Inspired by this blog entry.

The Class given to a binder at construction time should be an interface with no super-interfaces. It is referred to as a schema. A schema's methods prescribe the keys of a source of property configuration and the intended types of their associated values. Binding a source of property configuration to the schema gives the caller a proxy that implements the schema's interface. Invoking a proxy method attempts to retrieve the property value associated with the key prescribed by the invoked method, and to convert the value to the type prescribed by the method's return value.

Every schema method maps to a property key. A method can be marked with BoundProperty to indicate the property key to be used when the method is invoked; if it is not so marked, the key used is: fully qualified name of the schema interface + '.' + the method's name.

Prior to version 3, binders accepted only Properties and Maps of string keys to string values. Beginning with version 3, binders admit sources of property configuration that map string keys to values of unknown type. If a given value in such a source happens to be a string, that value will undergo conversion to the method's return type if possible. Any problems with such a conversion will result in runtime type errors.

In order for a given property value to be converted from a string, the associated schema method should have a return type that is a value type, an array of value types, or a List of value types. A value type is any primitive type, primitive wrapper type, or type which possesses either:

• a public static method called valueOf which takes one argument, of type String, and whose return type is the type itself
• a public constructor which takes one argument, of type String

If a value type has both of these, the valueOf method takes priority over the constructor. Note that enums have a valueOf method.

The ValuesSeparatedBy annotation can be applied only to schema methods with an aggregate return type, and must specify a well-formed regular expression as a separator.

If a schema method specifies a default value via DefaultsTo, that value must be convertible to the return type of the schema method via the above rules.

If a schema method accepts no arguments, the property's value will be converted via the above rules. If the schema method accepts one or more arguments, the property's value is treated as a format string, and the arguments assigned to the format specifiers accordingly, before the entire value is converted. If the property's value is not a string, any arguments to the schema method are ignored.

Schema methods returning Date can be annotated with ParsedAs to indicate that the corresponding property's value(s) should be parsed using the given date patterns.

After binding, invoking a schema method returns the value of the property it represents if that property is present; else the value given by the method's DefaultsTo marker if present; else null for scalar types, a zero-length array for array types, and an empty list for list types. If the schema method returns a primitive type and neither a property nor its default is present, the method will raise NullPointerException.

Author:

Paul Holser

Constructor Summary

PropertyBinder(Class<T> schema)
Creates a new property binder from the given schema.

Method Summary

T	bind(File propertiesFile) Makes a new proxy bound to the properties purported to be in the given file.
T	bind(InputStream propertyInput) Makes a new proxy bound to the properties purported to be in the given input stream.
T	bind(Map<String,?> properties) Makes a new proxy bound to the properties in the given map.
T	bind(Properties properties) Makes a new proxy bound to the given properties.
T	bind(PropertySource source) Makes a new proxy bound to the properties represented by the given property source.
T	bind(ResourceBundle bundle) Makes a new proxy bound to the properties in the given resource bundle.
static <U> PropertyBinder<U>	forType(Class<U> schema) Factory method for property binders.
static SystemProperties	getSystemProperties() Makes a new proxy bound to a snapshot of the current system properties.

Methods inherited from class java.lang.Object

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

Constructor Detail

PropertyBinder

public PropertyBinder(Class<T> schema)

Creates a new property binder from the given schema.

Parameters:

schema - the type used to create and configure accessor proxies

Throws:

NullPointerException - if schema is null

IllegalArgumentException - if schema's configuration is invalid in any way

Method Detail

forType

public static <U> PropertyBinder<U> forType(Class<U> schema)

Factory method for property binders. Leverages generics type inference so that if you don't wish to specify the type more than once at construction time, you can call this method instead (at the expense of not offering a seam for testing).

Type Parameters:

U - the type of accessor proxies the binder is to create

Parameters:

schema - the type used to create and configure accessor proxies

Returns:

a new property binder that binds proxies to sources of property configuration

Throws:

NullPointerException - if schema is null

IllegalArgumentException - if schema's configuration is invalid in any way

bind

public T bind(InputStream propertyInput)
       throws IOException

Makes a new proxy bound to the properties purported to be in the given input stream.

Parameters:

propertyInput - an input stream containing properties to be bound

Returns:

a proxy bound to the properties

Throws:

IOException - if there is a problem reading from the input stream

NullPointerException - if propertyInput is null

See Also:

bind(File)

bind

public T bind(File propertiesFile)
       throws IOException

Makes a new proxy bound to the properties purported to be in the given file.

Parameters:

propertiesFile - a file containing properties to be bound

Returns:

a proxy bound to the properties

Throws:

IOException - if there is a problem reading from the file

NullPointerException - if propertiesFile is null

See Also:

bind(InputStream)

bind

public T bind(Properties properties)

Makes a new proxy bound to the given properties. If, after binding, the caller alters the contents of the properties object via her reference to it, the properties that the proxy refers to are affected.

Parameters:

properties - the properties to be bound

Returns:

a proxy bound to the properties

bind

public T bind(Map<String,?> properties)

Makes a new proxy bound to the properties in the given map. If, after binding, the caller alters the contents of the map via her reference to it, the properties that the proxy refers to are affected.

Parameters:

properties - the properties to be bound

Returns:

a proxy bound to the properties

Throws:

NullPointerException - if properties is null

bind

public T bind(ResourceBundle bundle)

Makes a new proxy bound to the properties in the given resource bundle. If, after binding, the caller alters the contents of the resource bundle, the properties that the proxy refers to are affected.

Parameters:

bundle - the bundle to be bound

Returns:

a proxy bound to the bundle

Throws:

NullPointerException - if bundle is null

bind

public T bind(PropertySource source)

Makes a new proxy bound to the properties represented by the given property source. If, after binding, the caller affects the responses the property source gives, the properties that the schema refers to are affected.

Parameters:

source - the property source to be bound

Returns:

a proxy bound to the property source

Throws:

NullPointerException - if source is null

getSystemProperties

public static SystemProperties getSystemProperties()

Makes a new proxy bound to a snapshot of the current system properties.

Returns:

a proxy bound to system properties