[29/36] lucene-solr:feature/autoscaling: SOLR-9986: Add javadoc to DatePointField class

[sh...@apache.org]

SOLR-9986: Add javadoc to DatePointField class


Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/f71f47c1
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/f71f47c1
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/f71f47c1

Branch: refs/heads/feature/autoscaling
Commit: f71f47c160038bfc12fa55241ed62a0769040a9b
Parents: cedf37c
Author: Tomas Fernandez Lobbe <tf...@apache.org>
Authored: Wed Mar 22 10:52:14 2017 -0700
Committer: Shalin Shekhar Mangar <sh...@apache.org>
Committed: Thu Mar 23 20:10:13 2017 +0530

----------------------------------------------------------------------
 .../org/apache/solr/schema/DatePointField.java  | 62 ++++++++++++++++++++
 1 file changed, 62 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/f71f47c1/solr/core/src/java/org/apache/solr/schema/DatePointField.java
----------------------------------------------------------------------
diff --git a/solr/core/src/java/org/apache/solr/schema/DatePointField.java b/solr/core/src/java/org/apache/solr/schema/DatePointField.java
index 377f571..50f85e3 100644
--- a/solr/core/src/java/org/apache/solr/schema/DatePointField.java
+++ b/solr/core/src/java/org/apache/solr/schema/DatePointField.java
@@ -36,8 +36,70 @@ import org.apache.lucene.util.mutable.MutableValueDate;
 import org.apache.lucene.util.mutable.MutableValueLong;
 import org.apache.solr.search.QParser;
 import org.apache.solr.uninverting.UninvertingReader;
+import org.apache.solr.update.processor.TimestampUpdateProcessorFactory;
 import org.apache.solr.util.DateMathParser;
 
+/**
+ * FieldType that can represent any Date/Time with millisecond precision.
+ * <p>
+ * Date Format for the XML, incoming and outgoing:
+ * </p>
+ * <blockquote>
+ * A date field shall be of the form 1995-12-31T23:59:59Z
+ * The trailing "Z" designates UTC time and is mandatory
+ * (See below for an explanation of UTC).
+ * Optional fractional seconds are allowed, as long as they do not end
+ * in a trailing 0 (but any precision beyond milliseconds will be ignored).
+ * All other parts are mandatory.
+ * </blockquote>
+ * <p>
+ * This format was derived to be standards compliant (ISO 8601) and is a more
+ * restricted form of the
+ * <a href="http://www.w3.org/TR/xmlschema-2/#dateTime-canonical-representation">canonical
+ * representation of dateTime</a> from XML schema part 2.  Examples...
+ * </p>
+ * <ul>
+ *   <li>1995-12-31T23:59:59Z</li>
+ *   <li>1995-12-31T23:59:59.9Z</li>
+ *   <li>1995-12-31T23:59:59.99Z</li>
+ *   <li>1995-12-31T23:59:59.999Z</li>
+ * </ul>
+ * <p>
+ * Note that <code>DatePointField</code> is lenient with regards to parsing fractional
+ * seconds that end in trailing zeros and will ensure that those values
+ * are indexed in the correct canonical format.
+ * </p>
+ * <p>
+ * This FieldType also supports incoming "Date Math" strings for computing
+ * values by adding/rounding internals of time relative either an explicit
+ * datetime (in the format specified above) or the literal string "NOW",
+ * ie: "NOW+1YEAR", "NOW/DAY", "1995-12-31T23:59:59.999Z+5MINUTES", etc...
+ * -- see {@link DateMathParser} for more examples.
+ * </p>
+ * <p>
+ * <b>NOTE:</b> Although it is possible to configure a <code>DatePointField</code>
+ * instance with a default value of "<code>NOW</code>" to compute a timestamp
+ * of when the document was indexed, this is not advisable when using SolrCloud
+ * since each replica of the document may compute a slightly different value.
+ * {@link TimestampUpdateProcessorFactory} is recommended instead.
+ * </p>
+ *
+ * <p>
+ * Explanation of "UTC"...
+ * </p>
+ * <blockquote>
+ * "In 1970 the Coordinated Universal Time system was devised by an
+ * international advisory group of technical experts within the International
+ * Telecommunication Union (ITU).  The ITU felt it was best to designate a
+ * single abbreviation for use in all languages in order to minimize
+ * confusion.  Since unanimous agreement could not be achieved on using
+ * either the English word order, CUT, or the French word order, TUC, the
+ * acronym UTC was chosen as a compromise."
+ * </blockquote>
+ *
+ * @see TrieDateField
+ * @see PointField
+ */
 public class DatePointField extends PointField implements DateValueFieldType {
 
   public DatePointField() {