Author: rhauch Date: 2008-08-07 12:37:58 -0400 (Thu, 07 Aug 2008) New Revision: 401 Modified: trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/Property.java trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/ValueFactory.java Log: DNA-196 - Add methods to ValueFactory that takes Iterator<?> and returns Iterator<T> http://jira.jboss.com/jira/browse/DNA-196 Added more documentation to better explain how the ValueFactory should be used to get at the Property's values. Modified: trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/Property.java =================================================================== --- trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/Property.java 2008-08-07 16:17:48 UTC (rev 400) +++ trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/Property.java 2008-08-07 16:37:58 UTC (rev 401) @@ -27,7 +27,32 @@ /** * 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. + * <p> + * This class is designed to be used with the {@link ValueFactories} interface and the particular {@link ValueFactory} that + * corresponds to the type of value you'd like to use. The <code>ValueFactory</code> will then return the values (if no type + * conversion is required) or will convert the values using the appropriate conversion algorithm. + * </p> + * <p> + * The following example shows how to obtain the {@link String} representations of the {@link #getValues() property values}: * + * <pre> + * ValueFactories valueFactories = ... + * Property property = ... + * Iterator&lt;String&gt; iter = valueFactories.getStringFactory().create(property.getValues()); + * while ( iter.hasNext() ) { + * System.out.println(iter.next()); + * } + * </pre> + * + * Meanwhile, the {@link ValueFactories#getLongFactory() long value factory} converts the values to <code>long</code>, the + * {@link ValueFactories#getDateFactory() date value factory} converts the values to {@link DateTime} instances, and so on. + * </p> + * <p> + * 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. + * </p> + * * @author Randall Hauch */ @Immutable @@ -43,8 +68,8 @@ /** * Get the number of actual values in this property. If the property allows {@link #isMultiple() multiple values}, then this * method may return a value greater than 1. If the property only allows a {@link #isSingle() single value}, then this method - * will return either 0 or 1. This method may return 0 regardless of whether the property allows a - * {@link #isSingle() single value}, or {@link #isMultiple() multiple values}. + * will return either 0 or 1. This method may return 0 regardless of whether the property allows a {@link #isSingle() single + * value}, or {@link #isMultiple() multiple values}. * * @return the number of actual values in this property; always non-negative */ @@ -93,6 +118,7 @@ * @return an iterator over the values; never null * @see Iterable#iterator() * @see #getValuesAsArray() + * @see ValueFactory#create(Iterator) */ Iterator<?> getValues(); @@ -109,6 +135,7 @@ * @return the array of values * @see Iterable#iterator() * @see #getValues() + * @see ValueFactory#create(Object[]) */ Object[] getValuesAsArray(); Modified: trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/ValueFactory.java =================================================================== --- trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/ValueFactory.java 2008-08-07 16:17:48 UTC (rev 400) +++ trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/ValueFactory.java 2008-08-07 16:37:58 UTC (rev 401) @@ -401,10 +401,14 @@ /** * Create an iterator over the values (of an unknown type). The factory converts any values as required. Note that this method * will not consider {@link #create(InputStream, int)}, {@link #create(Reader, int)} and {@link #create(String, TextDecoder)}. + * <p> + * This is useful to use when iterating over the {@link Property#getValues() values} of a {@link Property}. + * </p> * * @param values the values * @return the iterator of type <code>T</code> over the values, or null if the supplied parameter is null * @throws IoException If an unexpected problem occurs during the conversion. + * @see Property#getValues() */ Iterator<T> create( Iterator<?> values ) throws IoException;