10:45 a.m.
Author: rhauch
Date: 2008-05-28 11:45:27 -0400 (Wed, 28 May 2008)
New Revision: 204
Modified:
trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/DateTime.java
trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/DateTimeFactory.java
trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/PathFactory.java
Log:
DNA-67: Create graph API for federation engine
http://jira.jboss.org/jira/browse/DNA-67
Added JavaDoc.
Modified: trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/DateTime.java
===================================================================
--- trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/DateTime.java 2008-05-28 02:46:17
UTC (rev 203)
+++ trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/DateTime.java 2008-05-28 15:45:27
UTC (rev 204)
@@ -37,7 +37,24 @@
public interface DateTime extends Comparable<DateTime>, Serializable {
/**
- * Get the ISO-8601 representation of this instance in time.
+ * Get the ISO-8601 representation of this instance in time. The month-based ISO-8601
representation is the most common format
+ * of ISO8601, and is the format used in the XML standards for passing dates and
times:
+ *
+ * <pre>
+ * yyyy-mm-ddTHH:MM:SS.SSSZ
+ * </pre>
+ *
+ * The fields are separated by dashes and consist of:
+ * <ul>
+ * <li>four digit year;</li>
+ * <li>two digit month, where 01 is Janurary and 12 is December;</li>
+ * <li>two digit day of month, from 01 to 31;</li>
+ * <li>two digit hour, from 00 to 23;</li>
+ * <li>two digit minute, from 00 to 59;</li>
+ * <li>two digit second, from 00 to 59;</li>
+ * <li>three decimal places for milliseconds, if required;</li>
+ * <li>time zone offset of the form <code>�HH:mm</code> (or
'0' if UTC)</li>
+ * </ul>
* @return the string representation; never null
*/
String getString();
Modified: trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/DateTimeFactory.java
===================================================================
--- trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/DateTimeFactory.java 2008-05-28
02:46:17 UTC (rev 203)
+++ trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/DateTimeFactory.java 2008-05-28
15:45:27 UTC (rev 204)
@@ -22,6 +22,80 @@
package org.jboss.dna.spi.graph;
/**
+ * A factory for creating {@link DateTime date-time instants}. This interface extends the
{@link ValueFactory} generic interface
+ * and adds specific methods for creating instants for the current time (and time zone)
as well as various combinations of
+ * individual field values.
+ * <h2>ISO-8601</h2>
+ * <p>
+ * The factory creates date-time instants from strings that are in the standard ISO-8601
format. There are three supported styles:
+ * month-based, day-of-year-based, and week-based.
+ * </p>
+ * <h3>Month-Based</h3>
+ * <p>
+ * The month-based representation is the most common format of ISO8601, and is the format
used in the XML standards for passing
+ * dates and times:
+ *
+ * <pre>
+ * yyyy-mm-ddTHH:MM:SS.SSSZ
+ * </pre>
+ *
+ * The fields are separated by dashes and consist of:
+ * <ul>
+ * <li>four digit year;</li>
+ * <li>two digit month, where 01 is Janurary and 12 is December;</li>
+ * <li>two digit day of month, from 01 to 31;</li>
+ * <li>two digit hour, from 00 to 23;</li>
+ * <li>two digit minute, from 00 to 59;</li>
+ * <li>two digit second, from 00 to 59;</li>
+ * <li>three decimal places for milliseconds, if required;</li>
+ * <li>time zone offset of the form <code>�HH:mm</code> (or '0'
if UTC)</li>
+ * </ul>
+ * </p>
+ * <h3>Day of Year Based</h3>
+ * <p>
+ * This format of ISO-8601 uses a single field to represent the day of the year:
+ *
+ * <pre>
+ * yyyy-dddTHH:MM:SS.SSSZ
+ * </pre>
+ *
+ * The fields are separated by dashes and consist of:
+ * <ul>
+ * <li>four digit year</li>
+ * <li>three digit day of year, from 001 to 366;</li>
+ * <li>two digit hour, from 00 to 23;</li>
+ * <li>two digit minute, from 00 to 59;</li>
+ * <li>two digit second, from 00 to 59;</li>
+ * <li>three decimal places for milliseconds, if required;</li>
+ * <li>time zone offset of the form <code>�HH:mm</code> (or '0'
if UTC)</li>
+ * </ul>
+ * </p>
+ * <h3>Week Based</h3>
+ * <p>
+ * This format of ISO-8601 uses a single field to represent the day of the year:
+ *
+ * <pre>
+ * yyyy-Www-dTHH:MM:SS.SSSZ
+ * </pre>
+ *
+ * The fields are separated by dashes and consist of:
+ * <ul>
+ * <li>four digit weekyear (see below)</li>
+ * <li>two digit week of year, from 01 to 53;</li>
+ * <li>one digit day of week, from 1 to 7 where 1 is Monday and 7 is
Sunday;</li>
+ * <li>two digit hour, from 00 to 23;</li>
+ * <li>two digit minute, from 00 to 59;</li>
+ * <li>two digit second, from 00 to 59;</li>
+ * <li>three decimal places for milliseconds, if required;</li>
+ * <li>time zone offset of the form <code>�HH:mm</code> (or '0'
if UTC)</li>
+ * </ul>
+ * </p>
+ * <p>
+ * From <a
href="http://joda-time.sourceforge.net/cal_iso.html">Joda-Ti...;:
Weeks are always complete, and the first week of a
+ * year is the one that includes the first Thursday of the year. This definition can mean
that the first week of a year starts in
+ * the previous year, and the last week finishes in the next year. The weekyear field is
defined to refer to the year that owns
+ * the week, which may differ from the actual year.
+ * </p>
* @author Randall Hauch
*/
public interface DateTimeFactory extends ValueFactory<DateTime> {
Modified: trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/PathFactory.java
===================================================================
--- trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/PathFactory.java 2008-05-28
02:46:17 UTC (rev 203)
+++ trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/PathFactory.java 2008-05-28
15:45:27 UTC (rev 204)
@@ -22,7 +22,8 @@
package org.jboss.dna.spi.graph;
/**
- * A factory for creating {@link Path paths}.
+ * A factory for creating {@link Path paths}. This interface extends the {@link
ValueFactory} generic interface and adds specific
+ * methods for creating paths (and relative paths) from a series of names, segments, or
combinations.
* @author Randall Hauch
*/
public interface PathFactory extends ValueFactory<Path> {