org.modeshape.jcr.value

## Interface Property

- All Superinterfaces:
    Comparable<Property>, Iterable<Object>, Readable, Serializable
  All Known Implementing Classes:
    BasicEmptyProperty, BasicMultiValueProperty, BasicProperty, BasicSingleValueProperty

      @Immutable
      public interface Property
      extends Iterable<Object>, Comparable<Property>, Readable, Serializable

  Representation of a property consisting of a name and value(s). Note that this property is immutable, meaning that the property values may not be changed through this interface.

  This class is designed to be used with the `ValueFactories` interface and the particular `ValueFactory` that corresponds to the type of value you'd like to use. The `ValueFactory` will then return the values (if no type conversion is required) or will convert the values using the appropriate conversion algorithm.

  The following example shows how to obtain the `String` representations of the `property values`:

         ValueFactories valueFactories = ...
         Property property = ...
         Iterator<String> iter = valueFactories.getStringFactory().create(property.getValues());
         while ( iter.hasNext() ) {
             System.out.println(iter.next());
         }

  Meanwhile, the `long value factory` converts the values to `long`, the `date value factory` converts the values to `DateTime` instances, and so on.

  This technique is much better and far safer than casting the values. It is possible that some Property instances contain heterogeneous values, so casting may not always work. Also, this technique guarantees that the values are properly converted if the type is not what you expected.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `Property.ValueTypeTransformer<T>` Interface which allows the conversion of a property value to a given type.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `getFirstValue()` Obtain the property's first value in its natural form.
    `Name` | `getName()` Get the name of the property.
    `Object` | `getValue(int index)` Returns the value of the property at the given index.
    `Iterator<?>` | `getValues()` Obtain the property's values in their natural form.
    `Object[]` | `getValuesAsArray()` Obtain the property's values as an array of objects in their natural form.
    `<T> T[]` | `getValuesAsArray(Property.ValueTypeTransformer<T> valueTypeTransformer, Class<T> type)` Convert the values of this property to the given type, using the specified type transformer.
    `<T> T[]` | `getValuesAsArray(ValueFactory<T> valueFactory)` Convert the values of this property to whatever type the given value factory is used to create.
    `boolean` | `isBinary()` Determine whether this property is a binary property or not.
    `boolean` | `isEmpty()` Determine whether this property has no actual values.
    `boolean` | `isMultiple()` Determine whether the property currently has multiple values.
    `boolean` | `isReference()` Determine whether this property contains reference values, based upon the first value in the property.
    `boolean` | `isSimpleReference()` Determine whether this property contains simple reference values, based upon the first value in the property.
    `boolean` | `isSingle()` Determine whether the property currently has a single value.
    `int` | `size()` Get the number of actual values in this property.

    - ### Methods inherited from interface java.lang.Iterable

      `iterator`

    - ### Methods inherited from interface java.lang.Comparable

      `compareTo`

    - ### Methods inherited from interface org.modeshape.jcr.value.Readable

      `getString, getString, getString, getString, getString`

- - ### Method Detail

    - #### getName

          Name getName()

      Get the name of the property.
      Returns:
        the property name; never null

    - #### size

          int size()

      Get the number of actual values in this property. If the property allows `multiple values`, then this method may return a value greater than 1. If the property only allows a `single value`, then this method will return either 0 or 1. This method may return 0 regardless of whether the property allows a `single value`, or `multiple values`.
      Returns:
        the number of actual values in this property; always non-negative

    - #### isMultiple

          boolean isMultiple()

      Determine whether the property currently has multiple values.
      Returns:
        true if the property has multiple values, or false otherwise.
      See Also:
        `isSingle()`, `isEmpty()`

    - #### isSingle

          boolean isSingle()

      Determine whether the property currently has a single value.
      Returns:
        true if the property has a single value, or false otherwise.
      See Also:
        `isMultiple()`, `isEmpty()`

    - #### isEmpty

          boolean isEmpty()

      Determine whether this property has no actual values. This method may return `true` regardless of whether the property allows a `single value`, or `multiple values`.

      This method is a convenience method that is equivalent to `size() == 0`.

      Returns:
        true if this property has no values, or false otherwise
      See Also:
        `isMultiple()`, `isSingle()`

    - #### isReference

          boolean isReference()

      Determine whether this property contains reference values, based upon the first value in the property. Note that `PropertyType.SIMPLEREFERENCE` properties *are not* treated as references in order to avoid setting the back-pointer.
      Returns:
        true if this property is a reference property, or false otherwise.

    - #### isSimpleReference

          boolean isSimpleReference()

      Determine whether this property contains simple reference values, based upon the first value in the property.
      Returns:
        true if this property is a simple reference property, or false otherwise.
      See Also:
        `PropertyType.SIMPLEREFERENCE`

    - #### isBinary

          boolean isBinary()

      Determine whether this property is a binary property or not.
      Returns:
        true if the property is a binary property, false otherwise.

    - #### getFirstValue

          Object getFirstValue()

      Obtain the property's first value in its natural form. This is equivalent to calling `isEmpty() ? null : iterator().next()`
      Returns:
        the first value, or null if the property is `empty`
      See Also:
        `Iterable.iterator()`, `getValues()`, `getValuesAsArray()`, `isEmpty()`

    - #### getValues

          Iterator<?> getValues()

      Obtain the property's values in their natural form. This is equivalent to calling `iterator()`.

      A valid iterator is returned if the property has `single valued` or `multi-valued`.

      The resulting iterator is immutable, and all property values are immutable.

      Returns:
        an iterator over the values; never null
      See Also:
        `getFirstValue()`, `Iterable.iterator()`, `getValuesAsArray()`, `ValueFactory.create(Iterator)`

    - #### getValuesAsArray

          Object[] getValuesAsArray()

      Obtain the property's values as an array of objects in their natural form.

      A valid array is return if the property has `single valued` or `multi-valued`, or a null value is returned if the property is `empty`.

      The resulting array is a copy, guaranteeing immutability for the property.

      Returns:
        the array of values
      See Also:
        `getFirstValue()`, `Iterable.iterator()`, `getValues()`, `ValueFactory.create(Object[])`

    - #### getValue

          Object getValue(int index)
                          throws IndexOutOfBoundsException

      Returns the value of the property at the given index.
      Parameters:
        `index` - an `int` representing the index at which to retrieve the value. If the value is `0`, this is equivalent to calling `getFirstValue()`
      Returns:
        the value of the property at the given index; may be `null` if the property is empty.
      Throws:
        `IndexOutOfBoundsException` - if the given index is outside the interval of values of the property.

    - #### getValuesAsArray

          <T> T[] getValuesAsArray(ValueFactory<T> valueFactory)
                               throws ValueFormatException

      Convert the values of this property to whatever type the given value factory is used to create.
      Parameters:
        `valueFactory` - a `AbstractValueFactory` representing the factory which will be used to attempt the conversion of each value.
      Returns:
        the array of values for this property converted (if possible) to given type.
      Throws:
        `ValueFormatException` - if the conversion cannot be performed for any value in the array of values.

    - #### getValuesAsArray

          <T> T[] getValuesAsArray(Property.ValueTypeTransformer<T> valueTypeTransformer,
                                 Class<T> type)
                               throws ValueFormatException

      Convert the values of this property to the given type, using the specified type transformer.
      Parameters:
        `valueTypeTransformer` - a `Property.ValueTypeTransformer` representing the transformer which will be used to attempt the conversion of each value.
        `type` - a `Class` indicating the type to which the transformation is performed; required because of type erasure.
      Returns:
        the array of values for this property converted (if possible) to given type.
      Throws:
        `ValueFormatException` - if the conversion cannot be performed for any value in the array of values.

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