org.modeshape.jcr.value

## Interface ValueFactory<T>

- Type Parameters:
    `T` - the type of value to create
  All Known Subinterfaces:
    BinaryFactory, DateTimeFactory, NameFactory, PathFactory, ReferenceFactory, StringFactory, UriFactory
  All Known Implementing Classes:
    AbstractValueFactory, BinaryStoreValueFactory, BooleanValueFactory, DecimalValueFactory, DoubleValueFactory, JodaDateTimeValueFactory, LongValueFactory, NameValueFactory, NodeIdentifierReferenceFactory, ObjectValueFactory, PathValueFactory, ReferenceValueFactory, StringValueFactory, UriValueFactory

      @ThreadSafe
      public interface ValueFactory<T>

  A factory for `Property` values. Each create method may throw one of these exceptions when attempting to convert a supplied value to the `factory's type`:
  - `IllegalArgumentException` - If the supplied value is invalid in respect to the conversion being attempted.
  - `UnsupportedOperationException` - If a conversion from the supplied value is not supported.
  - `IoException` - If an unexpected problem occurs during the conversion (such as an `IOException`).

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static TextDecoder` | `DEFAULT_DECODER`
    `static TextEncoder` | `DEFAULT_ENCODER`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `T` | `create(BigDecimal value)` Create a value from a decimal.
    `T[]` | `create(BigDecimal[] values)` Create an array of values from an array of decimal values.
    `T` | `create(BinaryValue value)` Create a value from the binary content given by the supplied stream.
    `T[]` | `create(BinaryValue[] values)` Create an array of values from the array of binary objects.
    `T` | `create(boolean value)` Create a boolean from a string.
    `T[]` | `create(boolean[] values)` Create an array of values from an array of booleans.
    `T` | `create(byte[] value)` Create a value from the binary content given by the supplied array.
    `T[]` | `create(byte[][] values)` Create an array of values from the array of binary content.
    `T` | `create(Calendar value)` Create a value from a Calendar instance.
    `T[]` | `create(Calendar[] values)` Create an array of values from an array of Calendar instances.
    `T` | `create(Date value)` Create a value from a date.
    `T[]` | `create(Date[] values)` Create an array of values from an array of dates.
    `T` | `create(DateTime value)` Create a value from a date-time instant.
    `T[]` | `create(DateTime[] values)` Create an array of values from an array of `DateTime` instants.
    `T` | `create(double value)` Create a value from a double.
    `T[]` | `create(double[] values)` Create an array of values from an array of doubles.
    `T` | `create(float value)` Create a value from a float.
    `T[]` | `create(float[] values)` Create an array of values from an array of floats.
    `T` | `create(InputStream stream)` Create a value from the binary content given by the supplied stream.
    `T` | `create(InputStream stream, String hint)` Create a value from the binary content given by the supplied stream with a hint to the BinaryStore for how to store it
    `T` | `create(int value)` Create a value from an integer.
    `T[]` | `create(int[] values)` Create an array of values from an array of integers.
    `Iterable<T>` | `create(Iterable<?> valueIterable)` Create an iterable with the values (of an unknown type).
    `Iterator<T>` | `create(Iterator<?> values)` Create an iterator over the values (of an unknown type).
    `T` | `create(long value)` Create a long from a string.
    `T[]` | `create(long[] values)` Create an array of values from an array of longs.
    `T` | `create(Name value)` Create a value from a name.
    `T[]` | `create(Name[] values)` Create an array of values from an array of names.
    `T` | `create(NodeKey value)` Create a value from a `NodeKey`.
    `T[]` | `create(NodeKey[] value)` Create an array of values from an array of `NodeKey`.
    `T` | `create(Object value)` Create a value from the specified information by determining which other `create` method applies and delegating to that method.
    `T[]` | `create(Object[] values)` Create an array of values from the specified information by determining which other `create` method applies for each object and then delegating to that method.
    `T` | `create(Path.Segment value)` Create a value from a path segment.
    `T` | `create(Path value)` Create a value from a path.
    `T[]` | `create(Path[] values)` Create an array of values from an array of paths.
    `T` | `create(Reference value)` Create a value from a reference.
    `T[]` | `create(Reference[] values)` Create an array of values from an array of references.
    `T` | `create(String value)` Create a value from a string, using no decoding.
    `T[]` | `create(String[] values)` Create an array of values from an array of string values, using no decoding.
    `T[]` | `create(String[] values, TextDecoder decoder)` Create an array of values from an array of strings, using the supplied decoder.
    `T` | `create(String value, TextDecoder decoder)` Create a value from a string, using the supplied decoder.
    `T` | `create(URI value)` Create a value from a URI.
    `T[]` | `create(URI[] values)` Create an array of values from an array of URIs.
    `T` | `create(UUID value)` Create a value from a UUID.
    `T[]` | `create(UUID[] values)` Create an array of values from an array of UUIDs.
    `T[]` | `createEmptyArray(int length)` Creates an empty array of the given type.
    `PropertyType` | `getPropertyType()` Get the `type` of values created by this factory.
    `ValueFactory<T>` | `with(ValueFactories valueFactories)` Return a potentially new copy of this factory that uses the supplied ValueFactories object.

- - ### Field Detail

    - #### DEFAULT_DECODER

          static final TextDecoder DEFAULT_DECODER

    - #### DEFAULT_ENCODER

          static final TextEncoder DEFAULT_ENCODER

  - ### Method Detail

    - #### with

          ValueFactory<T> with(ValueFactories valueFactories)

      Return a potentially new copy of this factory that uses the supplied ValueFactories object.
      Parameters:
        `valueFactories` - the value factories object; may not be null
      Returns:
        the factory, which may be a new instance or may be this object if the supplied value factories is the same as used by this factory; never null

    - #### getPropertyType

          PropertyType getPropertyType()

      Get the `type` of values created by this factory.
      Returns:
        the value type; never null

    - #### create

          T create(String value)
                   throws ValueFormatException

      Create a value from a string, using no decoding.
      Parameters:
        `value` - the string from which the value is to be created
      Returns:
        the value, or null if the supplied string is null
      Throws:
        `ValueFormatException` - if the conversion from a string could not be performed
      See Also:
        `create(String, TextDecoder)`

    - #### create

          T create(String value,
                 TextDecoder decoder)
                   throws ValueFormatException

      Create a value from a string, using the supplied decoder.
      Parameters:
        `value` - the string from which the value is to be created
        `decoder` - the decoder that should be used; if null, the `default decoder` is used
      Returns:
        the value, or null if the supplied string is null
      Throws:
        `ValueFormatException` - if the conversion from a string could not be performed
      See Also:
        `create(String)`

    - #### create

          T create(int value)
                   throws ValueFormatException

      Create a value from an integer.
      Parameters:
        `value` - the integer from which the value is to be created
      Returns:
        the value; never null
      Throws:
        `ValueFormatException` - if the conversion from an integer could not be performed

    - #### create

          T create(long value)
                   throws ValueFormatException

      Create a long from a string.
      Parameters:
        `value` - the string from which the long is to be created
      Returns:
        the value; never null
      Throws:
        `ValueFormatException` - if the conversion from a long could not be performed

    - #### create

          T create(boolean value)
                   throws ValueFormatException

      Create a boolean from a string.
      Parameters:
        `value` - the boolean from which the value is to be created
      Returns:
        the value; never null
      Throws:
        `ValueFormatException` - if the conversion from a boolean could not be performed

    - #### create

          T create(float value)
                   throws ValueFormatException

      Create a value from a float.
      Parameters:
        `value` - the float from which the value is to be created
      Returns:
        the value; never null
      Throws:
        `ValueFormatException` - if the conversion from a float could not be performed

    - #### create

          T create(double value)
                   throws ValueFormatException

      Create a value from a double.
      Parameters:
        `value` - the double from which the value is to be created
      Returns:
        the value; never null
      Throws:
        `ValueFormatException` - if the conversion from a double could not be performed

    - #### create

          T create(BigDecimal value)
                   throws ValueFormatException

      Create a value from a decimal.
      Parameters:
        `value` - the decimal from which the value is to be created
      Returns:
        the value, or null if the supplied decimal is null
      Throws:
        `ValueFormatException` - if the conversion from a decimal could not be performed

    - #### create

          T create(Calendar value)
                   throws ValueFormatException

      Create a value from a Calendar instance.
      Parameters:
        `value` - the Calendar instance from which the value is to be created
      Returns:
        the value, or null if the supplied Calendar is null
      Throws:
        `ValueFormatException` - if the conversion from a Calendar could not be performed

    - #### create

          T create(Date value)
                   throws ValueFormatException

      Create a value from a date.
      Parameters:
        `value` - the date from which the value is to be created
      Returns:
        the value, or null if the supplied date is null
      Throws:
        `ValueFormatException` - if the conversion from a Date could not be performed

    - #### create

          T create(DateTime value)
                   throws ValueFormatException

      Create a value from a date-time instant.
      Parameters:
        `value` - the date-time instant from which the value is to be created
      Returns:
        the value, or null if the supplied date is null
      Throws:
        `ValueFormatException` - if the conversion from a Date could not be performed

    - #### create

          T create(Name value)
                   throws ValueFormatException

      Create a value from a name.
      Parameters:
        `value` - the name from which the value is to be created
      Returns:
        the value, or null if the supplied name is null
      Throws:
        `ValueFormatException` - if the conversion from a name could not be performed

    - #### create

          T create(Path value)
                   throws ValueFormatException

      Create a value from a path.
      Parameters:
        `value` - the path from which the value is to be created
      Returns:
        the value, or null if the supplied path is null
      Throws:
        `ValueFormatException` - if the conversion from a path could not be performed

    - #### create

          T create(Path.Segment value)
                   throws ValueFormatException

      Create a value from a path segment.
      Parameters:
        `value` - the path segment from which the value is to be created
      Returns:
        the value, or null if the supplied path segment is null
      Throws:
        `ValueFormatException` - if the conversion from a path could not be performed

    - #### create

          T create(Reference value)
                   throws ValueFormatException

      Create a value from a reference.
      Parameters:
        `value` - the reference from which the value is to be created
      Returns:
        the value, or null if the supplied reference is null
      Throws:
        `ValueFormatException` - if the conversion from a reference could not be performed

    - #### create

          T create(URI value)
                   throws ValueFormatException

      Create a value from a URI.
      Parameters:
        `value` - the URI from which the value is to be created
      Returns:
        the value, or null if the supplied URI is null
      Throws:
        `ValueFormatException` - if the conversion from a URI could not be performed

    - #### create

          T create(UUID value)
                   throws ValueFormatException

      Create a value from a UUID.
      Parameters:
        `value` - the UUID from which the value is to be created
      Returns:
        the value, or null if the supplied URI is null
      Throws:
        `ValueFormatException` - if the conversion from a UUID could not be performed

    - #### create

          T create(NodeKey value)
                   throws ValueFormatException

      Create a value from a `NodeKey`.
      Parameters:
        `value` - the node key from which the value is to be created
      Returns:
        the value, or null if the supplied URI is null
      Throws:
        `ValueFormatException` - if the conversion from a NodeKey could not be performed

    - #### create

          T create(byte[] value)
                   throws ValueFormatException

      Create a value from the binary content given by the supplied array.
      Parameters:
        `value` - the content to be used to create the value
      Returns:
        the value, or null if the supplied stream is null
      Throws:
        `ValueFormatException` - if the conversion from a byte array could not be performed

    - #### create

          T create(BinaryValue value)
                   throws ValueFormatException,
                          IoException

      Create a value from the binary content given by the supplied stream.
      Parameters:
        `value` - the binary object to be used to create the value
      Returns:
        the value, or null if the supplied stream is null
      Throws:
        `ValueFormatException` - if the conversion from the binary object could not be performed
        `IoException` - If an unexpected problem occurs while accessing the supplied binary value (such as an `IOException`).

    - #### create

          T create(InputStream stream)
                   throws ValueFormatException,
                          IoException

      Create a value from the binary content given by the supplied stream.
      Parameters:
        `stream` - the stream containing the content to be used to create the value
      Returns:
        the value, or null if the supplied stream is null
      Throws:
        `ValueFormatException` - if the conversion from an input stream could not be performed
        `IoException` - If an unexpected problem occurs while accessing the supplied stream (such as an `IOException`).

    - #### create

          T create(InputStream stream,
                 String hint)
                   throws ValueFormatException,
                          IoException

      Create a value from the binary content given by the supplied stream with a hint to the BinaryStore for how to store it
      Parameters:
        `stream` - the stream containing the content to be used to create the value
        `hint` - a hint that the BinaryStore may use to make storage decisions about this input stream
      Returns:
        the value, or null if the supplied stream is null
      Throws:
        `ValueFormatException` - if the conversion from an input stream could not be performed
        `IoException` - If an unexpected problem occurs while accessing the supplied stream (such as an `IOException`).

    - #### create

          T create(Object value)
                   throws ValueFormatException,
                          IoException

      Create a value from the specified information by determining which other `create` method applies and delegating to that method. Note that this method only will call `create` methods that take a single parameter; so this excludes `create(InputStream)` and `create(String, TextDecoder)`.
      Parameters:
        `value` - the value
      Returns:
        the new value, or null if the supplied parameter is null
      Throws:
        `ValueFormatException` - if the conversion from an object could not be performed
        `IoException` - If an unexpected problem occurs while accessing the supplied binary value (such as an `IOException`).

    - #### create

          T[] create(String[] values)
                     throws ValueFormatException

      Create an array of values from an array of string values, using no decoding.
      Parameters:
        `values` - the values
      Returns:
        the values, or null if the supplied string is null
      Throws:
        `ValueFormatException` - if the conversion from a string array could not be performed
      See Also:
        `create(String[], TextDecoder)`

    - #### create

          T[] create(String[] values,
                   TextDecoder decoder)
                     throws ValueFormatException

      Create an array of values from an array of strings, using the supplied decoder.
      Parameters:
        `values` - the string values from which the values are to be created
        `decoder` - the decoder that should be used; if null, the `default decoder` is used
      Returns:
        the value, or null if the supplied string is null
      Throws:
        `ValueFormatException` - if the conversion from a string array could not be performed
      See Also:
        `create(String)`

    - #### create

          T[] create(int[] values)
                     throws ValueFormatException

      Create an array of values from an array of integers.
      Parameters:
        `values` - the integers from which the values are to be created
      Returns:
        the values, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an integer array could not be performed

    - #### create

          T[] create(long[] values)
                     throws ValueFormatException

      Create an array of values from an array of longs.
      Parameters:
        `values` - the longs from which the values are to be created
      Returns:
        the values, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an array of longs could not be performed

    - #### create

          T[] create(boolean[] values)
                     throws ValueFormatException

      Create an array of values from an array of booleans.
      Parameters:
        `values` - the booleans from which the values are to be created
      Returns:
        the values, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an array of booleans could not be performed

    - #### create

          T[] create(float[] values)
                     throws ValueFormatException

      Create an array of values from an array of floats.
      Parameters:
        `values` - the floats from which the values are to be created
      Returns:
        the values, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an array of floats could not be performed

    - #### create

          T[] create(double[] values)
                     throws ValueFormatException

      Create an array of values from an array of doubles.
      Parameters:
        `values` - the doubles from which the values are to be created
      Returns:
        the values, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an array of doubles could not be performed

    - #### create

          T[] create(BigDecimal[] values)
                     throws ValueFormatException

      Create an array of values from an array of decimal values.
      Parameters:
        `values` - the decimals from which the values are to be created
      Returns:
        the values, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an array of decimal values could not be performed

    - #### create

          T[] create(Calendar[] values)
                     throws ValueFormatException

      Create an array of values from an array of Calendar instances.
      Parameters:
        `values` - the Calendar instances from which the values are to be created
      Returns:
        the values, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an array of calendar instances could not be performed

    - #### create

          T[] create(Date[] values)
                     throws ValueFormatException

      Create an array of values from an array of dates.
      Parameters:
        `values` - the dates from which the values are to be created
      Returns:
        the values, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an array of date values could not be performed

    - #### create

          T[] create(DateTime[] values)
                     throws ValueFormatException

      Create an array of values from an array of `DateTime` instants.
      Parameters:
        `values` - the instants from which the values are to be created
      Returns:
        the values, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an array of date values could not be performed

    - #### create

          T[] create(Name[] values)
                     throws ValueFormatException

      Create an array of values from an array of names.
      Parameters:
        `values` - the names from which the values are to be created
      Returns:
        the values, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an array of names could not be performed

    - #### create

          T[] create(Path[] values)
                     throws ValueFormatException

      Create an array of values from an array of paths.
      Parameters:
        `values` - the paths from which the values are to be created
      Returns:
        the values, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an array of paths could not be performed

    - #### create

          T[] create(Reference[] values)
                     throws ValueFormatException

      Create an array of values from an array of references.
      Parameters:
        `values` - the references from which the values are to be created
      Returns:
        the values, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an array of references could not be performed

    - #### create

          T[] create(URI[] values)
                     throws ValueFormatException

      Create an array of values from an array of URIs.
      Parameters:
        `values` - the URIs from which the values are to be created
      Returns:
        the values, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an array of URIs could not be performed

    - #### create

          T[] create(UUID[] values)
                     throws ValueFormatException

      Create an array of values from an array of UUIDs.
      Parameters:
        `values` - the UUIDs from which the values are to be created
      Returns:
        the values, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an array of UUIDs could not be performed

    - #### create

          T[] create(NodeKey[] value)
                     throws ValueFormatException

      Create an array of values from an array of `NodeKey`.
      Parameters:
        `value` - the node key from which the value is to be created
      Returns:
        the value, or null if the supplied URI is null
      Throws:
        `ValueFormatException` - if the conversion from a NodeKey could not be performed

    - #### create

          T[] create(byte[][] values)
                     throws ValueFormatException

      Create an array of values from the array of binary content.
      Parameters:
        `values` - the array of content to be used to create the values
      Returns:
        the value, or null if the supplied array is null
      Throws:
        `ValueFormatException` - if the conversion from an array of byte arrays could not be performed

    - #### create

          T[] create(BinaryValue[] values)
                     throws ValueFormatException,
                            IoException

      Create an array of values from the array of binary objects.
      Parameters:
        `values` - the values
      Returns:
        the new value, or null if the supplied parameter is null
      Throws:
        `ValueFormatException` - if the conversion from an array of objects could not be performed
        `IoException` - If an unexpected problem occurs during the conversion.

    - #### create

          T[] create(Object[] values)
                     throws ValueFormatException,
                            IoException

      Create an array of values from the specified information by determining which other `create` method applies for each object and then delegating to that method. Note that this method will not consider `create(InputStream)` and `create(String, TextDecoder)`.
      Parameters:
        `values` - the values
      Returns:
        the new value, or null if the supplied parameter is null
      Throws:
        `ValueFormatException` - if the conversion from an array of objects could not be performed
        `IoException` - If an unexpected problem occurs during the conversion.

    - #### create

          Iterator<T> create(Iterator<?> values)
                             throws ValueFormatException,
                                    IoException

      Create an iterator over the values (of an unknown type). The factory converts any values as required. Note that this method will not consider `create(InputStream)` and `create(String, TextDecoder)`.

      This is useful to use when iterating over the `values` of a `Property`.

      Parameters:
        `values` - the values
      Returns:
        the iterator of type `T` over the values, or null if the supplied parameter is null
      Throws:
        `ValueFormatException` - if the conversion from an iterator of objects could not be performed
        `IoException` - If an unexpected problem occurs during the conversion.
      See Also:
        `Property.getValues()`

    - #### create

          Iterable<T> create(Iterable<?> valueIterable)
                             throws ValueFormatException,
                                    IoException

      Create an iterable with the values (of an unknown type). The factory converts any values as required. Note that this method will not consider `create(InputStream)` and `create(String, TextDecoder)`.

      This is useful to use when converting all the `values` of a `Property`.

      Example:

                Property property = ...
                ExecutionContext executionContext = ...
                ValueFactory<String> stringFactory = executionContext.getValueFactories().getStringFactory();
                for (String token : stringFactory.create(property)) {
                    ...
                }

      Parameters:
        `valueIterable` - the values
      Returns:
        the iterator of type `T` over the values, or null if the supplied parameter is null
      Throws:
        `ValueFormatException` - if the conversion from an iterator of objects could not be performed
        `IoException` - If an unexpected problem occurs during the conversion.
      See Also:
        `Property.getValues()`

    - #### createEmptyArray

          T[] createEmptyArray(int length)

      Creates an empty array of the given type.
      Parameters:
        `length` - the length of the array; must be a positive value
      Returns:
        an empty array of the given length.

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