things.data
Class ThingsPropertyReaderToolkit

java.lang.Object
  things.data.ThingsPropertyReaderToolkit

All Implemented Interfaces:

ThingsProperty

public class ThingsPropertyReaderToolkit
extends java.lang.Object
implements ThingsProperty

A grab bag of static property utilities as well as a view utility object class. These will define how the properties are parsed and presented.

Property lists are comma delimited. Whitespace is preserved.

ENCODING: Escape with ?. Separate multivalues with ,. The , may be escaped with ?. The = indicates equality. It may be escaped with the ?.

Version:

1.0

Version History

EPG - Partially adapted from another project - 22 NOV 04
 

Author:

Erich P. Gatejen

Nested Class Summary

static class

ThingsPropertyReaderToolkit.Validations The supported validations.

Field Summary

Fields inherited from interface things.data.ThingsProperty

PROPERTY_COMMENT_CHARACTER, PROPERTY_CR, PROPERTY_EMPTY, PROPERTY_ESCAPE_CHARACTER, PROPERTY_ESCAPED_CR, PROPERTY_ESCAPED_LF, PROPERTY_LF, PROPERTY_LINE_CONTINUATION, PROPERTY_LINE_CONTINUATION_STRING, PROPERTY_LINE_EQUALITY, PROPERTY_LINE_SEPARATOR, PROPERTY_LINE_SEPARATOR_ASSTRING, PROPERTY_LINE_TERMINATION, PROPERTY_PATH_SEPARATOR

Constructor Summary

ThingsPropertyReaderToolkit()
Default constructor.

ThingsPropertyReaderToolkit(ThingsPropertyTree propertyTree)
Constructor.

ThingsPropertyReaderToolkit(ThingsPropertyViewReader propertyViewReader)
Constructor.

Method Summary

static java.lang.String[]	decodeString(java.lang.String value) Decode the string.
static java.lang.String	encodeString(java.lang.String... values) Encode a string of values and return as a new string.
static java.lang.String	encodeString(java.lang.String value) Encode a string and return as a new string.
static void	encodeString(java.io.Writer out, java.lang.String... values) Encode a string of values to a writer.
static void	encodeString(java.io.Writer out, java.lang.String value) Encode a single string to a writer.
static java.lang.String	fixPath(java.lang.String root, java.lang.String offset) Fix the path to the root.
java.lang.String	getDefaulted(java.lang.String path, java.lang.String defaultValue) Get a optional property.
java.lang.String	getOptional(java.lang.String... path) Get a optional property.
java.lang.String	getOptional(java.lang.String path) Get a optional property.
java.lang.String[]	getOptionalAsMulti(java.lang.String... path) Get a optional property as a multi-value.
java.lang.String[]	getOptionalAsMulti(java.lang.String path) Get a optional property as a multi-value.
java.lang.String	getOptionalSingle(java.lang.String... path) Get a optional property.
java.lang.String	getOptionalSingle(java.lang.String path) Get a optional property.
boolean	getOptionalTruth(java.lang.String... path) Get a optional property and evaluate it for truth.
java.lang.String[]	getOrderedNumberedPly(java.lang.String... path) This will create an ordered list of property names from a ply that consists entirely of numeric entries.
java.lang.String	getRequired(java.util.Collection<ThingsPropertyReaderToolkit.Validations> requestedValidations, java.lang.String... path) Get a required property.
java.lang.String	getRequired(java.lang.String... path) Get a required property.
java.lang.String	getRequired(java.lang.String path) Get a required property.
java.lang.String	getRequired(java.lang.String path, ThingsPropertyReaderToolkit.Validations... requestedValidations) Get a required property.
java.lang.String[]	getRequiredAsMulti(java.lang.String... path) Get a required property as a multi-value.
java.lang.String[]	getRequiredAsMulti(java.lang.String path) Get a required property as a multi-value.
int	getRequiredInteger(java.lang.String... path) Get a required property and evaluate it as an integer.
int	getRequiredInteger(java.lang.String path) Get a required property and evaluate it as an integer.
java.lang.String	getRequiredSingle(java.util.Collection<ThingsPropertyReaderToolkit.Validations> requestedValidations, java.lang.String... path) Get a required property.
java.lang.String	getRequiredSingle(java.lang.String... path) Get a required property.
java.lang.String	getRequiredSingle(java.lang.String path) Get a required property.
java.lang.String	getRequiredSingle(java.lang.String path, ThingsPropertyReaderToolkit.Validations... requestedValidations) Get a required property.
boolean	getRequiredTruth(java.lang.String... path) Get a required property and evaluate it for truth.
ThingsPropertyViewReader	getView() Get the property view reader.
static java.lang.String	path(java.lang.String... items) Build a path.
static java.util.ListIterator<java.lang.String>	propertyList(java.lang.String property) It will take a single property and treat it as a list.
void	validate(java.lang.String target, java.lang.String name, java.util.Collection<ThingsPropertyReaderToolkit.Validations> requestedValidations) Validate.
void	validate(java.lang.String target, java.lang.String name, ThingsPropertyReaderToolkit.Validations... requestedValidations) Validate.
int	validateInt(java.lang.String target, java.lang.String name) Validate integer.
long	validateLong(java.lang.String target, java.lang.String name) Validate long.
static void	validatePath(java.lang.String path) Validate the path.
static void	validateValue(java.lang.String value) Validate a value.
static void	validateValues(java.lang.String[] values) Validate a values.

Methods inherited from class java.lang.Object

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

Constructor Detail

ThingsPropertyReaderToolkit

public ThingsPropertyReaderToolkit()
                            throws ThingsException

Default constructor. DO NOT CALL THIS! It is not valid.

Throws:

ThingsException

ThingsPropertyReaderToolkit

public ThingsPropertyReaderToolkit(ThingsPropertyViewReader propertyViewReader)
                            throws ThingsException

Constructor. Create the toolkit.

Parameters:

propertyViewReader - The view reader to use.

Throws:

ThingsException

ThingsPropertyReaderToolkit

public ThingsPropertyReaderToolkit(ThingsPropertyTree propertyTree)
                            throws ThingsException

Constructor. Create the toolkit.

Parameters:

propertyTree - The tree to use.

Throws:

ThingsException

Method Detail

getRequired

public java.lang.String getRequired(java.lang.String path)
                             throws ThingsException

Get a required property. If the property does not exist, it will throw an exception.

Parameters:

path - the property name

Returns:

value of the property

Throws:

ThingsException

getRequired

public java.lang.String getRequired(java.lang.String... path)
                             throws ThingsException

Get a required property. If the property does not exist, it will throw an exception.

Parameters:

path - pieces of the path.

Returns:

value of the property

Throws:

ThingsException

getRequiredTruth

public boolean getRequiredTruth(java.lang.String... path)
                         throws ThingsException

Get a required property and evaluate it for truth. If the property does not exist, it will throw an exception.

Parameters:

path - pieces of the path.

Returns:

true if it appears true (according to the Plato tool), otherwise false.

Throws:

ThingsException

See Also:

Plato

getRequiredInteger

public int getRequiredInteger(java.lang.String path)
                       throws ThingsException

Get a required property and evaluate it as an integer. If the property does not exist or it is not an integer, it will throw an exception.

Parameters:

path - the property name

Returns:

the integer value

Throws:

ThingsException

See Also:

Plato

getRequiredInteger

public int getRequiredInteger(java.lang.String... path)
                       throws ThingsException

Get a required property and evaluate it as an integer. If the property does not exist or it is not an integer, it will throw an exception.

Parameters:

path - pieces of the path.

Returns:

the integer value

Throws:

ThingsException

See Also:

Plato

getRequired

public java.lang.String getRequired(java.lang.String path,
                                    ThingsPropertyReaderToolkit.Validations... requestedValidations)
                             throws ThingsException

Get a required property. If the property does not exist, it will throw an exception. Check for requests validations. If any validations fail, it will throw an exception with code DATA_ERROR_PROPERTY_FAILED_VALIDATION.

Parameters:

path - the property name

requestedValidations - The requested validations

Returns:

value of the property

Throws:

ThingsException

getRequired

public java.lang.String getRequired(java.util.Collection<ThingsPropertyReaderToolkit.Validations> requestedValidations,
                                    java.lang.String... path)
                             throws ThingsException

Get a required property. If the property does not exist, it will throw an exception. Check for requests validations. If any validations fail, it will throw an exception with code DATA_ERROR_PROPERTY_FAILED_VALIDATION.

Parameters:

path - pieces of the path.

requestedValidations - The requested validations

Returns:

value of the property

Throws:

ThingsException

getRequiredSingle

public java.lang.String getRequiredSingle(java.lang.String path)
                                   throws ThingsException

Get a required property. It must be a single value. If the property does not exist, it will throw an exception.

Parameters:

path - the property name

Returns:

value of the property

Throws:

ThingsException

getRequiredSingle

public java.lang.String getRequiredSingle(java.lang.String... path)
                                   throws ThingsException

Get a required property. It must be a single value. If the property does not exist, it will throw an exception.

Parameters:

path - pieces of the path.

Returns:

value of the property

Throws:

ThingsException

getRequiredSingle

public java.lang.String getRequiredSingle(java.lang.String path,
                                          ThingsPropertyReaderToolkit.Validations... requestedValidations)
                                   throws ThingsException

Get a required property. It must be a single value. If the property does not exist, it will throw an exception. Check for requests validations. If any validations fail, it will throw an exception with code DATA_ERROR_PROPERTY_FAILED_VALIDATION.

Parameters:

path - the property name

requestedValidations - The requested validations

Returns:

value of the property

Throws:

ThingsException

getRequiredSingle

public java.lang.String getRequiredSingle(java.util.Collection<ThingsPropertyReaderToolkit.Validations> requestedValidations,
                                          java.lang.String... path)
                                   throws ThingsException

Get a required property. If the property does not exist, it will throw an exception. Check for requests validations. If any validations fail, it will throw an exception with code DATA_ERROR_PROPERTY_FAILED_VALIDATION.

Parameters:

path - pieces of the path.

requestedValidations - The requested validations

Returns:

value of the property

Throws:

ThingsException

getRequiredAsMulti

public java.lang.String[] getRequiredAsMulti(java.lang.String path)
                                      throws ThingsException

Get a required property as a multi-value. If the property does not exist, it will throw an exception.

Parameters:

path - the property name

Returns:

value of the property

Throws:

ThingsException

getRequiredAsMulti

public java.lang.String[] getRequiredAsMulti(java.lang.String... path)
                                      throws ThingsException

Get a required property as a multi-value. If the property does not exist, it will throw an exception.

Parameters:

path - pieces of the path.

Returns:

value of the property

Throws:

ThingsException

getOptional

public java.lang.String getOptional(java.lang.String path)
                             throws ThingsException

Get a optional property. If the property does not exist, it will return a null.

Parameters:

path - the property name

Returns:

value of the property

Throws:

ThingsException

getDefaulted

public java.lang.String getDefaulted(java.lang.String path,
                                     java.lang.String defaultValue)

Get a optional property. If the property does not exist or is empty, return the default value. It will never throw an exception. Any problem will yield the default value.

Parameters:

path - the property name

defaultValue - the default value.

Returns:

value of the property

getOptional

public java.lang.String getOptional(java.lang.String... path)
                             throws ThingsException

Get a optional property. If the property does not exist, it will return a null.

Parameters:

path - pieces of the path.

Returns:

value of the property

Throws:

ThingsException

getOptionalTruth

public boolean getOptionalTruth(java.lang.String... path)
                         throws ThingsException

Get a optional property and evaluate it for truth. If the property does not exist, it will return false.

Parameters:

path - pieces of the path.

Returns:

true if it appears true (according to the Plato tool), otherwise false.

Throws:

ThingsException

See Also:

Plato

getOptionalSingle

public java.lang.String getOptionalSingle(java.lang.String path)
                                   throws ThingsException

Get a optional property. It must be a single value. If the property does not exist, it will return a null.

Parameters:

path - the property name

Returns:

value of the property

Throws:

ThingsException

getOptionalSingle

public java.lang.String getOptionalSingle(java.lang.String... path)
                                   throws ThingsException

Get a optional property. It must be a single value. If the property does not exist, it will return a null.

Parameters:

path - pieces of the path.

Returns:

value of the property

Throws:

ThingsException

getOptionalAsMulti

public java.lang.String[] getOptionalAsMulti(java.lang.String path)
                                      throws ThingsException

Get a optional property as a multi-value. If the property does not exist, it will return a null.

Parameters:

path - the property name

Returns:

value of the property

Throws:

ThingsException

getOptionalAsMulti

public java.lang.String[] getOptionalAsMulti(java.lang.String... path)
                                      throws ThingsException

Get a optional property as a multi-value. If the property does not exist, it will return a null.

Parameters:

path - pieces of the path.

Returns:

value of the property

Throws:

ThingsException

getView

public ThingsPropertyViewReader getView()

Get the property view reader.

Returns:

The property view

See Also:

ThingsPropertyViewReader

getOrderedNumberedPly

public java.lang.String[] getOrderedNumberedPly(java.lang.String... path)
                                         throws ThingsException

This will create an ordered list of property names from a ply that consists entirely of numeric entries. Anything other than numerics (integer) will cause an exception.

Parameters:

path - to the ply

Returns:

array of property names at the ply.

Throws:

ThingsException

validatePath

public static void validatePath(java.lang.String path)
                         throws ThingsException

Validate the path. It will throw an Error level exception if it is bad.

Throws:

ThingsException

validateValue

public static void validateValue(java.lang.String value)
                          throws ThingsException

Validate a value. It will throw an Error level exception if it is bad.

Throws:

ThingsException

validateValues

public static void validateValues(java.lang.String[] values)
                           throws ThingsException

Validate a values. It will throw an Error level exception if it is bad.

Throws:

ThingsException

fixPath

public static java.lang.String fixPath(java.lang.String root,
                                       java.lang.String offset)
                                throws ThingsException

Fix the path to the root.

Parameters:

root - the root offset. You can use null.

offset - the offset from root.

Returns:

the fixed path.

Throws:

ThingsException

path

public static java.lang.String path(java.lang.String... items)

Build a path. If it can't build anything, it'll return a null.

Parameters:

items - the strings to build.

Returns:

a full path.

decodeString

public static java.lang.String[] decodeString(java.lang.String value)
                                       throws ThingsException

Decode the string.

Parameters:

value - The string to decode.

Returns:

An array of values.

Throws:

ThingsException - Null or bad strings will cause exceptions.

encodeString

public static java.lang.String encodeString(java.lang.String... values)
                                     throws ThingsException

Encode a string of values and return as a new string.

Parameters:

values - The strings to encode.

Returns:

the String.

Throws:

ThingsException - Null or bad strings will cause exceptions.

encodeString

public static java.lang.String encodeString(java.lang.String value)
                                     throws ThingsException

Encode a string and return as a new string.

Parameters:

value - The string to encode.

Returns:

the String.

Throws:

ThingsException - Null or bad strings will cause exceptions.

encodeString

public static void encodeString(java.io.Writer out,
                                java.lang.String... values)
                         throws ThingsException

Encode a string of values to a writer.

Parameters:

values - The strings to encode.

out - The target writer.

Throws:

ThingsException - Null or bad strings will cause exceptions.

encodeString

public static void encodeString(java.io.Writer out,
                                java.lang.String value)
                         throws java.lang.Throwable

Encode a single string to a writer.

Parameters:

value - The string to encode.

out - The target writer.

Throws:

java.lang.Throwable - Null or bad strings will cause exceptions.

validate

public void validate(java.lang.String target,
                     java.lang.String name,
                     java.util.Collection<ThingsPropertyReaderToolkit.Validations> requestedValidations)
              throws ThingsException

Validate. It will throw an exception with any problem.

This is a kludge with the toArray. Bleh. No time.

Parameters:

target - The string to check.

name - Property name (used for error reporting, if necessary).

requestedValidations - All the validations as a collection. Remember, NOT_NULL is assumed.

Throws:

ThingsException - with code DATA_ERROR_PROPERTY_FAILED_VALIDATION if any validation fails.

validate

public void validate(java.lang.String target,
                     java.lang.String name,
                     ThingsPropertyReaderToolkit.Validations... requestedValidations)
              throws ThingsException

Validate. It will throw an exception with any problem.

Parameters:

target - The string to check.

name - Property name (used for error reporting, if necessary).

requestedValidations - All the validations. Remember, NOT_NULL is assumed.

Throws:

ThingsException - with code DATA_ERROR_PROPERTY_FAILED_VALIDATION if any validation fails.

validateInt

public int validateInt(java.lang.String target,
                       java.lang.String name)
                throws ThingsException

Validate integer. Make sure the target comes out as a good integer.

Parameters:

target - The string to check.

name - property name for error reporting purposes.

Returns:

the value if it works out ok..

Throws:

ThingsException - with code DATA_ERROR_PROPERTY_FAILED_VALIDATION if any validation fails.

validateLong

public long validateLong(java.lang.String target,
                         java.lang.String name)
                  throws ThingsException

Validate long. Make sure the target comes out as a good long.

Parameters:

target - The string to check.

name - property name for error reporting purposes.

Returns:

the value if it works out ok..

Throws:

ThingsException - with code DATA_ERROR_PROPERTY_FAILED_VALIDATION if any validation fails.

propertyList

public static java.util.ListIterator<java.lang.String> propertyList(java.lang.String property)

It will take a single property and treat it as a list. it will return a ListIterator for the list. If the property is null or empty, it will return an empty list.

Returns:

a ListIterator to a list of Strings