You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@helix.apache.org by zz...@apache.org on 2013/08/14 22:46:47 UTC
[2/2] git commit: HELIX-207: Add javadocs to classes and public
methods in the top-level package, rb=13548
HELIX-207: Add javadocs to classes and public methods in the top-level package, rb=13548
Project: http://git-wip-us.apache.org/repos/asf/incubator-helix/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-helix/commit/f38b3da2
Tree: http://git-wip-us.apache.org/repos/asf/incubator-helix/tree/f38b3da2
Diff: http://git-wip-us.apache.org/repos/asf/incubator-helix/diff/f38b3da2
Branch: refs/heads/master
Commit: f38b3da2988cc00fba95037185a52c3756b507f1
Parents: 9861070
Author: zzhang <zz...@uci.edu>
Authored: Wed Aug 14 13:46:37 2013 -0700
Committer: zzhang <zz...@uci.edu>
Committed: Wed Aug 14 13:46:37 2013 -0700
----------------------------------------------------------------------
.../java/org/apache/helix/AccessOption.java | 6 +-
.../java/org/apache/helix/BaseDataAccessor.java | 104 +++----
.../apache/helix/ClusterMessagingService.java | 48 ++-
.../java/org/apache/helix/ConfigAccessor.java | 61 ++--
.../apache/helix/ControllerChangeListener.java | 5 +-
.../main/java/org/apache/helix/Criteria.java | 73 ++++-
.../helix/CurrentStateChangeListener.java | 10 +-
.../java/org/apache/helix/ExternalCommand.java | 60 ++--
.../helix/ExternalViewChangeListener.java | 8 +-
.../main/java/org/apache/helix/GroupCommit.java | 15 +-
.../apache/helix/HealthStateChangeListener.java | 11 +-
.../main/java/org/apache/helix/HelixAdmin.java | 51 ++--
.../java/org/apache/helix/HelixConstants.java | 3 +
.../org/apache/helix/HelixDataAccessor.java | 10 +-
.../java/org/apache/helix/HelixException.java | 6 +-
.../java/org/apache/helix/HelixManager.java | 38 ++-
.../org/apache/helix/HelixManagerFactory.java | 10 +-
.../apache/helix/HelixManagerProperties.java | 21 +-
.../java/org/apache/helix/HelixProperty.java | 66 ++++-
.../java/org/apache/helix/HelixTimerTask.java | 9 +-
.../apache/helix/IdealStateChangeListener.java | 4 +-
.../helix/InstanceConfigChangeListener.java | 3 +
.../helix/LiveInstanceChangeListener.java | 4 +-
.../apache/helix/LiveInstanceInfoProvider.java | 5 +-
.../java/org/apache/helix/MessageListener.java | 4 +-
.../org/apache/helix/NotificationContext.java | 64 +++-
.../org/apache/helix/PreConnectCallback.java | 3 +
.../main/java/org/apache/helix/PropertyKey.java | 290 ++++++++++++++++++-
.../org/apache/helix/PropertyPathConfig.java | 17 +-
.../java/org/apache/helix/PropertyType.java | 54 ++++
.../helix/ScopedConfigChangeListener.java | 3 +
.../main/java/org/apache/helix/ZNRecord.java | 195 +++++++++++++
.../org/apache/helix/ZNRecordAssembler.java | 8 +
.../org/apache/helix/ZNRecordBucketizer.java | 14 +-
.../java/org/apache/helix/ZNRecordDelta.java | 38 ++-
.../java/org/apache/helix/ZNRecordUpdater.java | 7 +
36 files changed, 1123 insertions(+), 205 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/AccessOption.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/AccessOption.java b/helix-core/src/main/java/org/apache/helix/AccessOption.java
index eb86fee..8bb5506 100644
--- a/helix-core/src/main/java/org/apache/helix/AccessOption.java
+++ b/helix-core/src/main/java/org/apache/helix/AccessOption.java
@@ -32,7 +32,7 @@ public class AccessOption
/**
* Helper method to get zookeeper create mode from options
*
- * @param options
+ * @param options bitmask representing mode; least significant set flag is selected
* @return zookeeper create mode
*/
public static CreateMode getMode(int options)
@@ -60,8 +60,8 @@ public class AccessOption
/**
* Helper method to get is-throw-exception-on-node-not-exist from options
*
- * @param options
- * @return
+ * @param options bitmask containing Zookeeper mode options
+ * @return true if in is-throw-exception-on-node-not-exist, false otherwise
*/
public static boolean isThrowExceptionIfNotExist(int options)
{
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/BaseDataAccessor.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/BaseDataAccessor.java b/helix-core/src/main/java/org/apache/helix/BaseDataAccessor.java
index fcbad00..7c65460 100644
--- a/helix-core/src/main/java/org/apache/helix/BaseDataAccessor.java
+++ b/helix-core/src/main/java/org/apache/helix/BaseDataAccessor.java
@@ -24,9 +24,13 @@ import java.util.List;
import org.I0Itec.zkclient.DataUpdater;
import org.I0Itec.zkclient.IZkChildListener;
import org.I0Itec.zkclient.IZkDataListener;
-import org.apache.zookeeper.CreateMode;
import org.apache.zookeeper.data.Stat;
+/**
+ * Generic interface for accessing and manipulating data on a backing store like Zookeeper.
+ *
+ * @param <T> The type of record to use
+ */
public interface BaseDataAccessor<T>
{
/**
@@ -34,9 +38,9 @@ public interface BaseDataAccessor<T>
* create parents if they do not exist. For performance reasons, it may try to create
* child first and only if it fails it will try to create parent
*
- * @param path
- * @param record
- * @return
+ * @param path path to the ZNode to create
+ * @param record the data to write to the ZNode
+ * @return true if creation succeeded, false otherwise (e.g. if the ZNode exists)
*/
boolean create(String path, T record, int options);
@@ -44,10 +48,10 @@ public interface BaseDataAccessor<T>
* This will always attempt to set the data on existing node. If the znode does not
* exist it will create it.
*
- * @param path
- * @param record
+ * @param path path to the ZNode to set
+ * @param record the data to write to the ZNode
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
- * @return
+ * @return true if data was successfully set, false otherwise
*/
boolean set(String path, T record, int options);
@@ -55,19 +59,19 @@ public interface BaseDataAccessor<T>
* This will attempt to merge with existing data by calling znrecord.merge and if it
* does not exist it will create it znode
*
- * @param path
- * @param record
+ * @param path path to the ZNode to update
+ * @param updater an update routine for the data to merge in
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
- * @return
+ * @return true if data merge succeeded, false otherwise
*/
boolean update(String path, DataUpdater<T> updater, int options);
/**
- * This will remove znode and all it's child nodes if any
+ * This will remove znode and all its child nodes if any
*
- * @param path
+ * @param path path to the root ZNode to remove
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
- * @return
+ * @return true if the removal succeeded, false otherwise
*/
boolean remove(String path, int options);
@@ -75,10 +79,10 @@ public interface BaseDataAccessor<T>
* Use it when creating children under a parent node. This will use async api for better
* performance. If the child already exists it will return false.
*
- * @param parentPath
- * @param record
+ * @param parentPath paths to the immediate parent ZNodes
+ * @param record List of data to write to each of the children
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
- * @return
+ * @return For each child: true if creation succeeded, false otherwise (e.g. if the child exists)
*/
boolean[] createChildren(List<String> paths, List<T> records, int options);
@@ -86,9 +90,10 @@ public interface BaseDataAccessor<T>
* can set multiple children under a parent node. This will use async api for better
* performance. If this child does not exist it will create it.
*
- * @param parentPath
- * @param record
+ * @param parentPath paths to the immediate parent ZNodes
+ * @param record List of data with which to overwrite the corresponding ZNodes
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
+ * @return For each child: true if the data was set, false otherwise
*/
boolean[] setChildren(List<String> paths, List<T> records, int options);
@@ -96,117 +101,116 @@ public interface BaseDataAccessor<T>
* Can update multiple nodes using async api for better performance. If a child does not
* exist it will create it.
*
- * @param parentPath
- * @param record
+ * @param parentPath paths to the immediate parent ZNodes
+ * @param updaters List of update routines for records to merge in
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
- * @return
+ * @return For each child, true if the data was merged in, false otherwise
*/
boolean[] updateChildren(List<String> paths, List<DataUpdater<T>> updaters, int options);
/**
* remove multiple paths using async api. will remove any child nodes if any
*
- * @param paths
+ * @param paths paths to the ZNodes to remove
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
- * @return
+ * @return For each ZNode, true if successfully removed, false otherwise
*/
boolean[] remove(List<String> paths, int options);
/**
* Get the {@link T} corresponding to the path
*
- * @param path
+ * @param path path to the ZNode
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
- * @return
+ * @return the record data stored at the ZNode
*/
T get(String path, Stat stat, int options);
/**
* Get List of {@link T} corresponding to the paths using async api
*
- * @param paths
+ * @param paths paths to the ZNodes
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
- * @return
+ * @return List of record data stored at each ZNode
*/
List<T> get(List<String> paths, List<Stat> stats, int options);
/**
* Get the children under a parent path using async api
*
- * @param path
+ * @param path path to the immediate parent ZNode
+ * @param stats Zookeeper Stat objects corresponding to each child
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
- * @return
+ * @return A list of children of the parent ZNode
*/
List<T> getChildren(String parentPath, List<Stat> stats, int options);
/**
* Returns the child names given a parent path
*
- * @param type
- * @param keys
+ * @param parentPath path to the immediate parent ZNode
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
- * @return
+ * @return a list of the names of all of the parent ZNode's children
*/
List<String> getChildNames(String parentPath, int options);
/**
* checks if the path exists in zk
*
- * @param path
+ * @param path path to the ZNode to test
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
- * @return
+ * @return true if the ZNode exists, false otherwise
*/
boolean exists(String path, int options);
/**
* checks if the all the paths exists
*
- * @param paths
+ * @param paths paths to the ZNodes to test
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
- * @return
+ * @return for each path, true if a valid ZNode exists, false otherwise
*/
boolean[] exists(List<String> paths, int options);
/**
* Get the stats of all the paths
*
- * @param paths
+ * @param paths paths of the ZNodes to query
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
- * @return
+ * @return Zookeeper Stat object for each path
*/
Stat[] getStats(List<String> paths, int options);
/**
- * Get the stats of all the paths
+ * Get the stats of a single path
*
- * @param paths
+ * @param path path of the ZNode to query
* @param options Set the type of ZNode see the valid values in {@link AccessOption}
- * @return
+ * @return Zookeeper Stat object corresponding to the ZNode
*/
Stat getStat(String path, int options);
/**
* Subscribe data listener to path
*
- * @param path
- * @param listener
- * @return
+ * @param path path to the ZNode to listen to
+ * @param listener the listener to register for changes
*/
void subscribeDataChanges(String path, IZkDataListener listener);
/**
* Unsubscribe data listener to path
*
- * @param path
- * @param listener
+ * @param path path to the ZNode to stop listening to
+ * @param listener the listener currently subscribed to the ZNode
*/
void unsubscribeDataChanges(String path, IZkDataListener listener);
/**
* Subscribe child listener to path
*
- * @param path
- * @param listener
+ * @param path path to the immediate parent ZNode
+ * @param listener the listener to register for changes
* @return
*/
List<String> subscribeChildChanges(String path, IZkChildListener listener);
@@ -214,8 +218,8 @@ public interface BaseDataAccessor<T>
/**
* Unsubscribe child listener to path
*
- * @param path
- * @param listener
+ * @param path path to the immediate parent ZNode
+ * @param listener the listener currently subscribed to the children
*/
void unsubscribeChildChanges(String path, IZkChildListener listener);
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/ClusterMessagingService.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/ClusterMessagingService.java b/helix-core/src/main/java/org/apache/helix/ClusterMessagingService.java
index dc4a0ad..6bab243 100644
--- a/helix-core/src/main/java/org/apache/helix/ClusterMessagingService.java
+++ b/helix-core/src/main/java/org/apache/helix/ClusterMessagingService.java
@@ -40,34 +40,43 @@ public interface ClusterMessagingService
/**
* Send message matching the specifications mentioned in recipientCriteria.
*
- * @param receipientCriteria
+ * @param receipientCriteria criteria to be met, defined as {@link Criteria}
* @See Criteria
* @param message
* message to be sent. Some attributes of this message will be
* changed as required
- * @return returns how many messages were successfully sent.
+ * @return the number of messages that were successfully sent.
*/
int send(Criteria recipientCriteria, Message message);
/**
* This will send the message to all instances matching the criteria<br>
- * When there is a reply to the message sent AsynCallback.onReply will be
+ * When there is a reply to the message sent AsyncCallback.onReply will be
* invoked. Application can specify a timeout on AsyncCallback. After every
* reply is processed AsyncCallback.isDone will be invoked.<br>
* This method will return after sending the messages. <br>
* This is useful when message need to be sent and current thread need not
* wait for response since processing will be done in another thread.
- *
+ *
+ * @see #send(Criteria, Message)
* @param receipientCriteria
* @param message
- * @param callbackOnReply
- * @param timeOut
- * @param retryCount
- * @return
+ * @param callbackOnReply callback to trigger on completion
+ * @param timeOut Time to wait before failing the send
+ * @return the number of messages that were successfully sent
*/
int send(Criteria receipientCriteria, Message message,
AsyncCallback callbackOnReply, int timeOut);
+ /**
+ * @see #send(Criteria, Message, AsyncCallback, int)
+ * @param receipientCriteria
+ * @param message
+ * @param callbackOnReply
+ * @param timeOut
+ * @param retryCount maximum number of times to retry the send
+ * @return the number of messages that were successfully sent
+ */
int send(Criteria receipientCriteria, Message message,
AsyncCallback callbackOnReply, int timeOut, int retryCount);
@@ -81,17 +90,27 @@ public interface ClusterMessagingService
* for response. <br>
* The current thread can use callbackOnReply instance to store application
* specific data.
- *
+ *
+ * @see #send(Criteria, Message, AsyncCallback, int)
* @param receipientCriteria
* @param message
* @param callbackOnReply
* @param timeOut
* @param retryCount
- * @return
+ * @return the number of messages that were successfully sent
*/
int sendAndWait(Criteria receipientCriteria, Message message,
AsyncCallback callbackOnReply, int timeOut);
+ /**
+ * @see #send(Criteria, Message, AsyncCallback, int, int)
+ * @param receipientCriteria
+ * @param message
+ * @param callbackOnReply
+ * @param timeOut
+ * @param retryCount
+ * @return the number of messages that were successfully sent
+ */
int sendAndWait(Criteria receipientCriteria, Message message,
AsyncCallback callbackOnReply, int timeOut, int retryCount);
@@ -111,8 +130,7 @@ public interface ClusterMessagingService
* @param factory
* The per-type message factory
* @param threadpoolSize
- * size of the execution threadpool that handles the message
- * @return
+ * size of the execution threadpool that handles the message
*/
public void registerMessageHandlerFactory(String type,
MessageHandlerFactory factory);
@@ -121,9 +139,9 @@ public interface ClusterMessagingService
* This will generate all messages to be sent given the recipientCriteria and MessageTemplate,
* the messages are not sent.
*
- * @param receipientCriteria
- * @param messageTemplate
- * @return
+ * @param receipientCriteria criteria to be met, defined as {@link Criteria}
+ * @param messageTemplate the Message on which to base the messages to send
+ * @return messages to be sent, grouped by the type of instance to send the message to
*/
public Map<InstanceType, List<Message>> generateMessage(final Criteria recipientCriteria,
final Message messageTemplate);
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/ConfigAccessor.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/ConfigAccessor.java b/helix-core/src/main/java/org/apache/helix/ConfigAccessor.java
index c1afb8d..d3de9eb 100644
--- a/helix-core/src/main/java/org/apache/helix/ConfigAccessor.java
+++ b/helix-core/src/main/java/org/apache/helix/ConfigAccessor.java
@@ -35,7 +35,10 @@ import org.apache.helix.manager.zk.ZkClient;
import org.apache.helix.util.StringTemplate;
import org.apache.log4j.Logger;
-
+/**
+ * Provides access to the persistent configuration of the cluster, the instances that live on it,
+ * and the logical resources assigned to it.
+ */
public class ConfigAccessor
{
private static Logger LOG = Logger.getLogger(ConfigAccessor.class);
@@ -69,6 +72,10 @@ public class ConfigAccessor
private final ZkClient zkClient;
+ /**
+ * Initialize an accessor with a Zookeeper client
+ * @param zkClient
+ */
public ConfigAccessor(ZkClient zkClient)
{
this.zkClient = zkClient;
@@ -146,11 +153,12 @@ public class ConfigAccessor
}
/**
- * get config
+ * get a single config entry
*
- * @param scope
- * @param key
- * @return
+ * @param scope specification of the entity set to query
+ * (e.g. cluster, resource, participant, etc.)
+ * @param key the identifier of the configuration entry
+ * @return the configuration entry
*/
public String get(HelixConfigScope scope, String key) {
Map<String, String> map = get(scope, Arrays.asList(key));
@@ -161,11 +169,12 @@ public class ConfigAccessor
}
/**
- * get configs
+ * get many config entries
*
- * @param scope
- * @param keys
- * @return
+ * @param scope scope specification of the entity set to query
+ * (e.g. cluster, resource, participant, etc.)
+ * @param keys the identifiers of the configuration entries
+ * @return the configuration entries, organized by key
*/
public Map<String, String> get(HelixConfigScope scope, List<String> keys) {
if (scope == null || scope.getType()== null || !scope.isFullKey()) {
@@ -284,11 +293,12 @@ public class ConfigAccessor
}
/**
- * set config. create if not exist
+ * Set config, creating it if it doesn't exist
*
- * @param scope
- * @param key
- * @param value
+ * @param scope scope specification of the entity set to query
+ * (e.g. cluster, resource, participant, etc.)
+ * @param key the identifier of the configuration entry
+ * @param value the configuration
*/
public void set(HelixConfigScope scope, String key, String value) {
Map<String, String> map = new TreeMap<String, String>();
@@ -297,10 +307,11 @@ public class ConfigAccessor
}
/**
- * set configs. create if not exist
+ * Set multiple configs, creating them if they don't exist
*
- * @param scope
- * @param keyValueMap
+ * @param scope scope specification of the entity set to query
+ * (e.g. cluster, resource, participant, etc.)
+ * @param keyValueMap configurations organized by their identifiers
*/
public void set(HelixConfigScope scope, Map<String, String> keyValueMap)
{
@@ -398,20 +409,22 @@ public class ConfigAccessor
}
/**
- * rmeove config
+ * Remove a single config
*
- * @param scope
- * @param key
+ * @param scope scope specification of the entity set to query
+ * (e.g. cluster, resource, participant, etc.)
+ * @param key the identifier of the configuration entry
*/
public void remove(HelixConfigScope scope, String key) {
remove(scope, Arrays.asList(key));
}
/**
- * remove configs
+ * Remove multiple configs
*
- * @param scope
- * @param keys
+ * @param scope scope specification of the entity set to query
+ * (e.g. cluster, resource, participant, etc.)
+ * @param keys the identifiers of the configuration entries
*/
public void remove(HelixConfigScope scope, List<String> keys)
{
@@ -520,10 +533,10 @@ public class ConfigAccessor
/**
- * get list of config keys for a scope
+ * Get list of config keys for a scope
*
* @param scope
- * @return
+ * @return a list of configuration keys
*/
public List<String> getKeys(HelixConfigScope scope) {
if (scope == null || scope.getType() == null) {
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/ControllerChangeListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/ControllerChangeListener.java b/helix-core/src/main/java/org/apache/helix/ControllerChangeListener.java
index b27596d..104f0bc 100644
--- a/helix-core/src/main/java/org/apache/helix/ControllerChangeListener.java
+++ b/helix-core/src/main/java/org/apache/helix/ControllerChangeListener.java
@@ -19,12 +19,15 @@ package org.apache.helix;
* under the License.
*/
+/**
+ * Interface to implement to respond to controller changes.
+ */
public interface ControllerChangeListener
{
/**
* Invoked when controller changes
*
- * @param changeContext
+ * @param changeContext description of the event and state
*/
public void onControllerChange(NotificationContext changeContext);
}
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/Criteria.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/Criteria.java b/helix-core/src/main/java/org/apache/helix/Criteria.java
index 11e9f7a..101420c 100644
--- a/helix-core/src/main/java/org/apache/helix/Criteria.java
+++ b/helix-core/src/main/java/org/apache/helix/Criteria.java
@@ -19,6 +19,9 @@ package org.apache.helix;
* under the License.
*/
+/**
+ * Describes various properties that operations involving {@link Message} delivery will follow.
+ */
public class Criteria
{
public enum DataSource
@@ -61,87 +64,153 @@ public class Criteria
* Determine if use external view or ideal state as source of truth
*/
DataSource _dataSource = DataSource.EXTERNALVIEW;
-
+
+ /**
+ * Get the current source of truth
+ * @return either the ideal state or the external view
+ */
public DataSource getDataSource()
{
return _dataSource;
}
-
+
+ /**
+ * Set the current source of truth
+ * @param source ideal state or external view
+ */
public void setDataSource(DataSource source)
{
_dataSource = source;
}
+ /**
+ * Determine if the message is excluded from being sent to the sender
+ * @return true if the self-sent message is excluded, false otherwise
+ */
public boolean isSelfExcluded()
{
return selfExcluded;
}
+ /**
+ * Indicate whether or not the sender will be excluded as a message recipient
+ * @param selfExcluded true if the sender should be excluded, false otherwise
+ */
public void setSelfExcluded(boolean selfExcluded)
{
this.selfExcluded = selfExcluded;
}
+ /**
+ * Determine the type of the recipient
+ * @return InstanceType (e.g. PARTICIPANT, CONTROLLER, SPECTATOR)
+ */
public InstanceType getRecipientInstanceType()
{
return recipientInstanceType;
}
+ /**
+ * Set the type of the recipient
+ * @param recipientInstanceType InstanceType (e.g. PARTICIPANT, CONTROLLER, SPECTATOR)
+ */
public void setRecipientInstanceType(InstanceType recipientInstanceType)
{
this.recipientInstanceType = recipientInstanceType;
}
+ /**
+ * Determine if this message should be processed only if an instance was up at send time
+ * @return true if the message will be processed by current live nodes, false otherwise
+ */
public boolean isSessionSpecific()
{
return sessionSpecific;
}
+ /**
+ * Indicate whether or not a message should be restricted to a session
+ * @param sessionSpecific true if the message can only be processed by live nodes at send time,
+ * false otherwise
+ */
public void setSessionSpecific(boolean sessionSpecific)
{
this.sessionSpecific = sessionSpecific;
}
+ /**
+ * Get the name of the destination instance, available only for PARTICIPANT
+ * @return the instance name
+ */
public String getInstanceName()
{
return instanceName;
}
+ /**
+ * Set the name of the destination instance (PARTICIPANT only)
+ * @param instanceName the instance name or * for all instances
+ */
public void setInstanceName(String instanceName)
{
this.instanceName = instanceName;
}
+ /**
+ * Get the destination resource name
+ * @return destination resource name
+ */
public String getResource()
{
return resourceName;
}
+ /**
+ * Set the destination resource name
+ * @param resourceName the resource name or * for all resources
+ */
public void setResource(String resourceName)
{
this.resourceName = resourceName;
}
+ /**
+ * Get the destination partition name
+ * @return destination partition name
+ */
public String getPartition()
{
return partitionName;
}
+ /**
+ * Set the destination partition name
+ * @param partitionName the partition name, or * for all partitions of a resource
+ */
public void setPartition(String partitionName)
{
this.partitionName = partitionName;
}
+ /**
+ * Get the state of a resource partition
+ * @return the state of the resource partition
+ */
public String getPartitionState()
{
return partitionState;
}
+ /**
+ * Set the state of the resource partition
+ * @param partitionState the state of the resource partition
+ */
public void setPartitionState(String partitionState)
{
this.partitionState = partitionState;
}
+ @Override
public String toString()
{
StringBuilder sb = new StringBuilder();
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/CurrentStateChangeListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/CurrentStateChangeListener.java b/helix-core/src/main/java/org/apache/helix/CurrentStateChangeListener.java
index 0c3baa5..d244600 100644
--- a/helix-core/src/main/java/org/apache/helix/CurrentStateChangeListener.java
+++ b/helix-core/src/main/java/org/apache/helix/CurrentStateChangeListener.java
@@ -23,16 +23,18 @@ import java.util.List;
import org.apache.helix.model.CurrentState;
-
+/**
+ * Interface to implement to respond to changes in the current state
+ */
public interface CurrentStateChangeListener
{
/**
* Invoked when current state changes
*
- * @param instanceName
- * @param statesInfo
- * @param changeContext
+ * @param instanceName name of the instance whose state changed
+ * @param statesInfo a list of the current states
+ * @param changeContext the change event and state
*/
public void onStateChange(String instanceName,
List<CurrentState> statesInfo,
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/ExternalCommand.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/ExternalCommand.java b/helix-core/src/main/java/org/apache/helix/ExternalCommand.java
index 5c9d716..b24085d 100644
--- a/helix-core/src/main/java/org/apache/helix/ExternalCommand.java
+++ b/helix-core/src/main/java/org/apache/helix/ExternalCommand.java
@@ -33,6 +33,10 @@ import java.util.concurrent.TimeoutException;
import org.apache.log4j.Logger;
+/**
+ * Wrapper for running commands outside of the JVM
+ * @see {@link Process}
+ */
public class ExternalCommand
{
public static final String MODULE = ExternalCommand.class.getName();
@@ -44,6 +48,9 @@ public class ExternalCommand
private InputReader _out;
private InputReader _err;
+ /**
+ * Stream redirector
+ */
private static class InputReader extends Thread
{
private static final int BUFFER_SIZE = 2048;
@@ -87,7 +94,9 @@ public class ExternalCommand
}
}
/**
-* Constructor */
+ * Initialize with a {@link ProcessBuilder}
+ * @param processBuilder initialized {@link ProcessBuilder} object
+ */
public ExternalCommand(ProcessBuilder processBuilder)
{
_processBuilder = processBuilder;
@@ -109,7 +118,7 @@ public class ExternalCommand
}
/**
-* @see ProcessBuilder
+* @see {@link ProcessBuilder#environment()}
*/
public Map<String, String> getEnvironment()
{
@@ -117,7 +126,7 @@ public class ExternalCommand
}
/**
-* @see ProcessBuilder
+* @see {@link ProcessBuilder#directory()}
*/
public File getWorkingDirectory()
{
@@ -125,7 +134,7 @@ public class ExternalCommand
}
/**
-* @see ProcessBuilder
+* @see {@link ProcessBuilder#directory(File)}
*/
public void setWorkingDirectory(File directory)
{
@@ -133,7 +142,7 @@ public class ExternalCommand
}
/**
-* @see ProcessBuilder
+* @see {@link ProcessBuilder#redirectErrorStream()}
*/
public boolean getRedirectErrorStream()
{
@@ -141,19 +150,29 @@ public class ExternalCommand
}
/**
-* @see ProcessBuilder
+* @see {@link ProcessBuilder#redirectErrorStream(boolean)}
*/
public void setRedirectErrorStream(boolean redirectErrorStream)
{
_processBuilder.redirectErrorStream(redirectErrorStream);
}
+ /**
+ * Get the contents of the output stream after completion
+ * @return bytes from the output stream
+ * @throws InterruptedException the process was interrupted before completion
+ */
public byte[] getOutput() throws InterruptedException
{
waitFor();
return _out.getOutput();
}
+ /**
+ * Get the contents of the error stream after completion
+ * @return bytes from the error stream
+ * @throws InterruptedException the process was interrupted before completion
+ */
public byte[] getError() throws InterruptedException
{
waitFor();
@@ -163,10 +182,10 @@ public class ExternalCommand
/**
* Returns the output as a string.
*
-* @param encoding
+* @param encoding string encoding scheme, e.g. "UTF-8"
* @return encoded string
-* @throws InterruptedException
-* @throws UnsupportedEncodingException
+* @throws InterruptedException the process was interrupted before completion
+* @throws UnsupportedEncodingException the encoding scheme is invalid
*/
public String getStringOutput(String encoding) throws InterruptedException,
UnsupportedEncodingException
@@ -178,7 +197,7 @@ public class ExternalCommand
* Returns the output as a string. Uses encoding "UTF-8".
*
* @return utf8 encoded string
-* @throws InterruptedException
+* @throws InterruptedException the process was interrupted before completion
*/
public String getStringOutput() throws InterruptedException
{
@@ -196,10 +215,10 @@ public class ExternalCommand
/**
* Returns the error as a string.
*
-* @param encoding
+* @param encoding the encoding scheme, e.g. "UTF-8"
* @return error as string
-* @throws InterruptedException
-* @throws UnsupportedEncodingException
+* @throws InterruptedException the process was interrupted before completion
+* @throws UnsupportedEncodingException the encoding scheme is invalid
*/
public String getStringError(String encoding) throws InterruptedException,
UnsupportedEncodingException
@@ -211,7 +230,7 @@ public class ExternalCommand
* Returns the error as a string. Uses encoding "UTF-8".
*
* @return error as string
-* @throws InterruptedException
+* @throws InterruptedException the process was interrupted before completion
*/
public String getStringError() throws InterruptedException
{
@@ -232,7 +251,7 @@ public class ExternalCommand
* wait for the process to be finished.
* @return the status code of the process.
*
-* @throws InterruptedException
+* @throws InterruptedException the process was interrupted before completion
*/
public int waitFor() throws InterruptedException
{
@@ -252,8 +271,8 @@ public class ExternalCommand
* {@link TimeoutException}
* @return the status code of the process.
*
-* @throws TimeoutException
-* @throws InterruptedException
+* @throws TimeoutException the process timed out
+* @throws InterruptedException the process was interrupted before completion
*/
public int waitFor(long timeout) throws InterruptedException, TimeoutException
{
@@ -275,6 +294,10 @@ public class ExternalCommand
return _process.waitFor();
}
+ /**
+ * @see {@link Process#exitValue()}
+ * @return the return code of the process
+ */
public int exitValue()
{
if(_process == null)
@@ -283,6 +306,9 @@ public class ExternalCommand
return _process.exitValue();
}
+ /**
+ * see {@link Process#destroy()}
+ */
public void destroy()
{
if(_process == null)
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/ExternalViewChangeListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/ExternalViewChangeListener.java b/helix-core/src/main/java/org/apache/helix/ExternalViewChangeListener.java
index 1fa0db0..9aff2da 100644
--- a/helix-core/src/main/java/org/apache/helix/ExternalViewChangeListener.java
+++ b/helix-core/src/main/java/org/apache/helix/ExternalViewChangeListener.java
@@ -23,15 +23,17 @@ import java.util.List;
import org.apache.helix.model.ExternalView;
-
+/**
+ * Interface to implement to be notified of changes to the external view
+ */
public interface ExternalViewChangeListener
{
/**
* Invoked when external view changes
*
- * @param externalViewList
- * @param changeContext
+ * @param externalViewList a list of ExternalViews
+ * @param changeContext the change event and state
*/
public void onExternalViewChange(List<ExternalView> externalViewList,
NotificationContext changeContext);
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/GroupCommit.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/GroupCommit.java b/helix-core/src/main/java/org/apache/helix/GroupCommit.java
index 29f7369..f90ec9d 100644
--- a/helix-core/src/main/java/org/apache/helix/GroupCommit.java
+++ b/helix-core/src/main/java/org/apache/helix/GroupCommit.java
@@ -29,6 +29,9 @@ import org.I0Itec.zkclient.exception.ZkNoNodeException;
import org.apache.log4j.Logger;
// TODO: move to mananger.zk
+/**
+ * Support committing updates to data such that they are ordered for each key
+ */
public class GroupCommit
{
private static Logger LOG = Logger.getLogger(GroupCommit.class);
@@ -57,7 +60,9 @@ public class GroupCommit
// TODO: move the cache logic to data accessor
// private final Map<String, ZNRecord> _cache = new ConcurrentHashMap<String, ZNRecord>();
-
+ /**
+ * Set up a group committer and its associated queues
+ */
public GroupCommit()
{
// Don't use Arrays.fill();
@@ -72,6 +77,14 @@ public class GroupCommit
return _queues[(key.hashCode() & Integer.MAX_VALUE) % _queues.length];
}
+ /**
+ * Do a group update for data associated with a given key
+ * @param accessor accessor with the ability to pull from the current data
+ * @param options see {@link AccessOption}
+ * @param key the data identifier
+ * @param record the data to be merged in
+ * @return true if successful, false otherwise
+ */
public boolean commit(BaseDataAccessor<ZNRecord> accessor, int options, String key, ZNRecord record)
{
Queue queue = getQueue(key);
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HealthStateChangeListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HealthStateChangeListener.java b/helix-core/src/main/java/org/apache/helix/HealthStateChangeListener.java
index bd3ef4f..607d5c9 100644
--- a/helix-core/src/main/java/org/apache/helix/HealthStateChangeListener.java
+++ b/helix-core/src/main/java/org/apache/helix/HealthStateChangeListener.java
@@ -22,18 +22,19 @@ package org.apache.helix;
import java.util.List;
import org.apache.helix.model.HealthStat;
-import org.apache.helix.model.Message;
-
+/**
+ * Interface to implement to listen for when a health status event is triggered.
+ */
public interface HealthStateChangeListener
{
/**
* Invoked when health stats change
*
- * @param instanceName
- * @param reports
- * @param changeContext
+ * @param instanceName the instance where the health status changed
+ * @param reports the health statuses
+ * @param changeContext event properties and state
*/
public void onHealthChange(String instanceName,
List<HealthStat> reports,
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixAdmin.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixAdmin.java b/helix-core/src/main/java/org/apache/helix/HelixAdmin.java
index 5cd9a13..5f92c24 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixAdmin.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixAdmin.java
@@ -22,19 +22,18 @@ package org.apache.helix;
import java.io.IOException;
import java.util.List;
import java.util.Map;
-import java.util.Set;
-
import org.apache.helix.model.*;
import org.apache.helix.model.ClusterConstraints.ConstraintType;
-import org.apache.helix.model.HelixConfigScope.ConfigScopeProperty;
-
+/*
+ * Helix cluster management
+ */
public interface HelixAdmin
{
/**
* Get a list of clusters under "/"
*
- * @return
+ * @return a list of cluster names
*/
List<String> getClusters();
@@ -42,16 +41,16 @@ public interface HelixAdmin
* Get a list of instances under a cluster
*
* @param clusterName
- * @return
+ * @return a list of instance names
*/
List<String> getInstancesInCluster(String clusterName);
/**
- * Get instance configs
+ * Get an instance config
*
* @param clusterName
* @param instanceName
- * @return
+ * @return InstanceConfig corresponding to the specified instance
*/
InstanceConfig getInstanceConfig(String clusterName, String instanceName);
@@ -59,7 +58,7 @@ public interface HelixAdmin
* Get a list of resources in a cluster
*
* @param clusterName
- * @return
+ * @return a list of resource names in the cluster
*/
List<String> getResourcesInCluster(String clusterName);
@@ -92,12 +91,12 @@ public interface HelixAdmin
*
* @param clusterName
* @param resourceName
- * @param numResources
+ * @param numPartitions
* @param stateModelRef
*/
void addResource(String clusterName,
String resourceName,
- int numResources,
+ int numPartitions,
String stateModelRef);
/**
*
@@ -114,13 +113,13 @@ public interface HelixAdmin
*
* @param clusterName
* @param resourceName
- * @param numResources
+ * @param numPartitions
* @param stateModelRef
* @param idealStateMode
*/
void addResource(String clusterName,
String resourceName,
- int numResources,
+ int numPartitions,
String stateModelRef,
String idealStateMode);
@@ -129,14 +128,14 @@ public interface HelixAdmin
*
* @param clusterName
* @param resourceName
- * @param numResources
+ * @param numPartitions
* @param stateModelRef
* @param idealStateMode
* @param bucketSize
*/
void addResource(String clusterName,
String resourceName,
- int numResources,
+ int numPartitions,
String stateModelRef,
String idealStateMode,
int bucketSize);
@@ -146,7 +145,7 @@ public interface HelixAdmin
*
* @param clusterName
* @param resourceName
- * @param numResources
+ * @param numPartitions
* @param stateModelRef
* @param idealStateMode
* @param bucketSize
@@ -154,7 +153,7 @@ public interface HelixAdmin
*/
void addResource(String clusterName,
String resourceName,
- int numResources,
+ int numPartitions,
String stateModelRef,
String idealStateMode,
int bucketSize,
@@ -296,7 +295,7 @@ public interface HelixAdmin
void addAlert(String clusterName, String alertName);
/**
- * Drop a statistics from a cluster
+ * Drop statistics from a cluster
*
* @param clusterName
* @param statName
@@ -324,7 +323,7 @@ public interface HelixAdmin
*
* @param clusterName
* @param stateModelName
- * @return
+ * @return StateModelDefinition identified by stateModelName
*/
StateModelDefinition getStateModelDef(String clusterName, String stateModelName);
@@ -333,7 +332,7 @@ public interface HelixAdmin
*
* @param clusterName
* @param resourceName
- * @return
+ * @return ExternalView for the resource
*/
ExternalView getResourceExternalView(String clusterName, String resourceName);
@@ -365,7 +364,7 @@ public interface HelixAdmin
*
* @param scope
* @param keys
- * @return
+ * @return configuration values ordered by the provided keys
*/
Map<String, String> getConfig(HelixConfigScope scope, List<String> keys);
@@ -373,7 +372,7 @@ public interface HelixAdmin
* Get configuration keys
*
* @param scope
- * @return
+ * @return keys mapping to valid configuration values
*/
List<String> getConfigKeys(HelixConfigScope scope);
@@ -402,7 +401,7 @@ public interface HelixAdmin
* @param clusterName
* @param stateModelDefName
* @param stateModelDefFile
- * @throws IOException
+ * @throws IOException error reading the state model definition file
*/
void addStateModelDef(String clusterName,
String stateModelDefName,
@@ -437,7 +436,7 @@ public interface HelixAdmin
*
* @param clusterName
* @param constraintType
- * @return
+ * @return constraints of constraintType
*/
ClusterConstraints getConstraints(String clusterName,
ConstraintType constraintType);
@@ -447,7 +446,6 @@ public interface HelixAdmin
* @param clusterName
* @param currentIdealState
* @param instanceNames
- * @return
*/
void rebalance(String clusterName,
IdealState currentIdealState,
@@ -467,6 +465,7 @@ public interface HelixAdmin
* @param resourceName
* @param replica
* @param keyPrefix
+ * @param group the group identifier of instances to rebalance
*/
void rebalance(String clusterName, String resourceName, int replica,
String keyPrefix, String group);
@@ -482,7 +481,6 @@ public interface HelixAdmin
* @param clusterName
* @param instanceNames
* @param tag
- * @return
*/
void addInstanceTag(String clusterName, String instanceName, String tag);
@@ -491,7 +489,6 @@ public interface HelixAdmin
* @param clusterName
* @param instanceNames
* @param tag
- * @return
*/
void removeInstanceTag(String clusterName, String instanceName, String tag);
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixConstants.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixConstants.java b/helix-core/src/main/java/org/apache/helix/HelixConstants.java
index 19bc740..f8fded8 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixConstants.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixConstants.java
@@ -19,6 +19,9 @@ package org.apache.helix;
* under the License.
*/
+/*
+ * Identifying constants of the components in a Helix-managed cluster
+ */
public interface HelixConstants
{
// TODO: ChangeType and PropertyType are duplicated, consider unifying
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java b/helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java
index 946787a..5ad48ea 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java
@@ -115,7 +115,7 @@ public interface HelixDataAccessor
* of the HelixProperty
*
* @param key
- * @return
+ * @return a map of property identifiers to typed properties
*/
<T extends HelixProperty> Map<String, T> getChildValuesMap(PropertyKey key);
@@ -125,7 +125,7 @@ public interface HelixDataAccessor
*
* @param keys
* @param children
- * @return
+ * @return array where true means the child was added and false means it was not
*/
<T extends HelixProperty> boolean[] createChildren(List<PropertyKey> keys,
List<T> children);
@@ -135,6 +135,7 @@ public interface HelixDataAccessor
*
* @param keys
* @param children
+ * @return array where true means the child was set and false means it was not
*/
<T extends HelixProperty> boolean[] setChildren(List<PropertyKey> keys, List<T> children);
@@ -144,6 +145,7 @@ public interface HelixDataAccessor
*
* @param paths
* @param updaters
+ * @return array where true means the child was updated and false means it was not
*/
<T extends HelixProperty> boolean[] updateChildren(List<String> paths,
List<DataUpdater<ZNRecord>> updaters,
@@ -152,14 +154,14 @@ public interface HelixDataAccessor
/**
* Get key builder for the accessor
*
- * @return
+ * @return instantiated PropertyKey.Builder
*/
PropertyKey.Builder keyBuilder();
/**
* Get underlying base data accessor
*
- * @return
+ * @return a data accessor that can process ZNRecord objects
*/
BaseDataAccessor<ZNRecord> getBaseDataAccessor();
}
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixException.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixException.java b/helix-core/src/main/java/org/apache/helix/HelixException.java
index 79c3468..0a64194 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixException.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixException.java
@@ -19,10 +19,14 @@ package org.apache.helix;
* under the License.
*/
-
+/**
+ * Base class for an exception thrown by Helix due to inconsistencies caught by Helix itself.
+ */
public class HelixException extends RuntimeException
{
+ private static final long serialVersionUID = 6558251214364526257L;
+
public HelixException(String message)
{
super(message);
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixManager.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixManager.java b/helix-core/src/main/java/org/apache/helix/HelixManager.java
index 7b01f2c..a4e2c55 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixManager.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixManager.java
@@ -36,7 +36,9 @@ import org.apache.helix.store.zk.ZkHelixPropertyStore;
* General flow <blockquote>
*
* <pre>
- * manager = HelixManagerFactory.getManagerFor<ROLE>(); ROLE can be participant, spectator or a controller<br/>
+ * manager = HelixManagerFactory.getZKHelixManager(
+ * clusterName, instanceName, ROLE, zkAddr);
+ * // ROLE can be participant, spectator or a controller<br/>
* manager.connect();
* manager.addSOMEListener();
* manager.start()
@@ -50,9 +52,9 @@ import org.apache.helix.store.zk.ZkHelixPropertyStore;
*
* </blockquote> Default implementations available
*
- * @see HelixStateMachineEngine for participant
- * @see RoutingTableProvider for spectator
- * @see GenericHelixController for controller
+ * @see HelixStateMachineEngine HelixStateMachineEngine for participant
+ * @see RoutingTableProvider RoutingTableProvider for spectator
+ * @see GenericHelixController RoutingTableProvider for controller
*/
public interface HelixManager
{
@@ -74,7 +76,7 @@ public interface HelixManager
* prevent client in doing anything when its disconnected from the cluster.
* There is no need to invoke connect again if isConnected return false.
*
- * @return
+ * @return true if connected, false otherwise
*/
boolean isConnected();
@@ -177,7 +179,7 @@ public interface HelixManager
* any cleanup tasks.<br/>
*
* @param listener
- * @return
+ * @return true if removed successfully, false otherwise
*/
boolean removeListener(PropertyKey key, Object listener);
/**
@@ -191,27 +193,29 @@ public interface HelixManager
/**
* Get config accessor
*
- * @return
+ * @return ConfigAccessor
*/
ConfigAccessor getConfigAccessor();
/**
* Returns the cluster name associated with this cluster manager
*
- * @return
+ * @return the associated cluster name
*/
String getClusterName();
/**
* Returns the instanceName used to connect to the cluster
*
- * @return
+ * @return the associated instance name
*/
String getInstanceName();
/**
* Get the sessionId associated with the connection to cluster data store.
+ *
+ * @return the session identifier
*/
String getSessionId();
@@ -220,40 +224,44 @@ public interface HelixManager
* be used to check if there was any new notification when previous
* notification was being processed. This is updated based on the
* notifications from listeners registered.
+ *
+ * @return UNIX timestamp
*/
long getLastNotificationTime();
/**
* Provides admin interface to setup and modify cluster.
*
- * @return
+ * @return instantiated HelixAdmin
*/
HelixAdmin getClusterManagmentTool();
/**
* Get property store
*
- * @return
+ * @return the property store that works with ZNRecord objects
*/
ZkHelixPropertyStore<ZNRecord> getHelixPropertyStore();
/**
* Messaging service which can be used to send cluster wide messages.
- *
+ *
+ * @return messaging service
*/
ClusterMessagingService getMessagingService();
/**
* Participant only component that periodically update participant health
* report to cluster manager server.
- *
+ *
+ * @return ParticipantHealthReportCollector
*/
ParticipantHealthReportCollector getHealthReportCollector();
/**
* Get cluster manager instance type
*
- * @return
+ * @return instance type (e.g. PARTICIPANT, CONTROLLER, SPECTATOR)
*/
InstanceType getInstanceType();
@@ -268,7 +276,7 @@ public interface HelixManager
* Get helix manager properties read from
* helix-core/src/main/resources/cluster-manager.properties
*
- * @return
+ * @return deserialized properties
*/
HelixManagerProperties getProperties();
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixManagerFactory.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixManagerFactory.java b/helix-core/src/main/java/org/apache/helix/HelixManagerFactory.java
index cc5673f..1f39d46 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixManagerFactory.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixManagerFactory.java
@@ -28,20 +28,22 @@ package org.apache.helix;
import org.apache.helix.manager.zk.ZKHelixManager;
import org.apache.log4j.Logger;
-
+/**
+ * Obtain one of a set of Helix cluster managers, organized by the backing system.
+ */
public final class HelixManagerFactory
{
private static final Logger logger = Logger.getLogger(HelixManagerFactory.class);
/**
- * Construct a zk-based cluster manager enforce all types (PARTICIPANT, CONTROLLER, and
- * SPECTATOR to have a name
+ * Construct a zk-based cluster manager that enforces all types (PARTICIPANT, CONTROLLER, and
+ * SPECTATOR) to have a name
*
* @param clusterName
* @param instanceName
* @param type
* @param zkAddr
- * @return
+ * @return a HelixManager backed by Zookeeper
*/
public static HelixManager getZKHelixManager(String clusterName,
String instanceName,
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixManagerProperties.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixManagerProperties.java b/helix-core/src/main/java/org/apache/helix/HelixManagerProperties.java
index f58dc27..77f6697 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixManagerProperties.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixManagerProperties.java
@@ -20,7 +20,6 @@ package org.apache.helix;
*/
import java.io.InputStream;
-import java.util.Arrays;
import java.util.Properties;
import org.apache.log4j.Logger;
@@ -37,6 +36,10 @@ public class HelixManagerProperties
private final Properties _properties = new Properties();
+ /**
+ * Initialize properties from a file
+ * @param propertyFileName
+ */
public HelixManagerProperties(String propertyFileName)
{
try
@@ -59,14 +62,18 @@ public class HelixManagerProperties
public HelixManagerProperties() {
// load empty properties
}
-
+
+ /**
+ * Get properties wrapped as {@link Properties}
+ * @return Properties
+ */
public Properties getProperties() {
return _properties;
}
/**
* get helix version
- * @return
+ * @return version read from properties
*/
public String getVersion() {
return this.getProperty("clustermanager.version");
@@ -76,7 +83,7 @@ public class HelixManagerProperties
* get property for key
*
* @param key
- * @return
+ * @return property associated by key
*/
public String getProperty(String key)
{
@@ -95,7 +102,7 @@ public class HelixManagerProperties
*
* @param version1
* @param version2
- * @return
+ * @return true if version1 >= version2, false otherwise
*/
static boolean versionNoLessThan(String version1, String version2) {
if (version1 == null || version2 == null) {
@@ -133,7 +140,7 @@ public class HelixManagerProperties
* false otherwise
*
* @param participantVersion
- * @return
+ * @return true if compatible, false otherwise
*/
public boolean isParticipantCompatible(String participantVersion) {
return isFeatureSupported("participant", participantVersion);
@@ -145,7 +152,7 @@ public class HelixManagerProperties
*
* @param featureName
* @param participantVersion
- * @return
+ * @return true if supported, false otherwise
*/
public boolean isFeatureSupported(String featureName, String participantVersion) {
String minSupportedVersion = getProperty("minimum_supported_version." + featureName);
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixProperty.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixProperty.java b/helix-core/src/main/java/org/apache/helix/HelixProperty.java
index 31ac50a..e60c409 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixProperty.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixProperty.java
@@ -40,26 +40,46 @@ public class HelixProperty
protected final ZNRecord _record;
+ /**
+ * Initialize the property with an identifier
+ * @param id
+ */
public HelixProperty(String id)
{
_record = new ZNRecord(id);
}
+ /**
+ * Initialize the property with an existing ZNRecord
+ * @param record
+ */
public HelixProperty(ZNRecord record)
{
_record = new ZNRecord(record);
}
+ /**
+ * Get the property identifier
+ * @return the property id
+ */
public final String getId()
{
return _record.getId();
}
+ /**
+ * Get the backing ZNRecord
+ * @return ZNRecord object associated with this property
+ */
public final ZNRecord getRecord()
{
return _record;
}
+ /**
+ * Set the changes to the backing ZNRecord
+ * @param deltaList list of ZNRecord updates to be made
+ */
public final void setDeltaList(List<ZNRecordDelta> deltaList)
{
_record.setDeltaList(deltaList);
@@ -71,6 +91,10 @@ public class HelixProperty
return _record.toString();
}
+ /**
+ * Get the size of buckets defined
+ * @return the bucket size, or 0 if not defined
+ */
public int getBucketSize()
{
String bucketSizeStr =
@@ -90,6 +114,10 @@ public class HelixProperty
return bucketSize;
}
+ /**
+ * Set the size of buckets defined
+ * @param bucketSize the bucket size (will default to 0 if negative)
+ */
public void setBucketSize(int bucketSize)
{
if (bucketSize <= 0)
@@ -99,11 +127,11 @@ public class HelixProperty
}
/**
- * static method that convert ZNRecord to an instance that subclasses HelixProperty
+ * static method that converts ZNRecord to an instance that subclasses HelixProperty
*
- * @param clazz
- * @param record
- * @return
+ * @param clazz subclass of HelixProperty
+ * @param record the ZNRecord describing the property
+ * @return typed instance corresponding to the record, or null if conversion fails
*/
public static <T extends HelixProperty> T convertToTypedInstance(Class<T> clazz,
ZNRecord record)
@@ -127,6 +155,12 @@ public class HelixProperty
return null;
}
+ /**
+ * Convert a collection of records to typed properties
+ * @param clazz Subclass of HelixProperty
+ * @param records the ZNRecords describing the property
+ * @return list of typed instances for which the conversion succeeded, or null if records is null
+ */
public static <T extends HelixProperty> List<T> convertToTypedList(Class<T> clazz,
Collection<ZNRecord> records)
{
@@ -147,6 +181,11 @@ public class HelixProperty
return decorators;
}
+ /**
+ * Converts a list of records to a map of the record identifier to typed properties
+ * @param records the ZNRecords to convert
+ * @return id --> HelixProperty subclass map
+ */
public static <T extends HelixProperty> Map<String, T> convertListToMap(List<T> records)
{
if (records == null)
@@ -162,6 +201,11 @@ public class HelixProperty
return decorators;
}
+ /**
+ * Convert typed properties to a list of records
+ * @param typedInstances objects subclassing HelixProperty
+ * @return a list of ZNRecord objects
+ */
public static <T extends HelixProperty> List<ZNRecord> convertToList(List<T> typedInstances)
{
if (typedInstances == null)
@@ -178,12 +222,20 @@ public class HelixProperty
return records;
}
+ /**
+ * Change the state of batch messaging
+ * @param enable true to enable, false to disable
+ */
public void setBatchMessageMode(boolean enable)
{
_record.setSimpleField(HelixPropertyAttribute.BATCH_MESSAGE_MODE.toString(), ""
+ enable);
}
+ /**
+ * Get the state of batch messaging
+ * @return true if enabled, false if disabled
+ */
public boolean getBatchMessageMode()
{
String enableStr =
@@ -202,7 +254,11 @@ public class HelixProperty
return false;
}
}
-
+
+ /**
+ * Get property validity
+ * @return true if valid, false if invalid
+ */
public boolean isValid()
{
return true;
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/HelixTimerTask.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/HelixTimerTask.java b/helix-core/src/main/java/org/apache/helix/HelixTimerTask.java
index 0b7edb9..c975867 100644
--- a/helix-core/src/main/java/org/apache/helix/HelixTimerTask.java
+++ b/helix-core/src/main/java/org/apache/helix/HelixTimerTask.java
@@ -19,17 +19,18 @@ package org.apache.helix;
* under the License.
*/
+/**
+ * Interface for defining a generic task to run periodically.
+ */
public abstract class HelixTimerTask
{
/**
- * Timer task starts
- *
+ * Start a timer task
*/
public abstract void start();
/**
- * Timer task stops
- *
+ * Stop a timer task
*/
public abstract void stop();
}
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/IdealStateChangeListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/IdealStateChangeListener.java b/helix-core/src/main/java/org/apache/helix/IdealStateChangeListener.java
index d387593..8104811 100644
--- a/helix-core/src/main/java/org/apache/helix/IdealStateChangeListener.java
+++ b/helix-core/src/main/java/org/apache/helix/IdealStateChangeListener.java
@@ -23,7 +23,9 @@ import java.util.List;
import org.apache.helix.model.IdealState;
-
+/**
+ * Interface to implement to listen for changes to the ideal state of resources.
+ */
public interface IdealStateChangeListener
{
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/InstanceConfigChangeListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/InstanceConfigChangeListener.java b/helix-core/src/main/java/org/apache/helix/InstanceConfigChangeListener.java
index 5d55be1..68446fc 100644
--- a/helix-core/src/main/java/org/apache/helix/InstanceConfigChangeListener.java
+++ b/helix-core/src/main/java/org/apache/helix/InstanceConfigChangeListener.java
@@ -23,6 +23,9 @@ import java.util.List;
import org.apache.helix.model.InstanceConfig;
+/**
+ * Interface to implement to listen for changes to instance configurations.
+ */
public interface InstanceConfigChangeListener
{
/**
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/LiveInstanceChangeListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/LiveInstanceChangeListener.java b/helix-core/src/main/java/org/apache/helix/LiveInstanceChangeListener.java
index 79b0845..1b85982 100644
--- a/helix-core/src/main/java/org/apache/helix/LiveInstanceChangeListener.java
+++ b/helix-core/src/main/java/org/apache/helix/LiveInstanceChangeListener.java
@@ -23,7 +23,9 @@ import java.util.List;
import org.apache.helix.model.LiveInstance;
-
+/**
+ * Interface to implement to listen for live instance changes.
+ */
public interface LiveInstanceChangeListener
{
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/LiveInstanceInfoProvider.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/LiveInstanceInfoProvider.java b/helix-core/src/main/java/org/apache/helix/LiveInstanceInfoProvider.java
index 1651839..03f6061 100644
--- a/helix-core/src/main/java/org/apache/helix/LiveInstanceInfoProvider.java
+++ b/helix-core/src/main/java/org/apache/helix/LiveInstanceInfoProvider.java
@@ -18,10 +18,13 @@ package org.apache.helix;
* under the License.
*/
+/**
+ * Interface to provide additional information about a live instance at creation time
+ */
public interface LiveInstanceInfoProvider
{
/**
- * Callback function that is called by HelixManager before it creates LiveInstance Zk Node.
+ * Callback function that is called by HelixManager before it creates LiveInstance Zk Node.
* The ZNRecord returned by this function
*
* @see ZkHelixManager#addLiveInstance()
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/MessageListener.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/MessageListener.java b/helix-core/src/main/java/org/apache/helix/MessageListener.java
index cb3776e..8b15e5f 100644
--- a/helix-core/src/main/java/org/apache/helix/MessageListener.java
+++ b/helix-core/src/main/java/org/apache/helix/MessageListener.java
@@ -23,7 +23,9 @@ import java.util.List;
import org.apache.helix.model.Message;
-
+/**
+ * Interface to implement when there is a change to messages
+ */
public interface MessageListener
{
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/NotificationContext.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/NotificationContext.java b/helix-core/src/main/java/org/apache/helix/NotificationContext.java
index f683e77..38f8c7b 100644
--- a/helix-core/src/main/java/org/apache/helix/NotificationContext.java
+++ b/helix-core/src/main/java/org/apache/helix/NotificationContext.java
@@ -22,9 +22,14 @@ package org.apache.helix;
import java.util.HashMap;
import java.util.Map;
+/**
+ * Metadata associated with a notification event and the current state of the cluster
+ */
public class NotificationContext
{
- // keys used for object map
+ /**
+ * keys used for object map
+ */
public enum MapKey {
TASK_EXECUTOR,
CURRENT_STATE_UPDATE,
@@ -38,72 +43,129 @@ public class NotificationContext
private String _pathChanged;
private String _eventName;
+ /**
+ * Get the name associated with the event
+ * @return event name
+ */
public String getEventName()
{
return _eventName;
}
+ /**
+ * Set the name associated with the event
+ * @param eventName the event name
+ */
public void setEventName(String eventName)
{
_eventName = eventName;
}
+ /**
+ * Instantiate with a HelixManager
+ * @param manager {@link HelixManager} object
+ */
public NotificationContext(HelixManager manager)
{
_manager = manager;
_map = new HashMap<String, Object>();
}
+ /**
+ * Get the HelixManager associated with this notification
+ * @return {@link HelixManager} object
+ */
public HelixManager getManager()
{
return _manager;
}
+ /**
+ * Get a map describing the update (keyed on {@link MapKey})
+ * @return the object map describing the update
+ */
public Map<String, Object> getMap()
{
return _map;
}
+ /**
+ * Get the type of the notification
+ * @return the notification type
+ */
public Type getType()
{
return _type;
}
+ /**
+ * Set the HelixManager associated with this notification
+ * @param manager {@link HelixManager} object
+ */
public void setManager(HelixManager manager)
{
this._manager = manager;
}
+ /**
+ * Add notification metadata
+ * @param key String value of a {@link MapKey}
+ * @param value
+ */
public void add(String key, Object value)
{
_map.put(key, value);
}
+ /**
+ * Set the notification map
+ * @param map
+ */
public void setMap(Map<String, Object> map)
{
this._map = map;
}
+ /**
+ * Set the notification type
+ * @param {@link Type} object
+ */
public void setType(Type type)
{
this._type = type;
}
+ /**
+ * Get a notification attribute
+ * @param key String from a {@link MapKey}
+ * @return
+ */
public Object get(String key)
{
return _map.get(key);
}
+ /**
+ * Valid types of notifications
+ */
public enum Type
{
INIT, CALLBACK, FINALIZE
}
+ /**
+ * Get the path changed status
+ * @return String corresponding to the path change
+ */
public String getPathChanged()
{
return _pathChanged;
}
+ /**
+ * Set the path changed status
+ * @param pathChanged
+ */
public void setPathChanged(String pathChanged)
{
this._pathChanged = pathChanged;
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/f38b3da2/helix-core/src/main/java/org/apache/helix/PreConnectCallback.java
----------------------------------------------------------------------
diff --git a/helix-core/src/main/java/org/apache/helix/PreConnectCallback.java b/helix-core/src/main/java/org/apache/helix/PreConnectCallback.java
index 9d65a14..45da706 100644
--- a/helix-core/src/main/java/org/apache/helix/PreConnectCallback.java
+++ b/helix-core/src/main/java/org/apache/helix/PreConnectCallback.java
@@ -19,6 +19,9 @@ package org.apache.helix;
* under the License.
*/
+/**
+ * Called to allow definition of tasks prior to connecting to Zookeeper
+ */
public interface PreConnectCallback
{
/**