add documentation

core/src/main/java/org/elasticsearch/action/admin/indices/rollover/Condition.java

@@ -27,12 +27,17 @@ import org.elasticsearch.common.xcontent.ObjectParser;
 
 import java.util.Set;
 
+/**
+ * Base class for rollover request conditions
+ */
 public abstract class Condition<T> implements NamedWriteable {
+
     public static ObjectParser<Set<Condition>, ParseFieldMatcherSupplier> PARSER =
         new ObjectParser<>("conditions", null);
     static {
         PARSER.declareString((conditions, s) ->
-            conditions.add(new MaxAgeCondition(TimeValue.parseTimeValue(s, MaxAgeCondition.NAME))), new ParseField(MaxAgeCondition.NAME));
+            conditions.add(new MaxAgeCondition(TimeValue.parseTimeValue(s, MaxAgeCondition.NAME))),
+            new ParseField(MaxAgeCondition.NAME));
         PARSER.declareLong((conditions, value) ->
             conditions.add(new MaxDocsCondition(value)), new ParseField(MaxDocsCondition.NAME));
     }
@@ -51,6 +56,9 @@ public abstract class Condition<T> implements NamedWriteable {
         return "[" + name + ": " + value + "]";
     }
 
+    /**
+     * Holder for index stats used to evaluate conditions
+     */
     public static class Stats {
         public final long numDocs;
         public final long indexCreated;
@@ -61,6 +69,9 @@ public abstract class Condition<T> implements NamedWriteable {
         }
     }
 
+    /**
+     * Holder for evaluated condition result
+     */
     public static class Result {
         public final Condition condition;
         public final boolean matched;

core/src/main/java/org/elasticsearch/action/admin/indices/rollover/MaxAgeCondition.java

@@ -25,6 +25,10 @@ import org.elasticsearch.common.unit.TimeValue;
 
 import java.io.IOException;
 
+/**
+ * Condition for index maximum age. Evaluates to <code>true</code>
+ * when the index is at least {@link #value} old
+ */
 public class MaxAgeCondition extends Condition<TimeValue> {
     public final static String NAME = "max_age";
 

core/src/main/java/org/elasticsearch/action/admin/indices/rollover/MaxDocsCondition.java

@@ -24,6 +24,10 @@ import org.elasticsearch.common.io.stream.StreamOutput;
 
 import java.io.IOException;
 
+/**
+ * Condition for maximum index docs. Evaluates to <code>true</code>
+ * when the index has at least {@link #value} docs
+ */
 public class MaxDocsCondition extends Condition<Long> {
     public final static String NAME = "max_docs";
 

core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverRequest.java

@@ -45,24 +45,18 @@ import java.util.Set;
 import static org.elasticsearch.action.ValidateActions.addValidationError;
 
 /**
- * Request class to swap index under an alias given some predicates
- * TODO: documentation
+ * Request class to swap index under an alias upon satisfying conditions
  */
 public class RolloverRequest extends AcknowledgedRequest<RolloverRequest> implements IndicesRequest {
 
-    private String alias;
-    private boolean simulate;
-    private Set<Condition> conditions = new HashSet<>(2);
-    private CreateIndexRequest createIndexRequest = new CreateIndexRequest("_na_");
-
     public static ObjectParser<RolloverRequest, ParseFieldMatcherSupplier> PARSER =
         new ObjectParser<>("conditions", null);
     static {
         PARSER.declareField((parser, request, parseFieldMatcherSupplier) ->
-            Condition.PARSER.parse(parser, request.conditions, parseFieldMatcherSupplier),
+                Condition.PARSER.parse(parser, request.conditions, parseFieldMatcherSupplier),
             new ParseField("conditions"), ObjectParser.ValueType.OBJECT);
         PARSER.declareField((parser, request, parseFieldMatcherSupplier) ->
-            request.createIndexRequest.settings(parser.map()),
+                request.createIndexRequest.settings(parser.map()),
             new ParseField("settings"), ObjectParser.ValueType.OBJECT);
         PARSER.declareField((parser, request, parseFieldMatcherSupplier) -> {
             for (Map.Entry<String, Object> mappingsEntry : parser.map().entrySet()) {
@@ -71,10 +65,15 @@ public class RolloverRequest extends AcknowledgedRequest<RolloverRequest> implem
             }
         }, new ParseField("mappings"), ObjectParser.ValueType.OBJECT);
         PARSER.declareField((parser, request, parseFieldMatcherSupplier) ->
-            request.createIndexRequest.aliases(parser.map()),
+                request.createIndexRequest.aliases(parser.map()),
             new ParseField("aliases"), ObjectParser.ValueType.OBJECT);
     }
 
+    private String alias;
+    private boolean simulate;
+    private Set<Condition> conditions = new HashSet<>(2);
+    private CreateIndexRequest createIndexRequest = new CreateIndexRequest("_na_");
+
     RolloverRequest() {}
 
     public RolloverRequest(String alias) {
@@ -128,42 +127,58 @@ public class RolloverRequest extends AcknowledgedRequest<RolloverRequest> implem
         return IndicesOptions.strictSingleIndexNoExpandForbidClosed();
     }
 
+    /**
+     * Sets the alias to rollover to another index
+     */
     public void setAlias(String alias) {
         this.alias = alias;
     }
 
+    /**
+     * Sets if the rollover should not be executed when conditions are met
+     */
     public void simulate(boolean simulate) {
         this.simulate = simulate;
     }
 
+    /**
+     * Adds condition to check if the index is at least <code>age</code> old
+     */
     public void addMaxIndexAgeCondition(TimeValue age) {
         this.conditions.add(new MaxAgeCondition(age));
     }
 
-    public void addMaxIndexDocsCondition(long docs) {
-        this.conditions.add(new MaxDocsCondition(docs));
+    /**
+     * Adds condition to check if the index has at least <code>numDocs</code>
+     */
+    public void addMaxIndexDocsCondition(long numDocs) {
+        this.conditions.add(new MaxDocsCondition(numDocs));
+    }
+
+    /**
+     * Sets rollover index creation request to override index settings when
+     * the rolled over index has to be created
+     */
+    public void setCreateIndexRequest(CreateIndexRequest createIndexRequest) {
+        this.createIndexRequest = Objects.requireNonNull(createIndexRequest, "create index request must not be null");;
     }
 
-    public boolean isSimulate() {
+    boolean isSimulate() {
         return simulate;
     }
 
-    public Set<Condition> getConditions() {
+    Set<Condition> getConditions() {
         return conditions;
     }
 
-    public String getAlias() {
+    String getAlias() {
         return alias;
     }
 
-    public CreateIndexRequest getCreateIndexRequest() {
+    CreateIndexRequest getCreateIndexRequest() {
         return createIndexRequest;
     }
 
-    public void setCreateIndexRequest(CreateIndexRequest createIndexRequest) {
-        this.createIndexRequest = Objects.requireNonNull(createIndexRequest, "create index request must not be null");;
-    }
-
     public void source(BytesReference source) {
         XContentType xContentType = XContentFactory.xContentType(source);
         if (xContentType != null) {

core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverRequestBuilder.java

@@ -25,9 +25,6 @@ import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.common.unit.TimeValue;
 
 
-/**
- * TODO: Documentation
- */
 public class RolloverRequestBuilder extends MasterNodeOperationRequestBuilder<RolloverRequest, RolloverResponse,
     RolloverRequestBuilder> {
     public RolloverRequestBuilder(ElasticsearchClient client, RolloverAction action) {

core/src/main/java/org/elasticsearch/action/admin/indices/rollover/RolloverResponse.java

@@ -56,26 +56,44 @@ public final class RolloverResponse extends ActionResponse implements ToXContent
             .collect(Collectors.toSet());
     }
 
+    /**
+     * Returns the name of the index that the request alias was pointing to
+     */
     public String getOldIndex() {
         return oldIndex;
     }
 
+    /**
+     * Returns the name of the index that the request alias currently points to
+     */
     public String getNewIndex() {
         return newIndex;
     }
 
+    /**
+     * Returns the statuses of all the request conditions
+     */
     public Set<Map.Entry<String, Boolean>> getConditionStatus() {
         return conditionStatus;
     }
 
+    /**
+     * Returns if the rollover execution was skipped even when conditions were met
+     */
     public boolean isSimulate() {
         return simulate;
     }
 
+    /**
+     * Returns if the rollover was not simulated and the conditions were met
+     */
     public boolean isRolledOver() {
         return rolledOver;
     }
 
+    /**
+     * Returns if the rollover index had to be explicitly created
+     */
     public boolean isRolloverIndexCreated() {
         return rolloverIndexCreated;
     }

core/src/main/java/org/elasticsearch/action/admin/indices/rollover/TransportRolloverAction.java

@@ -51,7 +51,7 @@ import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 
 /**
- * Main class to swap the index pointed to by an alias, given some predicates
+ * Main class to swap the index pointed to by an alias, given some conditions
  */
 public class TransportRolloverAction extends TransportMasterNodeAction<RolloverRequest, RolloverResponse> {
 

docs/reference/indices.asciidoc

@@ -16,6 +16,7 @@ index settings, aliases, mappings, and index templates.
 * <<indices-exists>>
 * <<indices-open-close>>
 * <<indices-shrink-index>>
+* <<indices-rollover-index>>
 
 [float]
 [[mapping-management]]

docs/reference/indices/rollover-index.asciidoc

@@ -0,0 +1,84 @@
+[[indices-rollover-index]]
+== Rollover Index
+
+The rollover index API allows to switch the index pointed to by an alias given some predicates.
+In order to rollover an index, the provided alias has to point to a single index. Upon satisfying
+any of the predicates, the alias is switched to point to a new index, creating the index if it
+does not exist. The rollover API requires the old concrete index name to have `{index_prefix}-{num}`
+format, as rollover index name is generated following `{index_prefix}-{num+1}` format.
+
+This API is syntactic sugar for changing the index pointed to by an alias given some predicate.
+
+The rollover API must be used against an alias that points to a single index:
+
+[source,js]
+--------------------------------------------------
+$ curl -XPUT 'http://localhost:9200/index-1/' -d '{
+    "aliases" : {
+        "index_alias": {}
+    }
+}'
+--------------------------------------------------
+
+To rollover `index_alias` to point to a new index:
+
+[source,js]
+--------------------------------------------------
+$ curl -XPOST 'http://localhost:9200/index_alias/_rollover' -d '{
+    "conditions" : {
+        "max_age": "7d", <1>
+        "max_docs": 1000 <2>
+    }
+}'
+--------------------------------------------------
+<1> Sets a condition that the index has to be at least 7 days old
+<2> Sets a condition that the index has to have at least a 1000 documents
+
+The API call above switches the index pointed to by `index_alias` from `index-1` to `index-2`, if any
+of the conditions are met. If `index-2` does not exist, it is created (using matching <<indices-templates>>
+if available). The API call returns immediately if none of the conditions are met.
+
+The `_rollover` API is similar to <<indices-create-index>> and accepts `settings`, `mappings` and `aliases`
+to override the index create request for a non-existent rolled over index.
+
+[source,js]
+--------------------------------------------------
+$ curl -XPOST 'http://localhost:9200/index_alias/_rollover' -d '{
+    "conditions" : {
+        "max_age": "7d",
+        "max_docs": 1000
+    },
+    "settings": { <1>
+        "index.number_of_shards": 2
+    }
+}'
+--------------------------------------------------
+<1> Set settings to override matching index template, `mappings` and `aliases` can also be provided.
+
+Using the http `GET` method for the API runs the rollover in simulated mode, where request conditions can be
+checked without performing the actual rollover. Setting `simulate=true` as a request parameter also runs
+the request in simulated mode.
+
+An example response for the index rollover API:
+
+[source,js]
+--------------------------------------------------
+{
+	"old_index": "index-1", <1>
+	"new_index": "index-2", <2>
+	"rolled_over": true, <3>
+	"simulated": false, <4>
+	"rollover_index_created": true, <5>
+	"conditions": { <6>
+	    "[max_age: 7d]": true,
+	    "[max_docs: 1000]": true
+	}
+}
+--------------------------------------------------
+<1> name of the index the alias was pointing to
+<2> name of the index the alias currently points to
+<3> whether the alias switch was successful
+<4> whether the rollover was dry run
+<5> whether the rolled over index had to be explicitly created
+<6> status of the evaluated request conditions
+