Improved java docs
Project: http://git-wip-us.apache.org/repos/asf/oodt/repo Commit: http://git-wip-us.apache.org/repos/asf/oodt/commit/07aea0d3 Tree: http://git-wip-us.apache.org/repos/asf/oodt/tree/07aea0d3 Diff: http://git-wip-us.apache.org/repos/asf/oodt/diff/07aea0d3 Branch: refs/heads/development Commit: 07aea0d364d6911a8a70221f3f6087749dc4e379 Parents: df1db1e Author: Imesha Sudasingha <imesha.sudasin...@gmail.com> Authored: Wed Aug 23 19:32:48 2017 +0530 Committer: Imesha Sudasingha <imesha.sudasin...@gmail.com> Committed: Thu Oct 12 08:07:14 2017 +0530 ---------------------------------------------------------------------- .../org/apache/oodt/config/ConfigEventType.java | 5 ++++ .../DistributedConfigurationManager.java | 15 +++++++++++- .../DistributedConfigurationPublisher.java | 17 ++++++++++++++ .../oodt/config/distributed/cli/CLIAction.java | 24 ++++++++++++++++++++ .../config/distributed/cli/ConfigPublisher.java | 8 +++++++ .../config/distributed/utils/ConfigUtils.java | 5 ++++ .../config/distributed/utils/CuratorUtils.java | 19 ++++++++++------ .../AbstractDistributedConfigurationTest.java | 7 ++++++ 8 files changed, 92 insertions(+), 8 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/oodt/blob/07aea0d3/config/src/main/java/org/apache/oodt/config/ConfigEventType.java ---------------------------------------------------------------------- diff --git a/config/src/main/java/org/apache/oodt/config/ConfigEventType.java b/config/src/main/java/org/apache/oodt/config/ConfigEventType.java index 8a465b0..15c68b2 100644 --- a/config/src/main/java/org/apache/oodt/config/ConfigEventType.java +++ b/config/src/main/java/org/apache/oodt/config/ConfigEventType.java @@ -17,6 +17,11 @@ package org.apache.oodt.config; +/** + * An enum class to represent distributed configuration management related events. + * + * @author Imesha Sudasingha + */ public enum ConfigEventType { PUBLISH("publish"), CLEAR("clear"); http://git-wip-us.apache.org/repos/asf/oodt/blob/07aea0d3/config/src/main/java/org/apache/oodt/config/distributed/DistributedConfigurationManager.java ---------------------------------------------------------------------- diff --git a/config/src/main/java/org/apache/oodt/config/distributed/DistributedConfigurationManager.java b/config/src/main/java/org/apache/oodt/config/distributed/DistributedConfigurationManager.java index 6dfb24b..fe36a02 100644 --- a/config/src/main/java/org/apache/oodt/config/distributed/DistributedConfigurationManager.java +++ b/config/src/main/java/org/apache/oodt/config/distributed/DistributedConfigurationManager.java @@ -47,6 +47,8 @@ import static org.apache.oodt.config.distributed.utils.ConfigUtils.getOODTProjec /** * Distributed configuration manager implementation. This class make use of a {@link CuratorFramework} instance to * connect to zookeeper. + * <p> + * This class can download configuration from zookeeper and clear configuration locally downloaded. * * @author Imesha Sudasingha. */ @@ -63,6 +65,7 @@ public class DistributedConfigurationManager extends ConfigurationManager { /** {@link NodeCache} to watch for configuration change notifications */ private NodeCache nodeCache; + /** This is the listener which is going to be notified on the configuration changes happening in zookeeper */ private NodeCacheListener nodeCacheListener = new NodeCacheListener() { @Override public void nodeChanged() throws Exception { @@ -150,6 +153,12 @@ public class DistributedConfigurationManager extends ConfigurationManager { logger.info("NodeCache for watching configuration changes started successfully"); } + /** + * {@inheritDoc} + * <p> + * Since distributed configuration management treats properties files and configuration files in two different ways, + * they are loaded in different manners. + */ @Override public synchronized void loadConfiguration() throws Exception { logger.debug("Loading properties for : {}", component); @@ -225,7 +234,11 @@ public class DistributedConfigurationManager extends ConfigurationManager { savedFiles.add(localFilePath); } - /** {@inheritDoc} */ + /** + * {@inheritDoc} + * <p> + * This method will additionally delete all the files downloaded earlier from zookeeper. + */ @Override public synchronized void clearConfiguration() { for (String path : savedFiles) { http://git-wip-us.apache.org/repos/asf/oodt/blob/07aea0d3/config/src/main/java/org/apache/oodt/config/distributed/DistributedConfigurationPublisher.java ---------------------------------------------------------------------- diff --git a/config/src/main/java/org/apache/oodt/config/distributed/DistributedConfigurationPublisher.java b/config/src/main/java/org/apache/oodt/config/distributed/DistributedConfigurationPublisher.java index 9d3dd4a..23ff71d 100644 --- a/config/src/main/java/org/apache/oodt/config/distributed/DistributedConfigurationPublisher.java +++ b/config/src/main/java/org/apache/oodt/config/distributed/DistributedConfigurationPublisher.java @@ -186,6 +186,13 @@ public class DistributedConfigurationPublisher { client.setData().forPath(zNodePaths.getNotificationsZNodePath(), type.toString().getBytes()); } + /** + * Publishes configuration from local files to zookeeper. + * + * @param fileMapping source file to ZNode path mappings + * @param isProperties if true, files will be stored under {@link ZNodePaths#propertiesZNodePath} + * @throws Exception + */ private void publishConfiguration(Map<String, String> fileMapping, boolean isProperties) throws Exception { for (Map.Entry<String, String> entry : fileMapping.entrySet()) { String filePath = entry.getKey(); @@ -220,6 +227,16 @@ public class DistributedConfigurationPublisher { } } + /** + * Verifies whether the content in local files given by keys of the <pre>fileMapping</pre> are identical to the + * configuration stored in zookeeper under ZNode paths given by <pre>${prefix}/{fileMapping.value}</pre> + * + * @param fileMapping src file to znode path mappings + * @param isProperties if true, treated as properties files and will look under {@link + * ZNodePaths#propertiesZNodePath} + * @return true, if all the configuration verification was successful and no error was detected. + * @throws Exception + */ private boolean verifyPublishedConfiguration(Map<String, String> fileMapping, boolean isProperties) throws Exception { boolean noError = true; for (Map.Entry<String, String> entry : fileMapping.entrySet()) { http://git-wip-us.apache.org/repos/asf/oodt/blob/07aea0d3/config/src/main/java/org/apache/oodt/config/distributed/cli/CLIAction.java ---------------------------------------------------------------------- diff --git a/config/src/main/java/org/apache/oodt/config/distributed/cli/CLIAction.java b/config/src/main/java/org/apache/oodt/config/distributed/cli/CLIAction.java index 50e567a..38b1775 100644 --- a/config/src/main/java/org/apache/oodt/config/distributed/cli/CLIAction.java +++ b/config/src/main/java/org/apache/oodt/config/distributed/cli/CLIAction.java @@ -33,6 +33,7 @@ import static org.apache.oodt.config.Constants.Properties.ZK_CONNECT_STRING; /** * {@link CmdLineAction} specifying the verify, publish and clear tasks of distributed configuration management. * + * @see ConfigPublisher * @author Imesha Sudasingha */ public class CLIAction extends CmdLineAction { @@ -83,6 +84,13 @@ public class CLIAction extends CmdLineAction { System.out.println("Exiting CLI ..."); } + /** + * Publishes configuration files (which are stored locally at the moment) specified in {@link #configFile} to + * zookeeper. + * + * @param publisher {@link DistributedConfigurationPublisher} instance + * @throws Exception + */ private void publish(DistributedConfigurationPublisher publisher) throws Exception { System.out.println(); System.out.println(String.format("Publishing configuration for : %s", publisher.getComponent())); @@ -91,6 +99,14 @@ public class CLIAction extends CmdLineAction { System.out.println(); } + /** + * Verifies whether the content in the local files (which were published to zookeeper) are identical to the content + * that has actually been published. The file mapping is obtained from {@link #configFile}. Will print error + * messages accordingly if the verification fails. + * + * @param publisher {@link DistributedConfigurationPublisher} instance + * @throws Exception + */ private void verify(DistributedConfigurationPublisher publisher) throws Exception { System.out.println(); System.out.println(String.format("Verifying configuration for : %s", publisher.getComponent())); @@ -103,6 +119,14 @@ public class CLIAction extends CmdLineAction { System.out.println(); } + /** + * Clears all configuration published to zookeeper This will simply delete {@link + * org.apache.oodt.config.distributed.ZNodePaths#configurationZNodePath} and {@link + * org.apache.oodt.config.distributed.ZNodePaths#propertiesZNodePath} along with its children from zookeeper. + * + * @param publisher {@link DistributedConfigurationPublisher} instance + * @throws Exception + */ private void clear(DistributedConfigurationPublisher publisher) throws Exception { System.out.println(); System.out.println(String.format("Clearing configuration for : %s", publisher.getComponent())); http://git-wip-us.apache.org/repos/asf/oodt/blob/07aea0d3/config/src/main/java/org/apache/oodt/config/distributed/cli/ConfigPublisher.java ---------------------------------------------------------------------- diff --git a/config/src/main/java/org/apache/oodt/config/distributed/cli/ConfigPublisher.java b/config/src/main/java/org/apache/oodt/config/distributed/cli/ConfigPublisher.java index f4c45a7..f6f89cf 100644 --- a/config/src/main/java/org/apache/oodt/config/distributed/cli/ConfigPublisher.java +++ b/config/src/main/java/org/apache/oodt/config/distributed/cli/ConfigPublisher.java @@ -23,6 +23,14 @@ import org.slf4j.LoggerFactory; /** * Class with main method which gets invoked by the CLI. + * <p> + * Basic usage: + * <pre> + * ./config-publisher -connectString localhost:2181 </> -a {publish|verify|clear} + * </pre> + * <p> + * Optionally, users can give <pre>-notify</pre> option to notify the listening OODT components on the configuration + * change. * * @author Imesha Sudasingha */ http://git-wip-us.apache.org/repos/asf/oodt/blob/07aea0d3/config/src/main/java/org/apache/oodt/config/distributed/utils/ConfigUtils.java ---------------------------------------------------------------------- diff --git a/config/src/main/java/org/apache/oodt/config/distributed/utils/ConfigUtils.java b/config/src/main/java/org/apache/oodt/config/distributed/utils/ConfigUtils.java index 6e4d677..bbb24b0 100644 --- a/config/src/main/java/org/apache/oodt/config/distributed/utils/ConfigUtils.java +++ b/config/src/main/java/org/apache/oodt/config/distributed/utils/ConfigUtils.java @@ -27,6 +27,11 @@ import org.slf4j.LoggerFactory; import static org.apache.oodt.config.Constants.Properties.OODT_PROJECT; import static org.apache.oodt.config.Constants.SEPARATOR; +/** + * A utility class to be used for configuration related tasks. + * + * @author Imesha Sudasingha + */ public class ConfigUtils { private static final Logger logger = LoggerFactory.getLogger(ConfigUtils.class); http://git-wip-us.apache.org/repos/asf/oodt/blob/07aea0d3/config/src/main/java/org/apache/oodt/config/distributed/utils/CuratorUtils.java ---------------------------------------------------------------------- diff --git a/config/src/main/java/org/apache/oodt/config/distributed/utils/CuratorUtils.java b/config/src/main/java/org/apache/oodt/config/distributed/utils/CuratorUtils.java index c559f55..57aefff 100644 --- a/config/src/main/java/org/apache/oodt/config/distributed/utils/CuratorUtils.java +++ b/config/src/main/java/org/apache/oodt/config/distributed/utils/CuratorUtils.java @@ -38,6 +38,11 @@ import static org.apache.oodt.config.Constants.Properties.ZK_PROPERTIES_FILE; import static org.apache.oodt.config.Constants.ZPaths.NAMESPACE; import static org.apache.oodt.config.Constants.ZPaths.SEPARATOR; +/** + * A set of utility methods to be used to do complex operations on zookeeper using {@link CuratorFramework} + * + * @author Imesha Sudasingha + */ public class CuratorUtils { private static final Logger logger = LoggerFactory.getLogger(CuratorUtils.class); @@ -88,8 +93,8 @@ public class CuratorUtils { } /** - * Builds a {@link CuratorFramework} instance with given connect string. Will use the {@link CuratorUtils#logger} for - * logging. + * Builds a {@link CuratorFramework} instance with given connect string. Will use the {@link CuratorUtils#logger} + * for logging. * * @param connectString zookeeper connect string * @return CuratorFramework instance created @@ -112,11 +117,11 @@ public class CuratorUtils { int maxRetryCount = Integer.parseInt(System.getProperty(Constants.Properties.ZK_CONNECTION_TIMEOUT, "3")); CuratorFrameworkFactory.Builder builder = CuratorFrameworkFactory.builder() - .namespace(NAMESPACE) - .connectString(connectString) - .retryPolicy(new ExponentialBackoffRetry(retryInitialWaitMs, maxRetryCount)) - .connectionTimeoutMs(connectionTimeoutMs) - .sessionTimeoutMs(sessionTimeoutMs); + .namespace(NAMESPACE) + .connectString(connectString) + .retryPolicy(new ExponentialBackoffRetry(retryInitialWaitMs, maxRetryCount)) + .connectionTimeoutMs(connectionTimeoutMs) + .sessionTimeoutMs(sessionTimeoutMs); /* * If authorization information is available, those will be added to the client. NOTE: These auth info are http://git-wip-us.apache.org/repos/asf/oodt/blob/07aea0d3/config/src/main/java/org/apache/oodt/config/test/AbstractDistributedConfigurationTest.java ---------------------------------------------------------------------- diff --git a/config/src/main/java/org/apache/oodt/config/test/AbstractDistributedConfigurationTest.java b/config/src/main/java/org/apache/oodt/config/test/AbstractDistributedConfigurationTest.java index f8d421e..707be01 100644 --- a/config/src/main/java/org/apache/oodt/config/test/AbstractDistributedConfigurationTest.java +++ b/config/src/main/java/org/apache/oodt/config/test/AbstractDistributedConfigurationTest.java @@ -25,6 +25,13 @@ import org.junit.BeforeClass; import static org.apache.oodt.config.Constants.Properties.ZK_CONNECT_STRING; +/** + * An abstract class to be used for distributed configuration management related tests. Any test related to any OODT + * component can extend this class and connect to the {@link #zookeeper} instance started by this class for further + * steps. + * + * @author Imesha Sudasingha + */ public abstract class AbstractDistributedConfigurationTest { protected static TestingServer zookeeper;