helix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From zzh...@apache.org
Subject git commit: [HELIX-208] Add javadocs to classes and public methods in the model package, rb=13748
Date Thu, 22 Aug 2013 23:55:38 GMT
Updated Branches:
  refs/heads/master 1f8a32fa6 -> 58b78f6a4


[HELIX-208] Add javadocs to classes and public methods in the model package, rb=13748


Project: http://git-wip-us.apache.org/repos/asf/incubator-helix/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-helix/commit/58b78f6a
Tree: http://git-wip-us.apache.org/repos/asf/incubator-helix/tree/58b78f6a
Diff: http://git-wip-us.apache.org/repos/asf/incubator-helix/diff/58b78f6a

Branch: refs/heads/master
Commit: 58b78f6a4f16913053f7250c667a91bb31fd6225
Parents: 1f8a32f
Author: zzhang <zzhang5@uci.edu>
Authored: Thu Aug 22 13:51:35 2013 -0700
Committer: zzhang <zzhang5@uci.edu>
Committed: Thu Aug 22 13:51:35 2013 -0700

----------------------------------------------------------------------
 .../org/apache/helix/model/AlertHistory.java    |   7 +
 .../org/apache/helix/model/AlertStatus.java     |  42 ++-
 .../java/org/apache/helix/model/Alerts.java     |  39 +++
 .../apache/helix/model/ClusterConstraints.java  |  42 ++-
 .../org/apache/helix/model/ConstraintItem.java  |  37 ++-
 .../org/apache/helix/model/CurrentState.java    |  55 +++-
 .../main/java/org/apache/helix/model/Error.java |   7 +
 .../org/apache/helix/model/ExternalView.java    |  33 +++
 .../java/org/apache/helix/model/HealthStat.java |  43 +++
 .../apache/helix/model/HelixConfigScope.java    |  46 +++-
 .../java/org/apache/helix/model/IdealState.java | 128 ++++++++-
 .../org/apache/helix/model/InstanceConfig.java  |  72 ++++-
 .../org/apache/helix/model/LeaderHistory.java   |   7 +-
 .../org/apache/helix/model/LiveInstance.java    |  57 +++-
 .../java/org/apache/helix/model/Message.java    | 262 ++++++++++++++++++-
 .../java/org/apache/helix/model/Partition.java  |  10 +-
 .../org/apache/helix/model/PauseSignal.java     |  11 +
 .../org/apache/helix/model/PersistentStats.java |  38 +++
 .../java/org/apache/helix/model/Resource.java   |  55 +++-
 .../helix/model/StateModelDefinition.java       |  66 ++++-
 .../org/apache/helix/model/StatusUpdate.java    |   7 +
 .../java/org/apache/helix/model/Transition.java |  16 ++
 22 files changed, 1043 insertions(+), 37 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/AlertHistory.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/AlertHistory.java b/helix-core/src/main/java/org/apache/helix/model/AlertHistory.java
index 7af017e..58db71d 100644
--- a/helix-core/src/main/java/org/apache/helix/model/AlertHistory.java
+++ b/helix-core/src/main/java/org/apache/helix/model/AlertHistory.java
@@ -21,8 +21,15 @@ package org.apache.helix.model;
 import org.apache.helix.HelixProperty;
 import org.apache.helix.ZNRecord;
 
+/**
+ * Maintains a history of alerts that have been fired, as well as actions taken, if any.
+ */
 public class AlertHistory extends HelixProperty {
 
+  /**
+   * Instantiate the alert history with a pre-populated record
+   * @param record ZNRecord representing the alert history
+   */
   public AlertHistory(ZNRecord record) {
     super(record);
     // TODO Auto-generated constructor stub

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/AlertStatus.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/AlertStatus.java b/helix-core/src/main/java/org/apache/helix/model/AlertStatus.java
index d468473..d90ec1a 100644
--- a/helix-core/src/main/java/org/apache/helix/model/AlertStatus.java
+++ b/helix-core/src/main/java/org/apache/helix/model/AlertStatus.java
@@ -23,20 +23,31 @@ import java.util.Map;
 
 import org.apache.helix.HelixProperty;
 import org.apache.helix.ZNRecord;
+import org.apache.helix.model.Alerts.AlertsProperty;
 
+/**
+ * Get characteristics of alerts, whether they were fired, and their context. An alert is triggered
+ * when cluster health violates pre-defined constraints to ensure that the cluster meets SLAs.
+ */
 public class AlertStatus extends HelixProperty {
 
+  /**
+   * The name of the ZNode containing alert status
+   */
   public final static String nodeName = "AlertStatus";
 
-  public enum AlertsProperty {
-    SESSION_ID,
-    FIELDS
-  }
-
+  /**
+   * Instantiate with an identifier
+   * @param id identifier representing this group of alert statuses
+   */
   public AlertStatus(String id) {
     super(id);
   }
 
+  /**
+   * Instantiate with a pre-populated record corresponding to alert status
+   * @param record ZNRecord representing alert statuses
+   */
   public AlertStatus(ZNRecord record) {
     // _record = record;
     super(record);
@@ -47,14 +58,26 @@ public class AlertStatus extends HelixProperty {
    * public Alerts(ZNRecord record, Stat stat) { super(record, stat); }
    */
 
+  /**
+   * Set the session that these alerts correspond to
+   * @param sessionId session for which to look up alerts
+   */
   public void setSessionId(String sessionId) {
     _record.setSimpleField(AlertsProperty.SESSION_ID.toString(), sessionId);
   }
 
+  /**
+   * Get the session that these alerts correspond to
+   * @return session identifier
+   */
   public String getSessionId() {
     return _record.getSimpleField(AlertsProperty.SESSION_ID.toString());
   }
 
+  /**
+   * Get the instance that these alerts correspond to
+   * @return name of the instance
+   */
   public String getInstanceName() {
     return _record.getId();
   }
@@ -64,10 +87,19 @@ public class AlertStatus extends HelixProperty {
    * _record.getSimpleField(AlertsProperty.CLUSTER_MANAGER_VERSION.toString()); }
    */
 
+  /**
+   * Get the properties of all alerts, such as if they were fired
+   * @return all alert statuses as a Map of alert to the status properties
+   */
   public Map<String, Map<String, String>> getMapFields() {
     return _record.getMapFields();
   }
 
+  /**
+   * Get the statistics of a single alert
+   * @param statName Name of the alert
+   * @return alert statistics as a map of name, value pairs
+   */
   public Map<String, String> getStatFields(String statName) {
     return _record.getMapField(statName);
   }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/Alerts.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/Alerts.java b/helix-core/src/main/java/org/apache/helix/model/Alerts.java
index 02db44c..506e3d5 100644
--- a/helix-core/src/main/java/org/apache/helix/model/Alerts.java
+++ b/helix-core/src/main/java/org/apache/helix/model/Alerts.java
@@ -24,12 +24,22 @@ import java.util.Map;
 import org.apache.helix.HelixProperty;
 import org.apache.helix.ZNRecord;
 
+/**
+ * Describe alerts and corresponding metrics. An alert is triggered when cluster health
+ * violates pre-defined constraints to ensure that the cluster meets SLAs.
+ */
 public class Alerts extends HelixProperty {
 
   // private final ZNRecord _record;
 
+  /**
+   * The name of the ZNode corresponding to this property
+   */
   public final static String nodeName = "Alerts";
 
+  /**
+   * Supported fields corresponding to a set of alerts
+   */
   public enum AlertsProperty {
     SESSION_ID,
     FIELDS
@@ -37,10 +47,18 @@ public class Alerts extends HelixProperty {
 
   // private final ZNRecord _record;
 
+  /**
+   * Instantiate with an identifier
+   * @param id A string that identifies the alerts
+   */
   public Alerts(String id) {
     super(id);
   }
 
+  /**
+   * Instantiate with a pre-populated Alerts record
+   * @param record ZNRecord representing Alerts
+   */
   public Alerts(ZNRecord record) {
     // _record = record;
     super(record);
@@ -51,14 +69,26 @@ public class Alerts extends HelixProperty {
    * public Alerts(ZNRecord record, Stat stat) { super(record, stat); }
    */
 
+  /**
+   * Set the session that the alerts correspond to
+   * @param sessionId the session for which alerts occurred
+   */
   public void setSessionId(String sessionId) {
     _record.setSimpleField(AlertsProperty.SESSION_ID.toString(), sessionId);
   }
 
+  /**
+   * Get the session that the alerts correspond to
+   * @return session identifier
+   */
   public String getSessionId() {
     return _record.getSimpleField(AlertsProperty.SESSION_ID.toString());
   }
 
+  /**
+   * Get the instance that the alerts correspond to
+   * @return the name of the instance
+   */
   public String getInstanceName() {
     return _record.getId();
   }
@@ -69,10 +99,19 @@ public class Alerts extends HelixProperty {
    * }
    */
 
+  /**
+   * Get the alerts
+   * @return a mapping of alert stat name to alert properties
+   */
   public Map<String, Map<String, String>> getMapFields() {
     return _record.getMapFields();
   }
 
+  /**
+   * Get specific alert statistics
+   * @param statName the name of the statistic group
+   * @return a mapping of property and value for the statistic
+   */
   public Map<String, String> getStatFields(String statName) {
     return _record.getMapField(statName);
   }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/ClusterConstraints.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/ClusterConstraints.java b/helix-core/src/main/java/org/apache/helix/model/ClusterConstraints.java
index 15c4345..f69a7ce 100644
--- a/helix-core/src/main/java/org/apache/helix/model/ClusterConstraints.java
+++ b/helix-core/src/main/java/org/apache/helix/model/ClusterConstraints.java
@@ -31,9 +31,15 @@ import org.apache.helix.model.Message.MessageType;
 import org.apache.helix.model.builder.ConstraintItemBuilder;
 import org.apache.log4j.Logger;
 
+/**
+ * All of the constraints on a given cluster and its subcomponents, both physical and logical.
+ */
 public class ClusterConstraints extends HelixProperty {
   private static Logger LOG = Logger.getLogger(ClusterConstraints.class);
 
+  /**
+   * Attributes on which constraints operate
+   */
   public enum ConstraintAttribute {
     STATE,
     MESSAGE_TYPE,
@@ -43,10 +49,16 @@ public class ClusterConstraints extends HelixProperty {
     CONSTRAINT_VALUE
   }
 
+  /**
+   * Possible special values that constraint attributes can take
+   */
   public enum ConstraintValue {
     ANY
   }
 
+  /**
+   * What is being constrained
+   */
   public enum ConstraintType {
     STATE_CONSTRAINT,
     MESSAGE_CONSTRAINT
@@ -55,10 +67,18 @@ public class ClusterConstraints extends HelixProperty {
   // constraint-id -> constraint-item
   private final Map<String, ConstraintItem> _constraints = new HashMap<String, ConstraintItem>();
 
+  /**
+   * Instantiate constraints as a given type
+   * @param type {@link ConstraintType} representing what this constrains
+   */
   public ClusterConstraints(ConstraintType type) {
     super(type.toString());
   }
 
+  /**
+   * Instantiate constraints from a pre-populated ZNRecord
+   * @param record ZNRecord containing all constraints
+   */
   public ClusterConstraints(ZNRecord record) {
     super(record);
 
@@ -78,8 +98,8 @@ public class ClusterConstraints extends HelixProperty {
 
   /**
    * add the constraint, overwrite existing one if constraint with same constraint-id already exists
-   * @param constraintId
-   * @param item
+   * @param constraintId unique constraint identifier
+   * @param item the constraint as a {@link ConstraintItem}
    */
   public void addConstraintItem(String constraintId, ConstraintItem item) {
     Map<String, String> map = new TreeMap<String, String>();
@@ -91,6 +111,10 @@ public class ClusterConstraints extends HelixProperty {
     _constraints.put(constraintId, item);
   }
 
+  /**
+   * Add multiple constraint items.
+   * @param items (constraint identifier, {@link ConstrantItem}) pairs
+   */
   public void addConstraintItems(Map<String, ConstraintItem> items) {
     for (String constraintId : items.keySet()) {
       addConstraintItem(constraintId, items.get(constraintId));
@@ -99,7 +123,7 @@ public class ClusterConstraints extends HelixProperty {
 
   /**
    * remove a constraint-item
-   * @param constraintId
+   * @param constraintId unique constraint identifier
    */
   public void removeConstraintItem(String constraintId) {
     _constraints.remove(constraintId);
@@ -108,8 +132,8 @@ public class ClusterConstraints extends HelixProperty {
 
   /**
    * get a constraint-item
-   * @param constraintId
-   * @return
+   * @param constraintId unique constraint identifier
+   * @return {@link ConstraintItem} or null if not present
    */
   public ConstraintItem getConstraintItem(String constraintId) {
     return _constraints.get(constraintId);
@@ -117,6 +141,8 @@ public class ClusterConstraints extends HelixProperty {
 
   /**
    * return a set of constraints that match the attribute pairs
+   * @param attributes (constraint scope, constraint string) pairs
+   * @return a set of {@link ConstraintItem}s with matching attributes
    */
   public Set<ConstraintItem> match(Map<ConstraintAttribute, String> attributes) {
     Set<ConstraintItem> matches = new HashSet<ConstraintItem>();
@@ -128,7 +154,11 @@ public class ClusterConstraints extends HelixProperty {
     return matches;
   }
 
-  // convert a message to constraint attribute pairs
+  /**
+   * convert a message to constraint attribute pairs
+   * @param msg a {@link Message} containing constraint attributes
+   * @return constraint attribute scope-value pairs
+   */
   public static Map<ConstraintAttribute, String> toConstraintAttributes(Message msg) {
     Map<ConstraintAttribute, String> attributes = new TreeMap<ConstraintAttribute, String>();
     String msgType = msg.getMsgType();

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/ConstraintItem.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/ConstraintItem.java b/helix-core/src/main/java/org/apache/helix/model/ConstraintItem.java
index be032af..6f6b160 100644
--- a/helix-core/src/main/java/org/apache/helix/model/ConstraintItem.java
+++ b/helix-core/src/main/java/org/apache/helix/model/ConstraintItem.java
@@ -26,6 +26,9 @@ import org.apache.helix.model.ClusterConstraints.ConstraintAttribute;
 import org.apache.helix.model.builder.ConstraintItemBuilder;
 import org.apache.log4j.Logger;
 
+/**
+ * A single constraint and its associated attributes
+ */
 public class ConstraintItem {
   private static Logger LOG = Logger.getLogger(ConstraintItem.class);
 
@@ -33,6 +36,10 @@ public class ConstraintItem {
   final Map<ConstraintAttribute, String> _attributes;
   final String _constraintValue;
 
+  /**
+   * Initialize a constraint with attributes
+   * @param attributes the attributes that define the constraint, including the constraint value
+   */
   public ConstraintItem(Map<String, String> attributes) {
     ConstraintItemBuilder builder = new ConstraintItemBuilder();
     builder.addConstraintAttributes(attributes);
@@ -40,11 +47,22 @@ public class ConstraintItem {
     _constraintValue = builder.getConstraintValue();
   }
 
+  /**
+   * Initialize a constraint with {@link ConstraintAttribute}s and a custom constraint value
+   * @param attributes constraint attribute scope-value pairs
+   * @param constraintValue the specific entity(ies) affected by the constraint
+   */
   public ConstraintItem(Map<ConstraintAttribute, String> attributes, String constraintValue) {
     _attributes = attributes;
     _constraintValue = constraintValue;
   }
 
+  /**
+   * Check if this constraint follows these attributes. Note that it is possible that this
+   * constraint could consist of attributes in addition to those that are specified.
+   * @param attributes attributes to check
+   * @return true if the constraint follows every attribute, false otherwise
+   */
   public boolean match(Map<ConstraintAttribute, String> attributes) {
     for (ConstraintAttribute key : _attributes.keySet()) {
       if (!attributes.containsKey(key)) {
@@ -58,7 +76,11 @@ public class ConstraintItem {
     return true;
   }
 
-  // filter out attributes that are not specified by this constraint
+  /**
+   * filter out attributes that are not specified by this constraint
+   * @param attributes attributes to filter
+   * @return attributes of this constraint that are in the provided attributes
+   */
   public Map<ConstraintAttribute, String> filter(Map<ConstraintAttribute, String> attributes) {
     Map<ConstraintAttribute, String> ret = new HashMap<ConstraintAttribute, String>();
     for (ConstraintAttribute key : _attributes.keySet()) {
@@ -69,14 +91,27 @@ public class ConstraintItem {
     return ret;
   }
 
+  /**
+   * Get the actual entities that the constraint operates on
+   * @return the constraint value
+   */
   public String getConstraintValue() {
     return _constraintValue;
   }
 
+  /**
+   * Get all the attributes of the constraint
+   * @return scope-value pairs of attributes
+   */
   public Map<ConstraintAttribute, String> getAttributes() {
     return _attributes;
   }
 
+  /**
+   * Get the value of a specific attribute in this cluster
+   * @param attr the attribute to look up
+   * @return the attribute value, or null if the attribute is not present
+   */
   public String getAttributeValue(ConstraintAttribute attr) {
     return _attributes.get(attr);
   }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/CurrentState.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/CurrentState.java b/helix-core/src/main/java/org/apache/helix/model/CurrentState.java
index 901ee10..32854ab 100644
--- a/helix-core/src/main/java/org/apache/helix/model/CurrentState.java
+++ b/helix-core/src/main/java/org/apache/helix/model/CurrentState.java
@@ -28,11 +28,14 @@ import org.apache.helix.ZNRecord;
 import org.apache.log4j.Logger;
 
 /**
- * Current states of partitions in a resource
+ * Current states of partitions in a resource for an instance.
  */
 public class CurrentState extends HelixProperty {
   private static Logger LOG = Logger.getLogger(CurrentState.class);
 
+  /**
+   * Lookup keys for the current state
+   */
   public enum CurrentStateProperty {
     SESSION_ID,
     CURRENT_STATE,
@@ -42,18 +45,34 @@ public class CurrentState extends HelixProperty {
              // BUCKET_SIZE
   }
 
+  /**
+   * Instantiate a current state with a resource
+   * @param resourceName name identifying the resource
+   */
   public CurrentState(String resourceName) {
     super(resourceName);
   }
 
+  /**
+   * Instantiate a current state with a pre-populated ZNRecord
+   * @param record a ZNRecord corresponding to the current state
+   */
   public CurrentState(ZNRecord record) {
     super(record);
   }
 
+  /**
+   * Get the name of the resource
+   * @return String resource identifier
+   */
   public String getResourceName() {
     return _record.getId();
   }
 
+  /**
+   * Get the partitions on this instance and the state that each partition is currently in.
+   * @return (partition, state) pairs
+   */
   public Map<String, String> getPartitionStateMap() {
     Map<String, String> map = new HashMap<String, String>();
     Map<String, Map<String, String>> mapFields = _record.getMapFields();
@@ -66,14 +85,27 @@ public class CurrentState extends HelixProperty {
     return map;
   }
 
+  /**
+   * Get the session that this current state corresponds to
+   * @return String session identifier
+   */
   public String getSessionId() {
     return _record.getSimpleField(CurrentStateProperty.SESSION_ID.toString());
   }
 
+  /**
+   * Set the session that this current state corresponds to
+   * @param sessionId String session identifier
+   */
   public void setSessionId(String sessionId) {
     _record.setSimpleField(CurrentStateProperty.SESSION_ID.toString(), sessionId);
   }
 
+  /**
+   * Get the state of a partition on this instance
+   * @param partitionName the name of the partition
+   * @return the state, or null if the partition is not present
+   */
   public String getState(String partitionName) {
     Map<String, Map<String, String>> mapFields = _record.getMapFields();
     Map<String, String> mapField = mapFields.get(partitionName);
@@ -83,14 +115,27 @@ public class CurrentState extends HelixProperty {
     return null;
   }
 
+  /**
+   * Set the state model that the resource follows
+   * @param stateModelName an identifier of the state model
+   */
   public void setStateModelDefRef(String stateModelName) {
     _record.setSimpleField(CurrentStateProperty.STATE_MODEL_DEF.toString(), stateModelName);
   }
 
+  /**
+   * Get the state model that the resource follows
+   * @return an identifier of the state model
+   */
   public String getStateModelDefRef() {
     return _record.getSimpleField(CurrentStateProperty.STATE_MODEL_DEF.toString());
   }
 
+  /**
+   * Set the state that a partition is currently in on this instance
+   * @param partitionName the name of the partition
+   * @param state the state of the partition
+   */
   public void setState(String partitionName, String state) {
     Map<String, Map<String, String>> mapFields = _record.getMapFields();
     if (mapFields.get(partitionName) == null) {
@@ -99,10 +144,18 @@ public class CurrentState extends HelixProperty {
     mapFields.get(partitionName).put(CurrentStateProperty.CURRENT_STATE.toString(), state);
   }
 
+  /**
+   * Set the state model factory
+   * @param factoryName the name of the factory
+   */
   public void setStateModelFactoryName(String factoryName) {
     _record.setSimpleField(CurrentStateProperty.STATE_MODEL_FACTORY_NAME.toString(), factoryName);
   }
 
+  /**
+   * Get the state model factory
+   * @return a name that identifies the state model factory
+   */
   public String getStateModelFactoryName() {
     return _record.getSimpleField(CurrentStateProperty.STATE_MODEL_FACTORY_NAME.toString());
   }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/Error.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/Error.java b/helix-core/src/main/java/org/apache/helix/model/Error.java
index b9b6ddf..7744b91 100644
--- a/helix-core/src/main/java/org/apache/helix/model/Error.java
+++ b/helix-core/src/main/java/org/apache/helix/model/Error.java
@@ -22,7 +22,14 @@ package org.apache.helix.model;
 import org.apache.helix.HelixProperty;
 import org.apache.helix.ZNRecord;
 
+/**
+ * Defines an error that occurs in computing a valid ideal state or external view
+ */
 public class Error extends HelixProperty {
+  /**
+   * Create an error from a record representing an existing one
+   * @param record ZNRecord corresponding to an error
+   */
   public Error(ZNRecord record) {
     super(record);
     // TODO Auto-generated constructor stub

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/ExternalView.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/ExternalView.java b/helix-core/src/main/java/org/apache/helix/model/ExternalView.java
index fd5c79a..d5f1afc 100644
--- a/helix-core/src/main/java/org/apache/helix/model/ExternalView.java
+++ b/helix-core/src/main/java/org/apache/helix/model/ExternalView.java
@@ -31,14 +31,29 @@ import org.apache.helix.ZNRecord;
  * of current states for the partitions in a resource
  */
 public class ExternalView extends HelixProperty {
+  /**
+   * Instantiate an external view with the resource it corresponds to
+   * @param resource the name of the resource
+   */
   public ExternalView(String resource) {
     super(new ZNRecord(resource));
   }
 
+  /**
+   * Instantiate an external view with a pre-populated record
+   * @param record ZNRecord corresponding to an external view
+   */
   public ExternalView(ZNRecord record) {
     super(record);
   }
 
+  /**
+   * For a given replica, specify which partition it corresponds to, where it is served, and its
+   * current state
+   * @param partition the partition of the replica being served
+   * @param instance the instance serving the replica
+   * @param state the state the replica is in
+   */
   public void setState(String partition, String instance, String state) {
     if (_record.getMapField(partition) == null) {
       _record.setMapField(partition, new TreeMap<String, String>());
@@ -46,18 +61,36 @@ public class ExternalView extends HelixProperty {
     _record.getMapField(partition).put(instance, state);
   }
 
+  /**
+   * For a given partition, indicate where and in what state each of its replicas is in
+   * @param partitionName the partition to set
+   * @param currentStateMap (instance, state) pairs
+   */
   public void setStateMap(String partitionName, Map<String, String> currentStateMap) {
     _record.setMapField(partitionName, currentStateMap);
   }
 
+  /**
+   * Get all the partitions of the resource
+   * @return a set of partition names
+   */
   public Set<String> getPartitionSet() {
     return _record.getMapFields().keySet();
   }
 
+  /**
+   * Get the instance and the state for each partition replica
+   * @param partitionName the partition to look up
+   * @return (instance, state) pairs
+   */
   public Map<String, String> getStateMap(String partitionName) {
     return _record.getMapField(partitionName);
   }
 
+  /**
+   * Get the resource represented by this view
+   * @return the name of the resource
+   */
   public String getResourceName() {
     return _record.getId();
   }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/HealthStat.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/HealthStat.java b/helix-core/src/main/java/org/apache/helix/model/HealthStat.java
index 42ac339..b884534 100644
--- a/helix-core/src/main/java/org/apache/helix/model/HealthStat.java
+++ b/helix-core/src/main/java/org/apache/helix/model/HealthStat.java
@@ -30,17 +30,32 @@ import org.apache.helix.alerts.StatsHolder;
 import org.apache.helix.model.Message.Attributes;
 import org.apache.log4j.Logger;
 
+/**
+ * Represents a set of properties that can be queried to determine the health of instances on a
+ * Helix-managed cluster
+ */
 public class HealthStat extends HelixProperty {
+  /**
+   * Queryable health statistic properties
+   */
   public enum HealthStatProperty {
     FIELDS
   }
 
   private static final Logger _logger = Logger.getLogger(HealthStat.class.getName());
 
+  /**
+   * Instantiate with an identifier
+   * @param id the name of these statistics
+   */
   public HealthStat(String id) {
     super(id);
   }
 
+  /**
+   * Instantiate with a pre-populated record
+   * @param record a ZNRecord corresponding to health statistics
+   */
   public HealthStat(ZNRecord record) {
     super(record);
     if (getCreateTimeStamp() == 0) {
@@ -48,27 +63,55 @@ public class HealthStat extends HelixProperty {
     }
   }
 
+  /**
+   * Get when these statistics were last modified
+   * @return a UNIX timestamp
+   */
   public long getLastModifiedTimeStamp() {
     return _record.getModifiedTime();
   }
 
+  /**
+   * Get when these statistics were created
+   * @return a UNIX timestamp
+   */
   public long getCreateTimeStamp() {
     return _record.getLongField(Attributes.CREATE_TIMESTAMP.toString(), 0L);
   }
 
+  /**
+   * Get the value of a test field corresponding to a request count
+   * @return the number of requests
+   */
   public String getTestField() {
     return _record.getSimpleField("requestCountStat");
   }
 
+  /**
+   * Set a group of heath statistics, grouped by the statistic
+   * @param healthFields a map of statistic name, the corresponding entity, and the value
+   */
   public void setHealthFields(Map<String, Map<String, String>> healthFields) {
     _record.setMapFields(healthFields);
   }
 
+  /**
+   * Create a key based on a parent key, instance, and statistic
+   * @param instance the instance for which these statistics exist
+   * @param parentKey the originating key
+   * @param statName the statistic
+   * @return a unified key
+   */
   public String buildCompositeKey(String instance, String parentKey, String statName) {
     String delim = ExpressionParser.statFieldDelim;
     return instance + delim + parentKey + delim + statName;
   }
 
+  /**
+   * Get all the health statistics for a given instance
+   * @param instanceName the instance for which to get health statistics
+   * @return a map of (instance and statistic, value or timestamp, value) triples
+   */
   public Map<String, Map<String, String>> getHealthFields(String instanceName) // ,
                                                                                // String
                                                                                // timestamp)

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/HelixConfigScope.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/HelixConfigScope.java b/helix-core/src/main/java/org/apache/helix/model/HelixConfigScope.java
index a8034de..9d3b41a 100644
--- a/helix-core/src/main/java/org/apache/helix/model/HelixConfigScope.java
+++ b/helix-core/src/main/java/org/apache/helix/model/HelixConfigScope.java
@@ -27,7 +27,9 @@ import org.apache.helix.util.StringTemplate;
  * config-scope that replaces @link ConfigScope
  */
 public class HelixConfigScope {
-
+  /**
+   * Defines the various scopes of configs, and how they are represented on Zookeeper
+   */
   public enum ConfigScopeProperty {
     CLUSTER(2, 0),
     PARTICIPANT(2, 0),
@@ -43,16 +45,26 @@ public class HelixConfigScope {
       _mapKeyArgNum = mapKeyArgNum;
     }
 
+    /**
+     * Get the number of template arguments required to generate a full path
+     * @return number of template arguments in the path
+     */
     public int getZkPathArgNum() {
       return _zkPathArgNum;
     }
 
+    /**
+     * Get the number of arguments corresponding to a lookup key
+     * @return number of map key arguments
+     */
     public int getMapKeyArgNum() {
       return _mapKeyArgNum;
     }
   }
 
-  // string templates to generate znode path
+  /**
+   * string templates to generate znode path
+   */
   private static final StringTemplate template = new StringTemplate();
   static {
     // get the znode
@@ -88,6 +100,12 @@ public class HelixConfigScope {
    */
   final boolean _isFullKey;
 
+  /**
+   * Initialize with a type of scope and unique identifiers
+   * @param type the scope
+   * @param zkPathKeys keys identifying a ZNode location
+   * @param mapKey a key for an additional lookup within a ZNode
+   */
   public HelixConfigScope(ConfigScopeProperty type, List<String> zkPathKeys, String mapKey) {
 
     if (zkPathKeys.size() != type.getZkPathArgNum()
@@ -117,26 +135,50 @@ public class HelixConfigScope {
     _mapKey = mapKey;
   }
 
+  /**
+   * Get the scope
+   * @return the type of scope
+   */
   public ConfigScopeProperty getType() {
     return _type;
   }
 
+  /**
+   * Get the cluster name
+   * @return the name of the associated cluster
+   */
   public String getClusterName() {
     return _clusterName;
   }
 
+  /**
+   * Get the participant name if it exists
+   * @return the participant name if the type is PARTICIPANT, or null
+   */
   public String getParticipantName() {
     return _participantName;
   }
 
+  /**
+   * Get the path to the corresponding ZNode
+   * @return a Zookeeper path
+   */
   public String getZkPath() {
     return _zkPath;
   }
 
+  /**
+   * Get the lookup key within the ZNode if it exists
+   * @return the lookup key, or null
+   */
   public String getMapKey() {
     return _mapKey;
   }
 
+  /**
+   * Determine if the key gets a config key or the actual config
+   * @return true if the key corresponds to a config, false if it corresponds to a config key
+   */
   public boolean isFullKey() {
     return _isFullKey;
   }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/IdealState.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/IdealState.java b/helix-core/src/main/java/org/apache/helix/model/IdealState.java
index b0b3960..463369a 100644
--- a/helix-core/src/main/java/org/apache/helix/model/IdealState.java
+++ b/helix-core/src/main/java/org/apache/helix/model/IdealState.java
@@ -33,9 +33,12 @@ import org.apache.helix.ZNRecord;
 import org.apache.log4j.Logger;
 
 /**
- * The ideal states of all partition in a resource
+ * The ideal states of all partitions in a resource
  */
 public class IdealState extends HelixProperty {
+  /**
+   * Properties that are persisted and are queryable for an ideal state
+   */
   public enum IdealStateProperty {
     NUM_PARTITIONS,
     STATE_MODEL_DEF_REF,
@@ -52,6 +55,10 @@ public class IdealState extends HelixProperty {
 
   public static final String QUERY_LIST = "PREFERENCE_LIST_QUERYS";
 
+  /**
+   * Deprecated.
+   * @see {@link RebalanceMode}
+   */
   @Deprecated
   public enum IdealStateModeProperty {
     AUTO,
@@ -59,6 +66,11 @@ public class IdealState extends HelixProperty {
     AUTO_REBALANCE
   }
 
+  /**
+   * The mode used for rebalance. FULL_AUTO does both node location calculation and state
+   * assignment, SEMI_AUTO only does the latter, and CUSTOMIZED does neither. USER_DEFINED
+   * uses a Rebalancer implementation plugged in by the user.
+   */
   public enum RebalanceMode {
     FULL_AUTO,
     SEMI_AUTO,
@@ -69,18 +81,34 @@ public class IdealState extends HelixProperty {
 
   private static final Logger logger = Logger.getLogger(IdealState.class.getName());
 
+  /**
+   * Instantiate an ideal state for a resource
+   * @param resourceName the name of the resource
+   */
   public IdealState(String resourceName) {
     super(resourceName);
   }
 
+  /**
+   * Instantiate an ideal state from a record
+   * @param record ZNRecord corresponding to an ideal state
+   */
   public IdealState(ZNRecord record) {
     super(record);
   }
 
+  /**
+   * Get the associated resource
+   * @return the name of the resource
+   */
   public String getResourceName() {
     return _record.getId();
   }
 
+  /**
+   * Get the rebalance mode of the ideal state
+   * @param mode {@link IdealStateModeProperty}
+   */
   @Deprecated
   public void setIdealStateMode(String mode) {
     _record.setSimpleField(IdealStateProperty.IDEAL_STATE_MODE.toString(), mode);
@@ -88,36 +116,64 @@ public class IdealState extends HelixProperty {
     _record.setEnumField(IdealStateProperty.REBALANCE_MODE.toString(), rebalanceMode);
   }
 
+  /**
+   * Get the rebalance mode of the resource
+   * @param rebalancerType
+   */
   public void setRebalanceMode(RebalanceMode rebalancerType) {
     _record.setEnumField(IdealStateProperty.REBALANCE_MODE.toString(), rebalancerType);
     IdealStateModeProperty idealStateMode = denormalizeRebalanceMode(rebalancerType);
     _record.setEnumField(IdealStateProperty.IDEAL_STATE_MODE.toString(), idealStateMode);
   }
 
+  /**
+   * Get the maximum number of partitions an instance can serve
+   * @return the partition capacity of an instance for this resource, or Integer.MAX_VALUE
+   */
   public int getMaxPartitionsPerInstance() {
     return _record.getIntField(IdealStateProperty.MAX_PARTITIONS_PER_INSTANCE.toString(),
         Integer.MAX_VALUE);
   }
 
+  /**
+   * Define a custom rebalancer that implements {@link Rebalancer}
+   * @param rebalancerClassName the name of the custom rebalancing class
+   */
   public void setRebalancerClassName(String rebalancerClassName) {
     _record
         .setSimpleField(IdealStateProperty.REBALANCER_CLASS_NAME.toString(), rebalancerClassName);
   }
 
+  /**
+   * Get the name of the user-defined rebalancer associated with this resource
+   * @return the rebalancer class name, or null if none is being used
+   */
   public String getRebalancerClassName() {
     return _record.getSimpleField(IdealStateProperty.REBALANCER_CLASS_NAME.toString());
   }
 
+  /**
+   * Set the maximum number of partitions of this resource that an instance can serve
+   * @param max the maximum number of partitions supported
+   */
   public void setMaxPartitionsPerInstance(int max) {
     _record.setIntField(IdealStateProperty.MAX_PARTITIONS_PER_INSTANCE.toString(), max);
   }
 
+  /**
+   * Get the rebalancing mode on this resource
+   * @return {@link IdealStateModeProperty}
+   */
   @Deprecated
   public IdealStateModeProperty getIdealStateMode() {
     return _record.getEnumField(IdealStateProperty.IDEAL_STATE_MODE.toString(),
         IdealStateModeProperty.class, IdealStateModeProperty.AUTO);
   }
 
+  /**
+   * Get the rebalancing mode on this resource
+   * @return {@link RebalanceMode}
+   */
   public RebalanceMode getRebalanceMode() {
     RebalanceMode property =
         _record.getEnumField(IdealStateProperty.REBALANCE_MODE.toString(), RebalanceMode.class,
@@ -129,6 +185,12 @@ public class IdealState extends HelixProperty {
     return property;
   }
 
+  /**
+   * Set the preferred instance placement and state for a partition replica
+   * @param partitionName the replica to set
+   * @param instanceName the assigned instance
+   * @param state the replica state in this instance
+   */
   public void setPartitionState(String partitionName, String instanceName, String state) {
     Map<String, String> mapField = _record.getMapField(partitionName);
     if (mapField == null) {
@@ -137,6 +199,10 @@ public class IdealState extends HelixProperty {
     _record.getMapField(partitionName).put(instanceName, state);
   }
 
+  /**
+   * Get all of the partitions
+   * @return a set of partition names
+   */
   public Set<String> getPartitionSet() {
     if (getRebalanceMode() == RebalanceMode.SEMI_AUTO
         || getRebalanceMode() == RebalanceMode.FULL_AUTO
@@ -150,10 +216,20 @@ public class IdealState extends HelixProperty {
     }
   }
 
+  /**
+   * Get the current mapping of a partition
+   * @param partitionName the name of the partition
+   * @return the instances where the replicas live and the state of each
+   */
   public Map<String, String> getInstanceStateMap(String partitionName) {
     return _record.getMapField(partitionName);
   }
 
+  /**
+   * Get the instances who host replicas of a partition
+   * @param partitionName the partition to look up
+   * @return set of instance names
+   */
   public Set<String> getInstanceSet(String partitionName) {
     if (getRebalanceMode() == RebalanceMode.SEMI_AUTO
         || getRebalanceMode() == RebalanceMode.FULL_AUTO
@@ -180,6 +256,11 @@ public class IdealState extends HelixProperty {
 
   }
 
+  /**
+   * Get the preference list of a partition
+   * @param partitionName the name of the partition
+   * @return a list of instances that can serve replicas of the partition
+   */
   public List<String> getPreferenceList(String partitionName) {
     List<String> instanceStateList = _record.getListField(partitionName);
 
@@ -190,26 +271,51 @@ public class IdealState extends HelixProperty {
     return null;
   }
 
+  /**
+   * Get the state model associated with this resource
+   * @return an identifier of the state model
+   */
   public String getStateModelDefRef() {
     return _record.getSimpleField(IdealStateProperty.STATE_MODEL_DEF_REF.toString());
   }
 
+  /**
+   * Set the state model associated with this resource
+   * @param stateModel state model identifier
+   */
   public void setStateModelDefRef(String stateModel) {
     _record.setSimpleField(IdealStateProperty.STATE_MODEL_DEF_REF.toString(), stateModel);
   }
 
+  /**
+   * Set the number of partitions of this resource
+   * @param numPartitions the number of partitions
+   */
   public void setNumPartitions(int numPartitions) {
     _record.setIntField(IdealStateProperty.NUM_PARTITIONS.toString(), numPartitions);
   }
 
+  /**
+   * Get the number of partitions of this resource
+   * @return the number of partitions
+   */
   public int getNumPartitions() {
     return _record.getIntField(IdealStateProperty.NUM_PARTITIONS.toString(), -1);
   }
 
+  /**
+   * Set the number of replicas for each partition of this resource. There are documented special
+   * values for the replica count, so this is a String.
+   * @param replicas replica count (as a string)
+   */
   public void setReplicas(String replicas) {
     _record.setSimpleField(IdealStateProperty.REPLICAS.toString(), replicas);
   }
 
+  /**
+   * Get the number of replicas for each partition of this resource
+   * @return number of replicas (as a string)
+   */
   public String getReplicas() {
     // HACK: if replica doesn't exists, use the length of the first list field
     // instead
@@ -254,15 +360,27 @@ public class IdealState extends HelixProperty {
     return replica;
   }
 
+  /**
+   * Set the state model factory associated with this resource
+   * @param name state model factory name
+   */
   public void setStateModelFactoryName(String name) {
     _record.setSimpleField(IdealStateProperty.STATE_MODEL_FACTORY_NAME.toString(), name);
   }
 
+  /**
+   * Get the state model factory associated with this resource
+   * @return state model factory name
+   */
   public String getStateModelFactoryName() {
     return _record.getStringField(IdealStateProperty.STATE_MODEL_FACTORY_NAME.toString(),
         HelixConstants.DEFAULT_STATE_MODEL_FACTORY);
   }
 
+  /**
+   * Set the frequency with which to rebalance
+   * @return the rebalancing timer period
+   */
   public int getRebalanceTimerPeriod() {
     return _record.getIntField(IdealStateProperty.REBALANCE_TIMER_PERIOD.toString(), -1);
   }
@@ -309,10 +427,18 @@ public class IdealState extends HelixProperty {
     return true;
   }
 
+  /**
+   * Set a tag to check to enforce assignment to certain instances
+   * @param groupTag the instance group tag
+   */
   public void setInstanceGroupTag(String groupTag) {
     _record.setSimpleField(IdealStateProperty.INSTANCE_GROUP_TAG.toString(), groupTag);
   }
 
+  /**
+   * Check for a tag that will restrict assignment to instances with a matching tag
+   * @return the group tag, or null if none is present
+   */
   public String getInstanceGroupTag() {
     return _record.getSimpleField(IdealStateProperty.INSTANCE_GROUP_TAG.toString());
   }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/InstanceConfig.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/InstanceConfig.java b/helix-core/src/main/java/org/apache/helix/model/InstanceConfig.java
index 62f52a6..eb1c652 100644
--- a/helix-core/src/main/java/org/apache/helix/model/InstanceConfig.java
+++ b/helix-core/src/main/java/org/apache/helix/model/InstanceConfig.java
@@ -23,7 +23,6 @@ import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashSet;
 import java.util.List;
-import java.util.Map;
 import java.util.Set;
 
 import org.apache.helix.HelixProperty;
@@ -34,6 +33,9 @@ import org.apache.log4j.Logger;
  * Instance configurations
  */
 public class InstanceConfig extends HelixProperty {
+  /**
+   * Configurable characteristics of an instance
+   */
   public enum InstanceConfigProperty {
     HELIX_HOST,
     HELIX_PORT,
@@ -44,30 +46,58 @@ public class InstanceConfig extends HelixProperty {
 
   private static final Logger _logger = Logger.getLogger(InstanceConfig.class.getName());
 
+  /**
+   * Instantiate for a specific instance
+   * @param instanceId the instance identifier
+   */
   public InstanceConfig(String instanceId) {
     super(instanceId);
   }
 
+  /**
+   * Instantiate with a pre-populated record
+   * @param record a ZNRecord corresponding to an instance configuration
+   */
   public InstanceConfig(ZNRecord record) {
     super(record);
   }
 
+  /**
+   * Get the host name of the instance
+   * @return the host name
+   */
   public String getHostName() {
     return _record.getSimpleField(InstanceConfigProperty.HELIX_HOST.toString());
   }
 
+  /**
+   * Set the host name of the instance
+   * @param hostName the host name
+   */
   public void setHostName(String hostName) {
     _record.setSimpleField(InstanceConfigProperty.HELIX_HOST.toString(), hostName);
   }
 
+  /**
+   * Get the port that the instance can be reached at
+   * @return the port
+   */
   public String getPort() {
     return _record.getSimpleField(InstanceConfigProperty.HELIX_PORT.toString());
   }
 
+  /**
+   * Set the port that the instance can be reached at
+   * @param port the port
+   */
   public void setPort(String port) {
     _record.setSimpleField(InstanceConfigProperty.HELIX_PORT.toString(), port);
   }
 
+  /**
+   * Get arbitrary tags associated with the instance
+   * @return a list of tags
+   */
   public List<String> getTags() {
     List<String> tags = getRecord().getListField(InstanceConfigProperty.TAG_LIST.toString());
     if (tags == null) {
@@ -76,6 +106,10 @@ public class InstanceConfig extends HelixProperty {
     return tags;
   }
 
+  /**
+   * Add a tag to this instance
+   * @param tag an arbitrary property of the instance
+   */
   public void addTag(String tag) {
     List<String> tags = getRecord().getListField(InstanceConfigProperty.TAG_LIST.toString());
     if (tags == null) {
@@ -87,6 +121,10 @@ public class InstanceConfig extends HelixProperty {
     getRecord().setListField(InstanceConfigProperty.TAG_LIST.toString(), tags);
   }
 
+  /**
+   * Remove a tag from this instance
+   * @param tag a property of this instance
+   */
   public void removeTag(String tag) {
     List<String> tags = getRecord().getListField(InstanceConfigProperty.TAG_LIST.toString());
     if (tags == null) {
@@ -97,6 +135,11 @@ public class InstanceConfig extends HelixProperty {
     }
   }
 
+  /**
+   * Check if an instance contains a tag
+   * @param tag the tag to check
+   * @return true if the instance contains the tag, false otherwise
+   */
   public boolean containsTag(String tag) {
     List<String> tags = getRecord().getListField(InstanceConfigProperty.TAG_LIST.toString());
     if (tags == null) {
@@ -105,14 +148,27 @@ public class InstanceConfig extends HelixProperty {
     return tags.contains(tag);
   }
 
+  /**
+   * Check if this instance is enabled and able to serve replicas
+   * @return true if enabled, false if disabled
+   */
   public boolean getInstanceEnabled() {
     return _record.getBooleanField(InstanceConfigProperty.HELIX_ENABLED.toString(), true);
   }
 
+  /**
+   * Set the enabled state of the instance
+   * @param enabled true to enable, false to disable
+   */
   public void setInstanceEnabled(boolean enabled) {
     _record.setBooleanField(InstanceConfigProperty.HELIX_ENABLED.toString(), enabled);
   }
 
+  /**
+   * Check if this instance is enabled for a given partition
+   * @param partition the partition name to check
+   * @return true if the instance is enabled for the partition, false otherwise
+   */
   public boolean getInstanceEnabledForPartition(String partition) {
     // Map<String, String> disabledPartitionMap =
     // _record.getMapField(InstanceConfigProperty.HELIX_DISABLED_PARTITION.toString());
@@ -125,11 +181,19 @@ public class InstanceConfig extends HelixProperty {
     }
   }
 
+  /**
+   * Get the partitions disabled by this instance
+   * @return a list of partition names
+   */
   public List<String> getDisabledPartitions() {
     return _record.getListField(InstanceConfigProperty.HELIX_DISABLED_PARTITION.toString());
-
   }
 
+  /**
+   * Set the enabled state for a partition on this instance
+   * @param partitionName the partition to set
+   * @param enabled true to enable, false to disable
+   */
   public void setInstanceEnabledForPartition(String partitionName, boolean enabled) {
     List<String> list =
         _record.getListField(InstanceConfigProperty.HELIX_DISABLED_PARTITION.toString());
@@ -166,6 +230,10 @@ public class InstanceConfig extends HelixProperty {
     return getId().hashCode();
   }
 
+  /**
+   * Get the name of this instance
+   * @return the instance name
+   */
   public String getInstanceName() {
     return _record.getId();
   }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/LeaderHistory.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/LeaderHistory.java b/helix-core/src/main/java/org/apache/helix/model/LeaderHistory.java
index 8e57143..d57fb52 100644
--- a/helix-core/src/main/java/org/apache/helix/model/LeaderHistory.java
+++ b/helix-core/src/main/java/org/apache/helix/model/LeaderHistory.java
@@ -25,6 +25,9 @@ import java.util.List;
 import org.apache.helix.HelixProperty;
 import org.apache.helix.ZNRecord;
 
+/**
+ * The history of instances that have served as the leader controller
+ */
 public class LeaderHistory extends HelixProperty {
   private final static int HISTORY_SIZE = 8;
 
@@ -38,8 +41,8 @@ public class LeaderHistory extends HelixProperty {
 
   /**
    * Save up to HISTORY_SIZE number of leaders in FIFO order
-   * @param clusterName
-   * @param instanceName
+   * @param clusterName the cluster the instance leads
+   * @param instanceName the name of the leader instance
    */
   public void updateHistory(String clusterName, String instanceName) {
     List<String> list = _record.getListField(clusterName);

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/LiveInstance.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/LiveInstance.java b/helix-core/src/main/java/org/apache/helix/model/LiveInstance.java
index 584f5b9..75e0cf3 100644
--- a/helix-core/src/main/java/org/apache/helix/model/LiveInstance.java
+++ b/helix-core/src/main/java/org/apache/helix/model/LiveInstance.java
@@ -24,9 +24,12 @@ import org.apache.helix.ZNRecord;
 import org.apache.log4j.Logger;
 
 /**
- * Instance that connects to zookeeper
+ * Instance that connects to zookeeper (stored ephemerally)
  */
 public class LiveInstance extends HelixProperty {
+  /**
+   * Saved properties of a live instance
+   */
   public enum LiveInstanceProperty {
     SESSION_ID,
     HELIX_VERSION,
@@ -36,50 +39,98 @@ public class LiveInstance extends HelixProperty {
 
   private static final Logger _logger = Logger.getLogger(LiveInstance.class.getName());
 
+  /**
+   * Instantiate with an instance identifier
+   * @param id instance identifier
+   */
   public LiveInstance(String id) {
     super(id);
   }
 
+  /**
+   * Instantiate with a pre-populated record
+   * @param record ZNRecord corresponding to a live instance
+   */
   public LiveInstance(ZNRecord record) {
     super(record);
   }
 
+  /**
+   * Set the session that this instance corresponds to
+   * @param sessionId session identifier
+   */
   public void setSessionId(String sessionId) {
     _record.setSimpleField(LiveInstanceProperty.SESSION_ID.toString(), sessionId);
   }
 
+  /**
+   * Get the session that this instance corresponds to
+   * @return session identifier
+   */
   public String getSessionId() {
     return _record.getSimpleField(LiveInstanceProperty.SESSION_ID.toString());
   }
 
+  /**
+   * Get the name of this instance
+   * @return the instance name
+   */
   public String getInstanceName() {
     return _record.getId();
   }
 
+  /**
+   * Get the version of Helix that this instance is running
+   * @return the version
+   */
   public String getHelixVersion() {
     return _record.getSimpleField(LiveInstanceProperty.HELIX_VERSION.toString());
   }
 
+  /**
+   * Set the version of Helix that this instance is running
+   * @param helixVersion the version
+   */
   public void setHelixVersion(String helixVersion) {
     _record.setSimpleField(LiveInstanceProperty.HELIX_VERSION.toString(), helixVersion);
   }
 
+  /**
+   * Get an identifier that represents the instance and where it is located
+   * @return identifier, e.g. process_id@host
+   */
   public String getLiveInstance() {
     return _record.getSimpleField(LiveInstanceProperty.LIVE_INSTANCE.toString());
   }
 
-  public void setLiveInstance(String leader) {
-    _record.setSimpleField(LiveInstanceProperty.LIVE_INSTANCE.toString(), leader);
+  /**
+   * Set an identifier that represents the process
+   * @param liveInstance process identifier, e.g. process_id@host
+   */
+  public void setLiveInstance(String liveInstance) {
+    _record.setSimpleField(LiveInstanceProperty.LIVE_INSTANCE.toString(), liveInstance);
   }
 
+  /**
+   * Get the last modified time of this live instance
+   * @return UNIX timestamp
+   */
   public long getModifiedTime() {
     return _record.getModifiedTime();
   }
 
+  /**
+   * Get a web service URL where ZK properties can be transferred to
+   * @return a fully-qualified URL
+   */
   public String getWebserviceUrl() {
     return _record.getSimpleField(LiveInstanceProperty.ZKPROPERTYTRANSFERURL.toString());
   }
 
+  /**
+   * Set a web service URL where ZK properties can be transferred to
+   * @param url a fully-qualified URL
+   */
   public void setWebserviceUrl(String url) {
     _record.setSimpleField(LiveInstanceProperty.ZKPROPERTYTRANSFERURL.toString(), url);
   }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/Message.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/Message.java b/helix-core/src/main/java/org/apache/helix/model/Message.java
index 4a35152..d599b8b 100644
--- a/helix-core/src/main/java/org/apache/helix/model/Message.java
+++ b/helix-core/src/main/java/org/apache/helix/model/Message.java
@@ -26,7 +26,6 @@ import java.util.Date;
 import java.util.List;
 import java.util.Map;
 import java.util.UUID;
-import java.util.concurrent.atomic.AtomicInteger;
 
 import org.apache.helix.HelixException;
 import org.apache.helix.HelixProperty;
@@ -36,10 +35,12 @@ import org.apache.helix.ZNRecord;
 import org.apache.helix.PropertyKey.Builder;
 
 /**
- * 
+ * Messages sent internally among nodes in the system to respond to changes in state.
  */
-
 public class Message extends HelixProperty {
+  /**
+   * The major categories of messages that are sent
+   */
   public enum MessageType {
     STATE_TRANSITION,
     SCHEDULER_MSG,
@@ -50,6 +51,9 @@ public class Message extends HelixProperty {
     PARTICIPANT_ERROR_REPORT
   };
 
+  /**
+   * Properties attached to Messages
+   */
   public enum Attributes {
     MSG_ID,
     SRC_SESSION_ID,
@@ -79,12 +83,18 @@ public class Message extends HelixProperty {
     INNER_MESSAGE
   }
 
+  /**
+   * The current processed state of the message
+   */
   public enum MessageState {
     NEW,
     READ, // not used
     UNPROCESSABLE // get exception when create handler
   }
 
+  /**
+   * Compares the creation time of two Messages
+   */
   public static final Comparator<Message> CREATE_TIME_COMPARATOR = new Comparator<Message>() {
     @Override
     public int compare(Message m1, Message m2) {
@@ -96,10 +106,20 @@ public class Message extends HelixProperty {
 
   // AtomicInteger _groupMsgCountDown = new AtomicInteger(1);
 
+  /**
+   * Instantiate a message
+   * @param type the message category
+   * @param msgId unique message identifier
+   */
   public Message(MessageType type, String msgId) {
     this(type.toString(), msgId);
   }
 
+  /**
+   * Instantiate a message
+   * @param type {@link MessageType} as a string or a custom message type
+   * @param msgId unique message identifier
+   */
   public Message(String type, String msgId) {
     super(new ZNRecord(msgId));
     _record.setSimpleField(Attributes.MSG_TYPE.toString(), type);
@@ -108,6 +128,10 @@ public class Message extends HelixProperty {
     _record.setLongField(Attributes.CREATE_TIMESTAMP.toString(), new Date().getTime());
   }
 
+  /**
+   * Instantiate a message
+   * @param record a ZNRecord corresponding to a message
+   */
   public Message(ZNRecord record) {
     super(record);
     if (getMsgState() == null) {
@@ -118,203 +142,400 @@ public class Message extends HelixProperty {
     }
   }
 
+  /**
+   * Set the time that the message was created
+   * @param timestamp a UNIX timestamp
+   */
   public void setCreateTimeStamp(long timestamp) {
     _record.setLongField(Attributes.CREATE_TIMESTAMP.toString(), timestamp);
   }
 
+  /**
+   * Instantiate a message with a new id
+   * @param record a ZNRecord corresponding to a message
+   * @param id unique message identifier
+   */
   public Message(ZNRecord record, String id) {
     super(new ZNRecord(record, id));
     setMsgId(id);
   }
 
+  /**
+   * Set a subtype of the message
+   * @param subType name of the subtype
+   */
   public void setMsgSubType(String subType) {
     _record.setSimpleField(Attributes.MSG_SUBTYPE.toString(), subType);
   }
 
+  /**
+   * Get the subtype of the message
+   * @return the subtype name, or null
+   */
   public String getMsgSubType() {
     return _record.getSimpleField(Attributes.MSG_SUBTYPE.toString());
   }
 
+  /**
+   * Set the type of this message
+   * @param type {@link MessageType}
+   */
   void setMsgType(MessageType type) {
     _record.setSimpleField(Attributes.MSG_TYPE.toString(), type.toString());
   }
 
+  /**
+   * Get the type of this message
+   * @return String {@link MessageType} or a custom message type
+   */
   public String getMsgType() {
     return _record.getSimpleField(Attributes.MSG_TYPE.toString());
   }
 
+  /**
+   * Get the session identifier of the destination node
+   * @return session identifier
+   */
   public String getTgtSessionId() {
     return _record.getSimpleField(Attributes.TGT_SESSION_ID.toString());
   }
 
+  /**
+   * Set the session identifier of the destination node
+   * @param tgtSessionId session identifier
+   */
   public void setTgtSessionId(String tgtSessionId) {
     _record.setSimpleField(Attributes.TGT_SESSION_ID.toString(), tgtSessionId);
   }
 
+  /**
+   * Get the session identifier of the source node
+   * @return session identifier
+   */
   public String getSrcSessionId() {
     return _record.getSimpleField(Attributes.SRC_SESSION_ID.toString());
   }
 
+  /**
+   * Set the session identifier of the source node
+   * @param srcSessionId session identifier
+   */
   public void setSrcSessionId(String srcSessionId) {
     _record.setSimpleField(Attributes.SRC_SESSION_ID.toString(), srcSessionId);
   }
 
+  /**
+   * Get the session identifier of the node that executes the message
+   * @return session identifier
+   */
   public String getExecutionSessionId() {
     return _record.getSimpleField(Attributes.EXE_SESSION_ID.toString());
   }
 
+  /**
+   * Set the session identifier of the node that executes the message
+   * @param exeSessionId session identifier
+   */
   public void setExecuteSessionId(String exeSessionId) {
     _record.setSimpleField(Attributes.EXE_SESSION_ID.toString(), exeSessionId);
   }
 
+  /**
+   * Get the instance from which the message originated
+   * @return the instance name
+   */
   public String getMsgSrc() {
     return _record.getSimpleField(Attributes.SRC_NAME.toString());
   }
 
+  /**
+   * Set the type of instance that the source node is
+   * @param type {@link InstanceType}
+   */
   public void setSrcInstanceType(InstanceType type) {
     _record.setEnumField(Attributes.SRC_INSTANCE_TYPE.toString(), type);
   }
 
+  /**
+   * Get the type of instance that the source is
+   * @return {@link InstanceType}
+   */
   public InstanceType getSrcInstanceType() {
     return _record.getEnumField(Attributes.SRC_INSTANCE_TYPE.toString(), InstanceType.class,
         InstanceType.PARTICIPANT);
   }
 
+  /**
+   * Set the name of the source instance
+   * @param msgSrc instance name
+   */
   public void setSrcName(String msgSrc) {
     _record.setSimpleField(Attributes.SRC_NAME.toString(), msgSrc);
   }
 
+  /**
+   * Get the name of the target instance
+   * @return instance name
+   */
   public String getTgtName() {
     return _record.getSimpleField(Attributes.TGT_NAME.toString());
   }
 
+  /**
+   * Set the current state of the message
+   * @param msgState {@link MessageState}
+   */
   public void setMsgState(MessageState msgState) { // HACK: The "tolowerCase()" call is to make the
                                                    // change backward compatible
     _record.setSimpleField(Attributes.MSG_STATE.toString(), msgState.toString().toLowerCase());
   }
 
+  /**
+   * Get the current state of the message
+   * @return {@link MessageState}
+   */
   public MessageState getMsgState() {
     // HACK: The "toUpperCase()" call is to make the change backward compatible
     return MessageState.valueOf(_record.getSimpleField(Attributes.MSG_STATE.toString())
         .toUpperCase());
   }
 
+  /**
+   * Set the name of the partition this message concerns
+   * @param partitionName
+   */
   public void setPartitionName(String partitionName) {
     _record.setSimpleField(Attributes.PARTITION_NAME.toString(), partitionName);
   }
 
+  /**
+   * Get the unique identifier of this message
+   * @return message identifier
+   */
   public String getMsgId() {
     return _record.getSimpleField(Attributes.MSG_ID.toString());
   }
 
+  /**
+   * Set the unique identifier of this message
+   * @param msgId message identifier
+   */
   public void setMsgId(String msgId) {
     _record.setSimpleField(Attributes.MSG_ID.toString(), msgId);
   }
 
+  /**
+   * Set the "from state" for transition-related messages
+   * @param state the state name
+   */
   public void setFromState(String state) {
     _record.setSimpleField(Attributes.FROM_STATE.toString(), state);
   }
 
+  /**
+   * Get the "from-state" for transition-related messages
+   * @return state name, or null for other message types
+   */
   public String getFromState() {
     return _record.getSimpleField(Attributes.FROM_STATE.toString());
   }
 
+  /**
+   * Set the "to state" for transition-related messages
+   * @param state the state name
+   */
   public void setToState(String state) {
     _record.setSimpleField(Attributes.TO_STATE.toString(), state);
   }
 
+  /**
+   * Get the "to state" for transition-related messages
+   * @return state name, or null for other message types
+   */
   public String getToState() {
     return _record.getSimpleField(Attributes.TO_STATE.toString());
   }
 
+  /**
+   * Set the instance for which this message is targeted
+   * @param msgTgt instance name
+   */
   public void setTgtName(String msgTgt) {
     _record.setSimpleField(Attributes.TGT_NAME.toString(), msgTgt);
   }
 
+  /**
+   * Check for debug mode
+   * @return true if enabled, false if disabled
+   */
   public Boolean getDebug() {
     return false;
   }
 
+  /**
+   * Get the generation that this message corresponds to
+   * @return generation number
+   */
   public Integer getGeneration() {
     return 1;
   }
 
+  /**
+   * Set the resource associated with this message
+   * @param resourceName resource name to set
+   */
   public void setResourceName(String resourceName) {
     _record.setSimpleField(Attributes.RESOURCE_NAME.toString(), resourceName);
   }
 
+  /**
+   * Get the resource associated with this message
+   * @return resource name
+   */
   public String getResourceName() {
     return _record.getSimpleField(Attributes.RESOURCE_NAME.toString());
   }
 
+  /**
+   * Get the resource partition associated with this message
+   * @return partition name
+   */
   public String getPartitionName() {
     return _record.getSimpleField(Attributes.PARTITION_NAME.toString());
   }
 
+  /**
+   * Get the state model definition name
+   * @return a String reference to the state model definition, e.g. "MasterSlave"
+   */
   public String getStateModelDef() {
     return _record.getSimpleField(Attributes.STATE_MODEL_DEF.toString());
   }
 
+  /**
+   * Set the state model definition name
+   * @param stateModelDefName a reference to the state model definition, e.g. "MasterSlave"
+   */
   public void setStateModelDef(String stateModelDefName) {
     _record.setSimpleField(Attributes.STATE_MODEL_DEF.toString(), stateModelDefName);
   }
 
+  /**
+   * Set the time that this message was read
+   * @param time UNIX timestamp
+   */
   public void setReadTimeStamp(long time) {
     _record.setLongField(Attributes.READ_TIMESTAMP.toString(), time);
   }
 
+  /**
+   * Set the time that the instance executes tasks as instructed by this message
+   * @param time UNIX timestamp
+   */
   public void setExecuteStartTimeStamp(long time) {
     _record.setLongField(Attributes.EXECUTE_START_TIMESTAMP.toString(), time);
   }
 
+  /**
+   * Get the time that this message was read
+   * @return UNIX timestamp
+   */
   public long getReadTimeStamp() {
     return _record.getLongField(Attributes.READ_TIMESTAMP.toString(), 0L);
   }
 
+  /**
+   * Get the time that execution occurred as a result of this message
+   * @return UNIX timestamp
+   */
   public long getExecuteStartTimeStamp() {
     return _record.getLongField(Attributes.EXECUTE_START_TIMESTAMP.toString(), 0L);
   }
 
+  /**
+   * Get the time that this message was created
+   * @return UNIX timestamp
+   */
   public long getCreateTimeStamp() {
     return _record.getLongField(Attributes.CREATE_TIMESTAMP.toString(), 0L);
   }
 
+  /**
+   * Set a unique identifier that others can use to refer to this message in replies
+   * @param correlationId a unique identifier, usually randomly generated
+   */
   public void setCorrelationId(String correlationId) {
     _record.setSimpleField(Attributes.CORRELATION_ID.toString(), correlationId);
   }
 
+  /**
+   * Get the unique identifier attached to this message for reply matching
+   * @return the correlation identifier
+   */
   public String getCorrelationId() {
     return _record.getSimpleField(Attributes.CORRELATION_ID.toString());
   }
 
+  /**
+   * Get the time to wait before stopping execution of this message
+   * @return the timeout in ms, or -1 indicating no timeout
+   */
   public int getExecutionTimeout() {
     return _record.getIntField(Attributes.TIMEOUT.toString(), -1);
   }
 
+  /**
+   * Set the time to wait before stopping execution of this message
+   * @param timeout the timeout in ms, or -1 indicating no timeout
+   */
   public void setExecutionTimeout(int timeout) {
     _record.setIntField(Attributes.TIMEOUT.toString(), timeout);
   }
 
+  /**
+   * Set the number of times to retry message handling on timeouts
+   * @param retryCount maximum number of retries
+   */
   public void setRetryCount(int retryCount) {
     _record.setIntField(Attributes.RETRY_COUNT.toString(), retryCount);
   }
 
+  /**
+   * Get the number of times to retry message handling on timeouts
+   * @return maximum number of retries
+   */
   public int getRetryCount() {
     return _record.getIntField(Attributes.RETRY_COUNT.toString(), 0);
   }
 
+  /**
+   * Get the results of message execution
+   * @return map of result property and value pairs
+   */
   public Map<String, String> getResultMap() {
     return _record.getMapField(Attributes.MESSAGE_RESULT.toString());
   }
 
+  /**
+   * Set the results of message execution
+   * @param resultMap map of result property and value pairs
+   */
   public void setResultMap(Map<String, String> resultMap) {
     _record.setMapField(Attributes.MESSAGE_RESULT.toString(), resultMap);
   }
 
+  /**
+   * Get the state model factory associated with this message
+   * @return the name of the factory
+   */
   public String getStateModelFactoryName() {
     return _record.getSimpleField(Attributes.STATE_MODEL_FACTORY_NAME.toString());
   }
 
+  /**
+   * Set the state model factory associated with this message
+   * @param factoryName the name of the factory
+   */
   public void setStateModelFactoryName(String factoryName) {
     _record.setSimpleField(Attributes.STATE_MODEL_FACTORY_NAME.toString(), factoryName);
   }
@@ -332,14 +553,31 @@ public class Message extends HelixProperty {
     }
   }
 
+  /**
+   * Add or change a message attribute
+   * @param attr {@link Attributes} attribute name
+   * @param val attribute value
+   */
   public void setAttribute(Attributes attr, String val) {
     _record.setSimpleField(attr.toString(), val);
   }
 
+  /**
+   * Get the value of an attribute
+   * @param attr {@link Attribute}
+   * @return attribute value
+   */
   public String getAttribute(Attributes attr) {
     return _record.getSimpleField(attr.toString());
   }
 
+  /**
+   * Create a reply based on an incoming message
+   * @param srcMessage the incoming message
+   * @param instanceName the instance that is the source of the reply
+   * @param taskResultMap the result of executing the incoming message
+   * @return the reply Message
+   */
   public static Message createReplyMessage(Message srcMessage, String instanceName,
       Map<String, String> taskResultMap) {
     if (srcMessage.getCorrelationId() == null) {
@@ -360,6 +598,10 @@ public class Message extends HelixProperty {
     return replyMessage;
   }
 
+  /**
+   * Add a partition to a collection of partitions associated with this message
+   * @param partitionName the partition name to add
+   */
   public void addPartitionName(String partitionName) {
     if (_record.getListField(Attributes.PARTITION_NAME.toString()) == null) {
       _record.setListField(Attributes.PARTITION_NAME.toString(), new ArrayList<String>());
@@ -371,6 +613,10 @@ public class Message extends HelixProperty {
     }
   }
 
+  /**
+   * Get a list of partitions associated with this message
+   * @return list of partition names
+   */
   public List<String> getPartitionNames() {
     List<String> partitionNames = _record.getListField(Attributes.PARTITION_NAME.toString());
     if (partitionNames == null) {
@@ -390,10 +636,20 @@ public class Message extends HelixProperty {
   // _groupMsgCountDown = countDown;
   // }
 
+  /**
+   * Check if this message is targetted for a controller
+   * @return true if this is a controller message, false otherwise
+   */
   public boolean isControlerMsg() {
     return getTgtName().equalsIgnoreCase("controller");
   }
 
+  /**
+   * Get the {@link PropertyKey} for this message
+   * @param keyBuilder PropertyKey Builder
+   * @param instanceName target instance
+   * @return message PropertyKey
+   */
   public PropertyKey getKey(Builder keyBuilder, String instanceName) {
     if (isControlerMsg()) {
       return keyBuilder.controllerMessage(getId());

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/Partition.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/Partition.java b/helix-core/src/main/java/org/apache/helix/model/Partition.java
index 0c8b9aa..1d694ab 100644
--- a/helix-core/src/main/java/org/apache/helix/model/Partition.java
+++ b/helix-core/src/main/java/org/apache/helix/model/Partition.java
@@ -20,15 +20,23 @@ package org.apache.helix.model;
  */
 
 /**
- * The name of a resource
+ * A distinct partition of a resource
  */
 public class Partition {
   private final String _partitionName;
 
+  /**
+   * Get the name of the partition, unique for the resource
+   * @return partition name
+   */
   public String getPartitionName() {
     return _partitionName;
   }
 
+  /**
+   * Instantiate with a partition name
+   * @param partitionName unique partition name within a resource
+   */
   public Partition(String partitionName) {
     this._partitionName = partitionName;
   }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/PauseSignal.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/PauseSignal.java b/helix-core/src/main/java/org/apache/helix/model/PauseSignal.java
index 4c02546..1d6706a 100644
--- a/helix-core/src/main/java/org/apache/helix/model/PauseSignal.java
+++ b/helix-core/src/main/java/org/apache/helix/model/PauseSignal.java
@@ -22,11 +22,22 @@ package org.apache.helix.model;
 import org.apache.helix.HelixProperty;
 import org.apache.helix.ZNRecord;
 
+/**
+ * Represent a pause in the cluster
+ */
 public class PauseSignal extends HelixProperty {
+  /**
+   * Instantiate with an identifier
+   * @param id pause signal identifier
+   */
   public PauseSignal(String id) {
     super(id);
   }
 
+  /**
+   * Instantiate with a pre-populated record
+   * @param record ZNRecord with fields corresponding to a pause
+   */
   public PauseSignal(ZNRecord record) {
     super(record);
   }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/PersistentStats.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/PersistentStats.java b/helix-core/src/main/java/org/apache/helix/model/PersistentStats.java
index e028e66..9cd1934 100644
--- a/helix-core/src/main/java/org/apache/helix/model/PersistentStats.java
+++ b/helix-core/src/main/java/org/apache/helix/model/PersistentStats.java
@@ -25,9 +25,15 @@ import org.apache.helix.HelixProperty;
 import org.apache.helix.ZNRecord;
 import org.apache.log4j.Logger;
 
+/**
+ * Statistics for an instance
+ */
 public class PersistentStats extends HelixProperty {
   private static final Logger _logger = Logger.getLogger(PersistentStats.class.getName());
 
+  /**
+   * High-level properties to provide context for these statistics
+   */
   public enum PersistentStatsProperty {
     SESSION_ID,
     FIELDS
@@ -35,12 +41,23 @@ public class PersistentStats extends HelixProperty {
 
   // private final ZNRecord _record;
 
+  /**
+   * The name of the statistics ZNode
+   */
   public final static String nodeName = "PersistentStats";
 
+  /**
+   * Instantiate with an identifier
+   * @param id record identifier
+   */
   public PersistentStats(String id) {
     super(id);
   }
 
+  /**
+   * Instantiate with a pre-populated record
+   * @param record ZNRecord with fields corresponding to persistent stats
+   */
   public PersistentStats(ZNRecord record) {
     // _record = record;
     super(record);
@@ -54,14 +71,26 @@ public class PersistentStats extends HelixProperty {
    * }
    */
 
+  /**
+   * Set the session corresponding to these statistics
+   * @param sessionId session id
+   */
   public void setSessionId(String sessionId) {
     _record.setSimpleField(PersistentStatsProperty.SESSION_ID.toString(), sessionId);
   }
 
+  /**
+   * Get the session corresponding to these statistics
+   * @return session id
+   */
   public String getSessionId() {
     return _record.getSimpleField(PersistentStatsProperty.SESSION_ID.toString());
   }
 
+  /**
+   * Get the instance for which these stats have been collected
+   * @return instance name
+   */
   public String getInstanceName() {
     return _record.getId();
   }
@@ -73,10 +102,19 @@ public class PersistentStats extends HelixProperty {
    * }
    */
 
+  /**
+   * Get all the statistics currently stored
+   * @return map of (stat name, stat attribute, value)
+   */
   public Map<String, Map<String, String>> getMapFields() {
     return _record.getMapFields();
   }
 
+  /**
+   * Get a specific statistic
+   * @param statName the statistic to look up
+   * @return map of (stat attribute, value)
+   */
   public Map<String, String> getStatFields(String statName) {
     return _record.getMapField(statName);
   }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/Resource.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/Resource.java b/helix-core/src/main/java/org/apache/helix/model/Resource.java
index b6ffea7..1544514 100644
--- a/helix-core/src/main/java/org/apache/helix/model/Resource.java
+++ b/helix-core/src/main/java/org/apache/helix/model/Resource.java
@@ -27,7 +27,7 @@ import org.apache.helix.HelixConstants;
 import org.apache.log4j.Logger;
 
 /**
- * A resource contains a set of partitions
+ * A resource contains a set of partitions and its replicas are managed by a state model
  */
 public class Resource {
   private static Logger LOG = Logger.getLogger(Resource.class);
@@ -39,19 +39,35 @@ public class Resource {
   private int _bucketSize = 0;
   private boolean _batchMessageMode = false;
 
+  /**
+   * Instantiate a resource by its name
+   * @param resourceName the name of the resource that identifies it
+   */
   public Resource(String resourceName) {
     this._resourceName = resourceName;
     this._partitionMap = new LinkedHashMap<String, Partition>();
   }
 
+  /**
+   * Get the state model definition managing this resource
+   * @return a reference to the state model definition
+   */
   public String getStateModelDefRef() {
     return _stateModelDefRef;
   }
 
+  /**
+   * Set the state model definition managing this resource
+   * @param stateModelDefRef a reference to the state model definition
+   */
   public void setStateModelDefRef(String stateModelDefRef) {
     _stateModelDefRef = stateModelDefRef;
   }
 
+  /**
+   * Set the state model factory for this resource
+   * @param factoryName the name of the state model factory
+   */
   public void setStateModelFactoryName(String factoryName) {
     if (factoryName == null) {
       _stateModelFactoryName = HelixConstants.DEFAULT_STATE_MODEL_FACTORY;
@@ -60,38 +76,75 @@ public class Resource {
     }
   }
 
+  /**
+   * Get the state model factory for this resource
+   * @return the state model factory name
+   */
   public String getStateModelFactoryname() {
     return _stateModelFactoryName;
   }
 
+  /**
+   * Get the resource name
+   * @return the name of the resource, should be unique
+   */
   public String getResourceName() {
     return _resourceName;
   }
 
+  /**
+   * Get the partitions of this resource
+   * @return {@link Partition} objects
+   */
   public Collection<Partition> getPartitions() {
     return _partitionMap.values();
   }
 
+  /**
+   * Add a partition to this resource
+   * @param partitionName the name of the partition
+   */
   public void addPartition(String partitionName) {
     _partitionMap.put(partitionName, new Partition(partitionName));
   }
 
+  /**
+   * Get a resource partition by name
+   * @param partitionName partition name
+   * @return the partition, or the name is not present
+   */
   public Partition getPartition(String partitionName) {
     return _partitionMap.get(partitionName);
   }
 
+  /**
+   * Get the bucket size of this resource
+   * @return the bucket size, or 0 if not specified
+   */
   public int getBucketSize() {
     return _bucketSize;
   }
 
+  /**
+   * Set the bucket size of this resource
+   * @param bucketSize the bucket size, or 0 to disable bucketizing
+   */
   public void setBucketSize(int bucketSize) {
     _bucketSize = bucketSize;
   }
 
+  /**
+   * Set whether or not messages for this resource should be batch processed
+   * @param mode true to batch process, false to disable batch processing
+   */
   public void setBatchMessageMode(boolean mode) {
     _batchMessageMode = mode;
   }
 
+  /**
+   * Get the batch message processing mode
+   * @return true if enabled, false if disabled
+   */
   public boolean getBatchMessageMode() {
     return _batchMessageMode;
   }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/StateModelDefinition.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/StateModelDefinition.java b/helix-core/src/main/java/org/apache/helix/model/StateModelDefinition.java
index 31224d5..7f08b6f 100644
--- a/helix-core/src/main/java/org/apache/helix/model/StateModelDefinition.java
+++ b/helix-core/src/main/java/org/apache/helix/model/StateModelDefinition.java
@@ -27,7 +27,6 @@ import java.util.List;
 import java.util.Map;
 import java.util.TreeMap;
 
-import org.apache.helix.HelixConstants;
 import org.apache.helix.HelixDefinedState;
 import org.apache.helix.HelixProperty;
 import org.apache.helix.ZNRecord;
@@ -75,6 +74,10 @@ public class StateModelDefinition extends HelixProperty {
    */
   private final Map<String, Map<String, String>> _stateTransitionTable;
 
+  /**
+   * Instantiate from a pre-populated record
+   * @param record ZNRecord representing a state model definition
+   */
   public StateModelDefinition(ZNRecord record) {
     super(record);
 
@@ -120,9 +123,9 @@ public class StateModelDefinition extends HelixProperty {
   /**
    * add transitions involving helix-defines states
    * these transitions need not to be specified in state-model-definition
-   * @param from
-   * @param to
-   * @param next
+   * @param from source state
+   * @param to destination state
+   * @param next intermediate state to reach the destination
    */
   void addDefaultTransition(String from, String to, String next) {
     if (!_stateTransitionTable.containsKey(from)) {
@@ -134,14 +137,28 @@ public class StateModelDefinition extends HelixProperty {
     }
   }
 
+  /**
+   * Get an ordered priority list of transitions
+   * @return transitions in the form SRC-DEST, the first of which is highest priority
+   */
   public List<String> getStateTransitionPriorityList() {
     return _stateTransitionPriorityList;
   }
 
+  /**
+   * Get an ordered priority list of states
+   * @return state names, the first of which is highest priority
+   */
   public List<String> getStatesPriorityList() {
     return _statesPriorityList;
   }
 
+  /**
+   * Get the intermediate state required to transition from one state to the other
+   * @param fromState the source
+   * @param toState the destination
+   * @return the intermediate state
+   */
   public String getNextStateForTransition(String fromState, String toState) {
     Map<String, String> map = _stateTransitionTable.get(fromState);
     if (map != null) {
@@ -150,12 +167,21 @@ public class StateModelDefinition extends HelixProperty {
     return null;
   }
 
+  /**
+   * Get the starting state in the model
+   * @return name of the initial state
+   */
   public String getInitialState() {
     // return _record.getSimpleField(StateModelDefinitionProperty.INITIAL_STATE
     // .toString());
     return _initialState;
   }
 
+  /**
+   * Number of instances that can be in each state
+   * @param state the state name
+   * @return maximum instance count per state, can be "N" or "R"
+   */
   public String getNumInstancesPerState(String state) {
     return _statesCountMap.get(state);
   }
@@ -176,8 +202,7 @@ public class StateModelDefinition extends HelixProperty {
 
   // TODO move this to model.builder package, refactor StateModelConfigGenerator to use this
   /**
-   * 
-   *
+   * Construct a state model
    */
   public static class Builder {
     private final String _statemodelName;
@@ -186,6 +211,10 @@ public class StateModelDefinition extends HelixProperty {
     Map<Transition, Integer> transitionMap;
     Map<String, String> stateConstraintMap;
 
+    /**
+     * Start building a state model with a name
+     * @param name state model name
+     */
     public Builder(String name) {
       this._statemodelName = name;
       statesMap = new HashMap<String, Integer>();
@@ -232,20 +261,34 @@ public class StateModelDefinition extends HelixProperty {
      * constraint. The transitions are first sorted based on priority and
      * transitions are selected in a greedy way until the constriants are not
      * violated.
-     * @param fromState
-     * @param toState
-     * @param priority
+     * @param fromState source
+     * @param toState destination
+     * @param priority priority, higher value is higher priority
+     * @return Builder
      */
     public Builder addTransition(String fromState, String toState, int priority) {
       transitionMap.put(new Transition(fromState, toState), priority);
       return this;
     }
 
+    /**
+     * Add a state transition with maximal priority value
+     * @see #addTransition(String, String, int)
+     * @param fromState
+     * @param toState
+     * @return Builder
+     */
     public Builder addTransition(String fromState, String toState) {
       addTransition(fromState, toState, Integer.MAX_VALUE);
       return this;
     }
 
+    /**
+     * Set a maximum for replicas in this state
+     * @param state state name
+     * @param upperBound maximum
+     * @return Builder
+     */
     public Builder upperBound(String state, int upperBound) {
       stateConstraintMap.put(state, String.valueOf(upperBound));
       return this;
@@ -263,12 +306,17 @@ public class StateModelDefinition extends HelixProperty {
      * the change the bounds.
      * @param state
      * @param bound
+     * @return Builder
      */
     public Builder dynamicUpperBound(String state, String bound) {
       stateConstraintMap.put(state, bound);
       return this;
     }
 
+    /**
+     * Create a StateModelDefinition from this Builder
+     * @return StateModelDefinition
+     */
     public StateModelDefinition build() {
       ZNRecord record = new ZNRecord(_statemodelName);
       ArrayList<String> statePriorityList = new ArrayList<String>(statesMap.keySet());

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/StatusUpdate.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/StatusUpdate.java b/helix-core/src/main/java/org/apache/helix/model/StatusUpdate.java
index d65a333..f4857ee 100644
--- a/helix-core/src/main/java/org/apache/helix/model/StatusUpdate.java
+++ b/helix-core/src/main/java/org/apache/helix/model/StatusUpdate.java
@@ -22,8 +22,15 @@ package org.apache.helix.model;
 import org.apache.helix.HelixProperty;
 import org.apache.helix.ZNRecord;
 
+/**
+ * Wraps updates to Helix constructs, e.g. state transitions and controller task statuses
+ */
 public class StatusUpdate extends HelixProperty {
 
+  /**
+   * Instantiate with a pre-populated record
+   * @param record ZNRecord corresponding to a status update
+   */
   public StatusUpdate(ZNRecord record) {
     super(record);
   }

http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/58b78f6a/helix-core/src/main/java/org/apache/helix/model/Transition.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/model/Transition.java b/helix-core/src/main/java/org/apache/helix/model/Transition.java
index 2bbec41..2151c44 100644
--- a/helix-core/src/main/java/org/apache/helix/model/Transition.java
+++ b/helix-core/src/main/java/org/apache/helix/model/Transition.java
@@ -19,10 +19,18 @@ package org.apache.helix.model;
  * under the License.
  */
 
+/**
+ * Defines a transition from one state to another
+ */
 public class Transition {
   final private String _fromState;
   final private String _toState;
 
+  /**
+   * Instantiate with a source and destination state
+   * @param fromState source name
+   * @param toState destination name
+   */
   public Transition(String fromState, String toState) {
     _fromState = fromState;
     _toState = toState;
@@ -46,10 +54,18 @@ public class Transition {
     return this.toString().equalsIgnoreCase(that.toString());
   }
 
+  /**
+   * Get the source state
+   * @return source state name
+   */
   public String getFromState() {
     return _fromState;
   }
 
+  /**
+   * Get the destination state
+   * @return destination state name
+   */
   public String getToState() {
     return _toState;
   }


Mime
View raw message