[dna-commits] DNA SVN: r401 - trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph.

[dna-commits at lists.jboss.org]

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;