SOLR-4472: jdoc updates for DateField and UUIDField refering to TimestampUpdateProcessorFactory and UUIDUpdateProcessorFactory

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1448879 13f79535-47bb-0310-9956-ffa450edef68

solr/core/src/java/org/apache/solr/schema/DateField.java

@@ -37,6 +37,7 @@ import org.apache.solr.request.SolrQueryRequest;
 import org.apache.solr.response.TextResponseWriter;
 import org.apache.solr.search.QParser;
 import org.apache.solr.util.DateMathParser;
+import org.apache.solr.update.processor.TimestampUpdateProcessorFactory; //jdoc
 
 import java.io.IOException;
 import java.text.*;
@@ -85,6 +86,13 @@ import java.util.*;
  * ie: "NOW+1YEAR", "NOW/DAY", "1995-12-31T23:59:59.999Z+5MINUTES", etc...
  * -- see {@link DateMathParser} for more examples.
  * </p>
+ * <p>
+ * <b>NOTE:</b> Allthough it is possible to configure a <code>DateField</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 recomended instead.
+ * </p>
  *
  * <p>
  * Explanation of "UTC"...
@@ -101,7 +109,7 @@ import java.util.*;
  *
  *
  * @see <a href="http://www.w3.org/TR/xmlschema-2/#dateTime">XML schema part 2</a>
- *
+ * @deprecated {@link TrieDateField} is recomended for all new schemas
  */
 public class DateField extends PrimitiveFieldType {
 

solr/core/src/java/org/apache/solr/schema/TrieDateField.java

@@ -17,14 +17,15 @@
 
 package org.apache.solr.schema;
 
-import org.apache.lucene.queries.function.FunctionValues;
-import org.apache.lucene.queries.function.ValueSource;
 import org.apache.solr.search.QParser;
 import org.apache.solr.common.SolrException;
 import org.apache.solr.response.TextResponseWriter;
+import org.apache.solr.update.processor.TimestampUpdateProcessorFactory; //jdoc
 import org.apache.lucene.document.FieldType.NumericType;
 import org.apache.lucene.index.AtomicReaderContext;
 import org.apache.lucene.index.StorableField;
+import org.apache.lucene.queries.function.FunctionValues;
+import org.apache.lucene.queries.function.ValueSource;
 import org.apache.lucene.search.SortField;
 import org.apache.lucene.search.Query;
 import org.apache.lucene.search.NumericRangeQuery;
@@ -36,6 +37,24 @@ import java.util.Map;
 import java.util.Date;
 import java.io.IOException;
 
+/**
+ * <p>
+ * An extension of {@link DateField} that supports the same values and 
+ * syntax, but indexes the value more efficiently using a numeric 
+ * {@link TrieField} under the covers.  See the description of 
+ * {@link DateField} for more details of the supported usage.
+ * </p>
+ * <p>
+ * <b>NOTE:</b> Allthough it is possible to configure a <code>TrieDateField</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 recomended instead.
+ * </p>
+ *
+ * @see DateField
+ * @see TrieField
+ */
 public class TrieDateField extends DateField {
 
   final TrieField wrappedField = new TrieField() {{

solr/core/src/java/org/apache/solr/schema/UUIDField.java

@@ -26,11 +26,22 @@ import org.apache.lucene.index.StorableField;
 import org.apache.lucene.search.SortField;
 import org.apache.solr.common.SolrException;
 import org.apache.solr.response.TextResponseWriter;
-
+import org.apache.solr.update.processor.UUIDUpdateProcessorFactory; // jdoc
 /**
+ * <p>
  * This FieldType accepts UUID string values, as well as the special value 
  * of "NEW" which triggers generation of a new random UUID.
- *
+ * </p>
+ * <p>
+ * <b>NOTE:</b> Configuring a <code>UUIDField</code> 
+ * instance with a default value of "<code>NEW</code>" is not advisable for 
+ * most users when using SolrCloud (and not possible if the UUID value is 
+ * configured as the unique key field) since the result will be that each 
+ * replica of each document will get a unique UUID value.  
+ * Using {@link UUIDUpdateProcessorFactory} to generate UUID values when 
+ * documents are added is recomended instead.
+ * </p>
+ * 
  * @see UUID#toString
  * @see UUID#randomUUID
  *

solr/example/example-DIH/solr/db/conf/schema.xml

@@ -293,12 +293,6 @@
         results by manufacturer.  copied from "manu" via copyField -->
    <field name="manu_exact" type="string" indexed="true" stored="false"/>
 
-   <!-- Here, default is used to create a "timestamp" field indicating
-        When each document was indexed.
-     -->
-   <field name="timestamp" type="date" indexed="true" stored="true" default="NOW" multiValued="false"/>
-   
-
    <!-- Dynamic field definitions.  If a field name is not found, dynamicFields
         will be used if the name matches any of the patterns.
         RESTRICTION: the glob-like pattern in the name attribute must have

solr/example/example-DIH/solr/solr/conf/schema.xml

@@ -293,12 +293,6 @@
         results by manufacturer.  copied from "manu" via copyField -->
    <field name="manu_exact" type="string" indexed="true" stored="false"/>
 
-   <!-- Here, default is used to create a "timestamp" field indicating
-        When each document was indexed.
-     -->
-   <field name="timestamp" type="date" indexed="true" stored="true" default="NOW" multiValued="false"/>
-   
-
    <!-- Dynamic field definitions.  If a field name is not found, dynamicFields
         will be used if the name matches any of the patterns.
         RESTRICTION: the glob-like pattern in the name attribute must have

solr/example/solr/collection1/conf/schema.xml

@@ -176,13 +176,6 @@
      NRT-friendly.
      -->
 
-   <!-- Uncommenting the following will create a "timestamp" field using
-        a default value of "NOW" to indicate when each document was indexed.
-     -->
-   <!--
-   <field name="timestamp" type="date" indexed="true" stored="true" default="NOW" multiValued="false"/>
-     -->
-
    <!-- Dynamic field definitions allow using convention over configuration
        for fields via the specification of patterns to match field names. 
        EXAMPLE:  name="*_i" will match any field ending in _i (like myid_i, z_i)