things.data
Class ThingsPropertyReaderToolkit

java.lang.Object
  extended by 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


Things.