# Package org.modeshape.jcr.value

Nodes in a graph contain properties, and this package defines the interfaces, classes and exceptions for representing and working with properties and their values.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  BinaryFactory | A factory for creating `BinaryValue` instances.
  BinaryValue | Value holder for binary data.
  DateTimeFactory | A factory for creating `date-time instants`.
  Location |
  Name | A qualified name consisting of a namespace and a local name.
  NameFactory | A factory for creating `names`.
  NameFactory.Holder |
  NamespaceRegistry | Registry of namespaces, which are used to provide isolated and independent domains for `names`.
  NamespaceRegistry.Holder |
  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).
  Property.ValueTypeTransformer<T> | Interface which allows the conversion of a property value to a given type.
  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`.
  StringFactory |
  UriFactory |
  ValueFactories | The set of standard `ValueFactory` instances.
  ValueFactory<T> | A factory for `Property` values.

- Class Summary
  Class | Description
  --- | ---
  BinaryKey | The internal key used to identify a unique BINARY value.
  PropertyType.ClassBasedTypeChecker |
  PropertyType.DateCanonicalizer |
  PropertyType.DoubleCanonicalizer |
  PropertyType.LongCanonicalizer |
  PropertyType.ObjectCanonicalizer |
  ValueComparators | A set of `Comparator` objects for the different kinds of property values.
  ValueComparators.BinaryValueComparator |
  ValueComparators.BooleanComparator |
  ValueComparators.CalendarComparator |
  ValueComparators.DateComparator |
  ValueComparators.DateTimeComparator |
  ValueComparators.DecimalComparator |
  ValueComparators.DoubleComparator |
  ValueComparators.LongComparator |
  ValueComparators.NameComparator |
  ValueComparators.ObjectComparator |
  ValueComparators.PathComparator |
  ValueComparators.PathSegmentComparator |
  ValueComparators.PathSegmentNameComparator |
  ValueComparators.ReferenceComparator |
  ValueComparators.StringComparator |
  ValueComparators.UriComparator |
  ValueComparators.UuidComparator |
  ValueTypeSystem |
  ValueTypeSystem.NodeKeyTypeFactory |
  WorkspaceAndPath | A path within a given workspace.

- Enum Summary
  Enum | Description
  --- | ---
  PropertyType | The data types for property values.

- Exception Summary
  Exception | Description
  --- | ---
  InvalidPathException | A runtime exception that represents that an invalid `path` 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.
  ValueFormatException | A runtime exception denoting that a value could not be converted to a specific type because of the value's format.

## Package org.modeshape.jcr.value Description

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 `BinaryValue` 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.
- `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`.

### Creating and converting property values

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`, `BinaryValue`, 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.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 `BinaryValue` 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` and `NameFactory`,

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.

### Comparing property values

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()`).

Copyright © 2008-2014 JBoss, a division of Red Hat. All Rights Reserved.