|
||||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | |||||||||
See:
Description
| Interface Summary | |
|---|---|
| Binary | Value holder for binary data. |
| BinaryFactory | A factory for creating Binary instances. |
| DateTime | An immutable date-time class that represents an instance in time. |
| DateTimeFactory | A factory for creating date-time instants. |
| Name | A qualified name consisting of a namespace and a local name. |
| NameFactory | A factory for creating names. |
| NamespaceRegistry | Registry of namespaces, which are used to provide isolated and independent domains for names. |
| NamespaceRegistry.Namespace | Representation of a single namespace at a single point in time. |
| Path | An object representation of a node path within a repository. |
| Path.Segment | Representation of the segments that occur within a path. |
| PathFactory | A factory for creating paths. |
| Property | Representation of a property consisting of a name and value(s). |
| PropertyFactory | A factory for creating Property objects. |
| Readable | An interface defining methods to obtain a "readable" string representation. |
| Reference | A representation of a reference to another node. |
| ReferenceFactory | A factory for creating references. |
| UuidFactory | A factory for creating UUID instances. |
| ValueFactories | The set of standard ValueFactory instances. |
| ValueFactory<T> | A factory for Property values. |
| Class Summary | |
|---|---|
| PathExpression | An expression that defines an acceptable path using a regular-expression-like language. |
| PathExpression.Matcher | |
| PathExpression.RepositoryPath | |
| PropertyType.ClassBasedTypeChecker | |
| PropertyType.DoubleCanonicalizer | |
| PropertyType.LongCanonicalizer | |
| PropertyType.ObjectCanonicalizer | |
| PropertyType.StrongReferenceTypeChecker | |
| PropertyType.WeakReferenceTypeChecker | |
| ValueComparators | A set of Comparator objects for the different kinds of property values. |
| ValueTypeSystem | |
| Enum Summary | |
|---|---|
| PropertyType | The data types for property values. |
| Exception Summary | |
|---|---|
| InvalidPathException | A runtime exception that represents that an invalid path was specified. |
| InvalidPathExpressionException | A runtime exception that represents that an invalid path expression was specified. |
| IoException | A runtime exception that represents that an error occurred during input/output. |
| NamespaceException | A runtime exception denoting that a namespace was invalid or not found. |
| PathNotFoundException | A runtime exception denoting that a node or property at a supplied path was not found. |
| ReferentialIntegrityException | A runtime exception denoting that an operation could not be performed because it would leave references in an invalid state. |
| ValueFormatException | A runtime exception denoting that a value could not be converted to a specific type because of the value's format. |
Nodes in a graph contain properties, and this package defines the interfaces, classes and exceptions for representing and working with properties and their values.
A property consists of a name and a set of values. A property name is represented
by Name, and is defined as a local name in a namespace.
Property values can be of any type, although there are specific interfaces for the known types:
String - A value represented with instances of the standard String class.Binary - A value represented with instances of the Binary interface.Long - A value represented with instances of the standard Long class.Double - A value represented with instances of the standard Double class.Decimal - A value represented with instances of the standard BigDecimal class.Date - A value represented with instances of the DateTime interface.
This interface hides the mishmash of Java date representations, and is designed to follow the anticipated
ZonedDateTime that is part of JSR-310.Boolean - A value represented with instances of the standard Boolean class.Name - A value represented with instances of the Name interface.Path - A value represented with instances of the Path interface.UUID - A value represented with instances of the standard UUID class.Reference - A value represented with instances of the Reference interface.URI - A value represented with instances of the standard URI class.Object - A value represented with instances of any class, although the class
should in all practicality implement Serializable.
The design of properties and their values was centered around one key principle: when using a property value,
you often don't care what type the property value actually is, but instead care about converting it to a
property type that you know how to work with. For example, you may be working with a property that represents
a date, and you want to work with the value as a DateTime object, regardless of whether the values
are actually String, DateTime, Binary, or even Calendar or Date
instances. You know its should be a date, so you want to get a value that behaves as a date.
This notion of working with a desired type implies the ability to convert from one value type to another.
And in fact, creating values is really just converting from "other" types into a known type.
So, we can use the factory design pattern to have a single concept of a component that creates property values
from a variety of types. But by using generics, we can use a single factory interface
that has the same methods for creating value objects, but make the return type specific to the type we want to create.
The ValueFactory interface is defined as follows:
public interface ValueFactory<T> {
T create( String value ) throws ValueFormatException;
T create( int value ) throws ValueFormatException;
T create( long value ) throws ValueFormatException;
T create( double value ) throws ValueFormatException;
...
T create( java.util.Date value ) throws ValueFormatException;
T create( java.util.Calendar value ) throws ValueFormatException;
T create( DateTime value ) throws ValueFormatException;
...
T create( java.util.UUID value ) throws ValueFormatException;
T create( java.net.URI value ) throws ValueFormatException;
T create( Reference value ) throws ValueFormatException;
T create( Name value ) throws ValueFormatException;
T create( Path value ) throws ValueFormatException;
...
T create( InputStream value, long approximateLength ) throws ValueFormatException;
T create( Reader value, long approximateLength ) throws ValueFormatException;
T create( Binary value ) throws ValueFormatException;
...
T[] create( String[] value ) throws ValueFormatException;
T[] create( int[] value ) throws ValueFormatException;
T[] create( long[] value ) throws ValueFormatException;
T[] create( double[] value ) throws ValueFormatException;
...
}
Notice that all the methods are called create, and most take a single parameter whose type is
one of the known types, a primitive, or a number of "other" types frequently encountered. (The create(...)
methods that take an InputStream or Reader have a second parameter that specifies
the length of the data.) Finally, note that almost all of the create methods have a form that each
take an array of values and return an array of T.
These methods also all throw a ValueFormatException, in case the supplied
parameter cannot be converted to the desired type. In many cases, there is a conversion (e.g., from the String "123"
to an integer), but there certainly are cases where no conversion is allowed (e.g., the String "a123" cannot be converted
to an integer, and a Name cannot be converted to a boolean). All types can be converted
to a string, and all factories support converting that string back to its original form.
The factory for creating DateTime objects would then be an implementation of ValueFactory<DateTime>,
a factory for creating Binary objects would be an implementation of ValueFactory<Binary,
and so on. In some cases, we'd like to add additional forms of create(...) for specific values, and
we can do this by extending a typed ValueFactory. For example, the DateTimeFactory adds
more methods for creating DateTime objects for the current time, current time in UTC, from another time
and an offset, and from individual field values:
public interface DateTimeFactory extends ValueFactories<DateTime> {
DateTime create();
DateTime createUtc();
DateTime create( DateTime original, long offsetInMillis );
DateTime create( int year, int monthOfYear, int dayOfMonth,
int hourOfDay, int minuteOfHour, int secondOfMinute, int millisecondsOfSecond );
DateTime create( int year, int monthOfYear, int dayOfMonth,
int hourOfDay, int minuteOfHour, int secondOfMinute, int millisecondsOfSecond,
int timeZoneOffsetHours );
DateTime create( int year, int monthOfYear, int dayOfMonth,
int hourOfDay, int minuteOfHour, int secondOfMinute, int millisecondsOfSecond,
String timeZoneId );
}
There are specialized factory interfaces for several other types, including PathFactory, NameFactory,
and UuidFactory.
The ValueFactories interface collects all the factories into a single spot:
public interface ValueFactories<T> {
ValueFactory<String> getStringFactory();
ValueFactory<Binary> getBinaryFactory();
ValueFactory<Long> getLongFactory();
ValueFactory<Double> getDoubleFactory();
ValueFactory<BigDecimal> getDecimalFactory();
DateTimeFactory getDateFactory();
ValueFactory<Boolean> getBooleanFactory();
NameFactory getNameFactory();
ValueFactory<Reference> getReferenceFactory();
PathFactory getPathFactory();
ValueFactory<URI> getUriFactory();
UuidFactory getUuidFactory();
ValueFactory<Object> getObjectFactory();
ValueFactory<?> getValueFactory( PropertyType type );
ValueFactory<?> getValueFactory( Object prototype );
}
This allows us to programmatically get the correct factory for a type known at compile time, but also
to obtain the correct factory given a prototype object or the enumeration literal representing
the desired type. Thus, the following code compiles:
ValueFactories factories = ...
DateTime now = factories.getDateFactory.create();
String stringValue = factories.getStringFactory().create(now);
A ValueFactories is provided as part of the ExecutionContext. In this way,
the environment may use a different implementation of one or more factories.
Because we have a mixture of standard Java types and custom interfaces for property values, we need
a set of Comparator implementations that allow us to compare property values.
The ValueComparators class defines a number of singleton comparators that can be used.
Plus, the PropertyType enumeration has the ability to get the comparator
for the specific type (e.g., PropertyType.BINARY.getComparator()).
|
||||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | |||||||||