accumulo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From els...@apache.org
Subject [3/3] git commit: ACCUMULO-1974 Javadoc for core/conf.
Date Mon, 16 Dec 2013 19:27:17 GMT
ACCUMULO-1974 Javadoc for core/conf.

Signed-off-by: Josh Elser <elserj@apache.org>


Project: http://git-wip-us.apache.org/repos/asf/accumulo/repo
Commit: http://git-wip-us.apache.org/repos/asf/accumulo/commit/3a2e0a92
Tree: http://git-wip-us.apache.org/repos/asf/accumulo/tree/3a2e0a92
Diff: http://git-wip-us.apache.org/repos/asf/accumulo/diff/3a2e0a92

Branch: refs/heads/master
Commit: 3a2e0a925002a2cb8e408791a7f0d2a0fa2f4c96
Parents: 74c8932
Author: Bill Havanki <bhavanki@cloudera.com>
Authored: Fri Dec 6 13:52:02 2013 -0500
Committer: Josh Elser <elserj@apache.org>
Committed: Mon Dec 16 14:15:48 2013 -0500

----------------------------------------------------------------------
 .../core/conf/AccumuloConfiguration.java        | 176 ++++++++++++++++++-
 .../accumulo/core/conf/ConfigSanityCheck.java   |  13 ++
 .../accumulo/core/conf/ConfigurationCopy.java   |  29 +++
 .../core/conf/DefaultConfiguration.java         |  21 ++-
 .../org/apache/accumulo/core/conf/Property.java | 124 ++++++++++++-
 .../apache/accumulo/core/conf/PropertyType.java |  14 ++
 .../accumulo/core/conf/SiteConfiguration.java   |  35 +++-
 7 files changed, 399 insertions(+), 13 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/accumulo/blob/3a2e0a92/core/src/main/java/org/apache/accumulo/core/conf/AccumuloConfiguration.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/conf/AccumuloConfiguration.java b/core/src/main/java/org/apache/accumulo/core/conf/AccumuloConfiguration.java
index 3aed8c1..b3b82d3 100644
--- a/core/src/main/java/org/apache/accumulo/core/conf/AccumuloConfiguration.java
+++ b/core/src/main/java/org/apache/accumulo/core/conf/AccumuloConfiguration.java
@@ -30,12 +30,27 @@ import org.apache.accumulo.core.client.impl.Tables;
 import org.apache.accumulo.start.classloader.vfs.AccumuloVFSClassLoader;
 import org.apache.log4j.Logger;
 
+/**
+ * A configuration object.
+ */
 public abstract class AccumuloConfiguration implements Iterable<Entry<String,String>>
{
 
+  /**
+   * A filter for properties, based on key.
+   */
   public static interface PropertyFilter {
+    /**
+     * Determines whether to accept a property based on its key.
+     *
+     * @param key property key
+     * @return true to accept property (pass filter)
+     */
     boolean accept(String key);
   }
 
+  /**
+   * A filter that accepts all properties.
+   */
   public static class AllFilter implements PropertyFilter {
     @Override
     public boolean accept(String key) {
@@ -43,10 +58,18 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
     }
   }
 
+  /**
+   * A filter that accepts properties whose keys begin with a prefix.
+   */
   public static class PrefixFilter implements PropertyFilter {
 
     private String prefix;
 
+    /**
+     * Creates a new filter.
+     *
+     * @param prefix prefix of property keys to accept
+     */
     public PrefixFilter(String prefix) {
       this.prefix = prefix;
     }
@@ -59,10 +82,30 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
 
   private static final Logger log = Logger.getLogger(AccumuloConfiguration.class);
   
+  /**
+   * Gets a property value from this configuration.
+   *
+   * @param property property to get
+   * @return property value
+   */
   public abstract String get(Property property);
   
+  /**
+   * Returns property key/value pairs in this configuration. The pairs include
+   * those defined in this configuration which pass the given filter, and those
+   * supplied from the parent configuration which are not included from here.
+   *
+   * @param props properties object to populate
+   * @param filter filter for accepting properties from this configuration
+   */
   public abstract void getProperties(Map<String,String> props, PropertyFilter filter);
 
+  /**
+   * Returns an iterator over property key/value pairs in this configuration.
+   * Some implementations may elect to omit properties.
+   *
+   * @return iterator over properties
+   */
   @Override
   public Iterator<Entry<String,String>> iterator() {
     TreeMap<String,String> entries = new TreeMap<String,String>();
@@ -80,11 +123,11 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
   }
   
   /**
-   * This method returns all properties in a map of string->string under the given prefix
property.
-   * 
-   * @param property
-   *          the prefix property, and must be of type PropertyType.PREFIX
-   * @return a map of strings to strings of the resulting properties
+   * Gets all properties under the given prefix in this configuration.
+   *
+   * @param property prefix property, must be of type PropertyType.PREFIX
+   * @return a map of property keys to values
+   * @throws IllegalArgumentException if property is not a prefix
    */
   public Map<String,String> getAllPropertiesWithPrefix(Property property) {
     checkType(property, PropertyType.PREFIX);
@@ -94,6 +137,15 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
     return propMap;
   }
   
+  /**
+   * Gets a property of type {@link PropertyType#MEMORY}, interpreting the
+   * value properly.
+   *
+   * @param property property to get
+   * @return property value
+   * @throws IllegalArgumentException if the property is of the wrong type
+   * @see #getMemoryInBytes(String)
+   */
   public long getMemoryInBytes(Property property) {
     checkType(property, PropertyType.MEMORY);
     
@@ -101,6 +153,14 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
     return getMemoryInBytes(memString);
   }
   
+  /**
+   * Interprets a string specifying a memory size. A memory size is specified
+   * as a long integer followed by an optional B (bytes), K (KB), M (MB), or
+   * G (GB).
+   *
+   * @param str string value
+   * @return interpreted memory size
+   */
   static public long getMemoryInBytes(String str) {
     int multiplier = 0;
     switch (str.charAt(str.length() - 1)) {
@@ -117,12 +177,30 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
     }
   }
   
+  /**
+   * Gets a property of type {@link PropertyType#TIMEDURATION}, interpreting the
+   * value properly.
+   *
+   * @param property property to get
+   * @return property value
+   * @throws IllegalArgumentException if the property is of the wrong type
+   * @see #getTimeInMillis(String)
+   */
   public long getTimeInMillis(Property property) {
     checkType(property, PropertyType.TIMEDURATION);
     
     return getTimeInMillis(get(property));
   }
   
+  /**
+   * Interprets a string specifying a time duration. A time duration is
+   * specified as a long integer followed by an optional d (days), h (hours),
+   * m (minutes), s (seconds), or ms (milliseconds). A value without a unit
+   * is interpreted as seconds.
+   *
+   * @param str string value
+   * @return interpreted time duration in milliseconds
+   */
   static public long getTimeInMillis(String str) {
     int multiplier = 1;
     switch (str.charAt(str.length() - 1)) {
@@ -143,23 +221,56 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
     }
   }
   
+  /**
+   * Gets a property of type {@link PropertyType#BOOLEAN}, interpreting the
+   * value properly (using <code>Boolean.parseBoolean()</code>).
+   *
+   * @param property property to get
+   * @return property value
+   * @throws IllegalArgumentException if the property is of the wrong type
+   */
   public boolean getBoolean(Property property) {
     checkType(property, PropertyType.BOOLEAN);
     return Boolean.parseBoolean(get(property));
   }
   
+  /**
+   * Gets a property of type {@link PropertyType#FRACTION}, interpreting the
+   * value properly.
+   *
+   * @param property property to get
+   * @return property value
+   * @throws IllegalArgumentException if the property is of the wrong type
+   * @see #getFraction(String)
+   */
   public double getFraction(Property property) {
     checkType(property, PropertyType.FRACTION);
     
     return getFraction(get(property));
   }
   
+  /**
+   * Interprets a string specifying a fraction. A fraction is specified as a
+   * double. An optional % at the end signifies a percentage.
+   *
+   * @param str string value
+   * @return interpreted fraction as a decimal value
+   */
   public double getFraction(String str) {
     if (str.charAt(str.length() - 1) == '%')
       return Double.parseDouble(str.substring(0, str.length() - 1)) / 100.0;
     return Double.parseDouble(str);
   }
   
+  /**
+   * Gets a property of type {@link PropertyType#PORT}, interpreting the
+   * value properly (as an integer within the range of non-privileged ports).
+   *
+   * @param property property to get
+   * @return property value
+   * @throws IllegalArgumentException if the property is of the wrong type
+   * @see #getTimeInMillis(String)
+   */
   public int getPort(Property property) {
     checkType(property, PropertyType.PORT);
     
@@ -174,6 +285,15 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
     return port;
   }
   
+  /**
+   * Gets a property of type {@link PropertyType#COUNT}, interpreting the
+   * value properly (as an integer).
+   *
+   * @param property property to get
+   * @return property value
+   * @throws IllegalArgumentException if the property is of the wrong type
+   * @see #getTimeInMillis(String)
+   */
   public int getCount(Property property) {
     checkType(property, PropertyType.COUNT);
     
@@ -181,6 +301,15 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
     return Integer.parseInt(countString);
   }
   
+  /**
+   * Gets a property of type {@link PropertyType#PATH}, interpreting the
+   * value properly, replacing supported environment variables.
+   *
+   * @param property property to get
+   * @return property value
+   * @throws IllegalArgumentException if the property is of the wrong type
+   * @see Constants#PATH_PROPERTY_ENV_VARS
+   */
   public String getPath(Property property) {
     checkType(property, PropertyType.PATH);
 
@@ -196,13 +325,21 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
     return pathString;
   }
 
+  /**
+   * Gets the default configuration.
+   *
+   * @return default configuration
+   * @see DefaultConfiguration#getInstance()
+   */
   public static synchronized DefaultConfiguration getDefaultConfiguration() {
     return DefaultConfiguration.getInstance();
   }
   
   /**
-   * Only here for Shell option-free start-up
-   * 
+   * Gets a site configuration parented by a default configuration. Only here
+   * for shell option-free start-up.
+   *
+   * @return configuration
    * @deprecated not for client use
    */
   @Deprecated
@@ -210,11 +347,27 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
     return SiteConfiguration.getInstance(getDefaultConfiguration());
   }
   
+  /**
+   * Gets the configuration specific to a table.
+   *
+   * @param conn connector (used to find table name)
+   * @param tableId table ID
+   * @return configuration containing table properties
+   * @throws TableNotFoundException if the table is not found
+   * @throws AccumuloException if there is a problem communicating to Accumulo
+   */
   public static AccumuloConfiguration getTableConfiguration(Connector conn, String tableId)
throws TableNotFoundException, AccumuloException {
     String tableName = Tables.getTableName(conn.getInstance(), tableId);
     return new ConfigurationCopy(conn.tableOperations().getProperties(tableName));
   }
   
+  /**
+   * Gets the maximum number of files per tablet from this configuration.
+   *
+   * @return maximum number of files per tablet
+   * @see Property#TABLE_FILE_MAX
+   * @see Property#TSERV_SCAN_MAX_OPENFILES
+   */
   public int getMaxFilesPerTablet() {
     int maxFilesPerTablet = getCount(Property.TABLE_FILE_MAX);
     if (maxFilesPerTablet <= 0) {
@@ -228,6 +381,15 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
   // overridden in ZooConfiguration
   public void invalidateCache() {}
   
+  /**
+   * Creates a new instance of a class specified in a configuration property.
+   *
+   * @param property property specifying class name
+   * @param base base class of type
+   * @param defaultInstance instance to use if creation fails
+   * @return new class instance, or default instance if creation failed
+   * @see AccumuloVFSClassLoader
+   */
   public <T> T instantiateClassProperty(Property property, Class<T> base, T defaultInstance)
{
     String clazzName = get(property);
     T instance = null;

http://git-wip-us.apache.org/repos/asf/accumulo/blob/3a2e0a92/core/src/main/java/org/apache/accumulo/core/conf/ConfigSanityCheck.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/conf/ConfigSanityCheck.java b/core/src/main/java/org/apache/accumulo/core/conf/ConfigSanityCheck.java
index 6724670..82c6dc9 100644
--- a/core/src/main/java/org/apache/accumulo/core/conf/ConfigSanityCheck.java
+++ b/core/src/main/java/org/apache/accumulo/core/conf/ConfigSanityCheck.java
@@ -20,11 +20,24 @@ import java.util.Map.Entry;
 
 import org.apache.log4j.Logger;
 
+/**
+ * A utility class for validating {@link AccumuloConfiguration} instances.
+ */
 public class ConfigSanityCheck {
   
   private static final Logger log = Logger.getLogger(ConfigSanityCheck.class);
   private static final String PREFIX = "BAD CONFIG ";
   
+  /**
+   * Validates the given configuration. A valid configuration contains only
+   * valid properties (i.e., defined or otherwise valid) that are not prefixes
+   * and whose values are formatted correctly for their property types. A valid
+   * configuration also contains a value for property
+   * {@link Property#INSTANCE_ZK_TIMEOUT} within a valid range.
+   *
+   * @param acuconf configuration
+   * @throws RuntimeException if the configuration fails validation
+   */
   public static void validate(AccumuloConfiguration acuconf) {
     for (Entry<String,String> entry : acuconf) {
       String key = entry.getKey();

http://git-wip-us.apache.org/repos/asf/accumulo/blob/3a2e0a92/core/src/main/java/org/apache/accumulo/core/conf/ConfigurationCopy.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/conf/ConfigurationCopy.java b/core/src/main/java/org/apache/accumulo/core/conf/ConfigurationCopy.java
index 756a97b..2b1945d 100644
--- a/core/src/main/java/org/apache/accumulo/core/conf/ConfigurationCopy.java
+++ b/core/src/main/java/org/apache/accumulo/core/conf/ConfigurationCopy.java
@@ -21,19 +21,36 @@ import java.util.HashMap;
 import java.util.Map;
 import java.util.Map.Entry;
 
+/**
+ * An {@link AccumuloConfiguration} which holds a flat copy of properties
+ * defined in another configuration
+ */
 public class ConfigurationCopy extends AccumuloConfiguration {
   final Map<String,String> copy = Collections.synchronizedMap(new HashMap<String,String>());
   
+  /**
+   * Creates a new configuration.
+   *
+   * @param config configuration property key/value pairs to copy
+   */
   public ConfigurationCopy(Map<String,String> config) {
     this(config.entrySet());
   }
   
+  /**
+   * Creates a new configuration.
+   *
+   * @param config configuration property iterable to use for copying
+   */
   public ConfigurationCopy(Iterable<Entry<String,String>> config) {
     for (Entry<String,String> entry : config) {
       copy.put(entry.getKey(), entry.getValue());
     }
   }
   
+  /**
+   * Creates a new empty configuration.
+   */
   public ConfigurationCopy() {
     this(new HashMap<String,String>());
   }
@@ -52,10 +69,22 @@ public class ConfigurationCopy extends AccumuloConfiguration {
     }
   }
   
+  /**
+   * Sets a property in this configuration.
+   *
+   * @param prop property to set
+   * @param value property value
+   */
   public void set(Property prop, String value) {
     copy.put(prop.getKey(), value);
   }
   
+  /**
+   * Sets a property in this configuration.
+   *
+   * @param key key of property to set
+   * @param value property value
+   */
   public void set(String key, String value) {
     copy.put(key, value);
   }

http://git-wip-us.apache.org/repos/asf/accumulo/blob/3a2e0a92/core/src/main/java/org/apache/accumulo/core/conf/DefaultConfiguration.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/conf/DefaultConfiguration.java b/core/src/main/java/org/apache/accumulo/core/conf/DefaultConfiguration.java
index cfc660e..81b7991 100644
--- a/core/src/main/java/org/apache/accumulo/core/conf/DefaultConfiguration.java
+++ b/core/src/main/java/org/apache/accumulo/core/conf/DefaultConfiguration.java
@@ -28,11 +28,21 @@ import java.util.TreeMap;
 
 import org.apache.log4j.Logger;
 
+/**
+ * An {@link AccumuloConfiguration} that contains only default values for
+ * properties. This class is a singleton.
+ */
 public class DefaultConfiguration extends AccumuloConfiguration {
   private static DefaultConfiguration instance = null;
   private static Logger log = Logger.getLogger(DefaultConfiguration.class);
   private Map<String,String> resolvedProps = null;
 
+  /**
+   * Gets an instance of this class.
+   *
+   * @return default configuration
+   * @throws RuntimeException if the default configuration is invalid
+   */
   synchronized public static DefaultConfiguration getInstance() {
     if (instance == null) {
       instance = new DefaultConfiguration();
@@ -64,6 +74,11 @@ public class DefaultConfiguration extends AccumuloConfiguration {
         props.put(entry.getKey(), entry.getValue());
   }
 
+  /**
+   * Generates HTML documentation on the default configuration.
+   *
+   * @param doc stream to write HTML to
+   */
   protected static void generateDocumentation(PrintStream doc) {
     // read static content from resources and output
     InputStream data = DefaultConfiguration.class.getResourceAsStream("config.html");
@@ -184,7 +199,11 @@ public class DefaultConfiguration extends AccumuloConfiguration {
   }
 
   /*
-   * Generate documentation for conf/accumulo-site.xml file usage
+   * Generates documentation for conf/accumulo-site.xml file usage. Arguments
+   * are: "--generate-doc", file to write to.
+   *
+   * @param args command-line arguments
+   * @throws IllegalArgumentException if args is invalid
    */
   public static void main(String[] args) throws FileNotFoundException {
     if (args.length == 2 && args[0].equals("--generate-doc")) {

http://git-wip-us.apache.org/repos/asf/accumulo/blob/3a2e0a92/core/src/main/java/org/apache/accumulo/core/conf/Property.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/conf/Property.java b/core/src/main/java/org/apache/accumulo/core/conf/Property.java
index 2ab3a20..1801a28 100644
--- a/core/src/main/java/org/apache/accumulo/core/conf/Property.java
+++ b/core/src/main/java/org/apache/accumulo/core/conf/Property.java
@@ -435,14 +435,32 @@ public enum Property {
     return this.key;
   }
 
+  /**
+   * Gets the key (string) for this property.
+   *
+   * @return keuy
+   */
   public String getKey() {
     return this.key;
   }
 
+  /**
+   * Gets the default value for this property exactly as provided in its
+   * definition (i.e., without interpolation or conversion to absolute paths).
+   *
+   * @return raw default value
+   */
   public String getRawDefaultValue() {
     return this.defaultValue;
   }
 
+  /**
+   * Gets the default value for this property. System properties are
+   * interpolated into the value if necessary.
+   *
+   * @return default value
+   * @see Interpolated
+   */
   public String getDefaultValue() {
     if (isInterpolated()) {
       PropertiesConfiguration pconf = new PropertiesConfiguration();
@@ -458,10 +476,20 @@ public enum Property {
     }
   }
 
+  /**
+   * Gets the type of this property.
+   *
+   * @return property type
+   */
   public PropertyType getType() {
     return this.type;
   }
 
+  /**
+   * Gets the description of this property.
+   *
+   * @return description
+   */
   public String getDescription() {
     return this.description;
   }
@@ -470,18 +498,44 @@ public enum Property {
     return hasAnnotation(Interpolated.class) || hasPrefixWithAnnotation(getKey(), Interpolated.class);
   }
 
+  /**
+   * Checks if this property is experimental.
+   *
+   * @return true if this property is experimental
+   * @see Experimental
+   */
   public boolean isExperimental() {
     return hasAnnotation(Experimental.class) || hasPrefixWithAnnotation(getKey(), Experimental.class);
   }
 
+  /**
+   * Checks if this property is deprecated.
+   *
+   * @return true if this property is deprecated
+   */
   public boolean isDeprecated() {
     return hasAnnotation(Deprecated.class) || hasPrefixWithAnnotation(getKey(), Deprecated.class);
   }
 
+  /**
+   * Checks if this property is sensitive.
+   *
+   * @return true if this property is sensitive
+   * @see Sensitive
+   */
   public boolean isSensitive() {
     return hasAnnotation(Sensitive.class) || hasPrefixWithAnnotation(getKey(), Sensitive.class);
   }
 
+  /**
+   * Checks if a property with the given key is sensitive. The key must be for
+   * a valid property, and must either itself be annotated as sensitive or have
+   * a prefix annotated as sensitive.
+   *
+   * @param key property key
+   * @return true if property is sensitive
+   * @see Sensitive
+   */
   public static boolean isSensitive(String key) {
     return hasPrefixWithAnnotation(key, Sensitive.class);
   }
@@ -529,6 +583,14 @@ public enum Property {
     return false;
   }
 
+  /**
+   * Checks if the given property key is valid. A valid property key is either
+   * equal to the key of some defined property or has a prefix matching some
+   * prefix defined in this class.
+   *
+   * @param key property key
+   * @return true if key is valid (recognized, or has a recognized prefix)
+   */
   public synchronized static boolean isValidPropertyKey(String key) {
     if (validProperties == null) {
       validProperties = new HashSet<String>();
@@ -546,6 +608,17 @@ public enum Property {
     return validProperties.contains(key) || isKeyValidlyPrefixed(key);
   }
 
+  /**
+   * Checks if the given property key is for a valid table property. A valid
+   * table property key is either equal to the key of some defined table
+   * property (which each start with {@link #TABLE_PREFIX}) or has a prefix
+   * matching {@link #TABLE_CONSTRAINT_PREFIX}, {@link #TABLE_ITERATOR_PREFIX},
+   * or {@link #TABLE_LOCALITY_GROUP_PREFIX}.
+   *
+   * @param key property key
+   * @return true if key is valid for a table property (recognized, or has a
+   * recognized prefix)
+   */
   public synchronized static boolean isValidTablePropertyKey(String key) {
     if (validTableProperties == null) {
       validTableProperties = new HashSet<String>();
@@ -564,14 +637,35 @@ public enum Property {
   private static final EnumSet<Property> fixedProperties = EnumSet.of(Property.TSERV_CLIENTPORT,
Property.TSERV_NATIVEMAP_ENABLED,
       Property.TSERV_SCAN_MAX_OPENFILES, Property.MASTER_CLIENTPORT, Property.GC_PORT);
 
+  /**
+   * Checks if the given property may be changed via Zookeeper, but not
+   * recognized until the restart of some relevant daemon.
+   *
+   * @param key property key
+   * @return true if property may be changed via Zookeeper but only heeded upon
+   * some restart
+   */
   public static boolean isFixedZooPropertyKey(Property key) {
     return fixedProperties.contains(key);
   }
 
+  /**
+   * Gets the set of "fixed" valid Zookeeper properties.
+   *
+   * @return fixed Zookeeper properties
+   * @see #isFixedZooPropertyKey(Property)
+   */
   public static Set<Property> getFixedProperties() {
     return fixedProperties;
   }
 
+  /**
+   * Checks if the given property key is valid for a property that may be
+   * changed via Zookeeper.
+   *
+   * @param key property key
+   * @return true if key's property may be changed via Zookeeper
+   */
   public static boolean isValidZooPropertyKey(String key) {
     // white list prefixes
     return key.startsWith(Property.TABLE_PREFIX.getKey()) || key.startsWith(Property.TSERV_PREFIX.getKey())
|| key.startsWith(Property.LOGGER_PREFIX.getKey())
@@ -580,6 +674,12 @@ public enum Property {
         || key.startsWith(Property.TABLE_COMPACTION_STRATEGY_PREFIX.getKey());
   }
 
+  /**
+   * Gets a {@link Property} instance with the given key.
+   *
+   * @param key property key
+   * @return property, or null if not found
+   */
   public static Property getPropertyByKey(String key) {
     for (Property prop : Property.values())
       if (prop.getKey().equals(key))
@@ -588,7 +688,9 @@ public enum Property {
   }
 
   /**
-   * @return true if this is a property whose value is expected to be a java class
+   * Checks if this property is expected to have a Java class as a value.
+   *
+   * @return true if this is property is a class property
    */
   public static boolean isClassProperty(String key) {
     return (key.startsWith(Property.TABLE_CONSTRAINT_PREFIX.getKey()) && key.substring(Property.TABLE_CONSTRAINT_PREFIX.getKey().length()).split("\\.").length
== 1)
@@ -599,6 +701,16 @@ public enum Property {
   // This is not a cache for loaded classes, just a way to avoid spamming the debug log
   static Map<String,Class<?>> loaded = Collections.synchronizedMap(new HashMap<String,Class<?>>());
 
+  /**
+   * Creates a new instance of a class specified in a configuration property.
+   *
+   * @param conf configuration containing property
+   * @param property property specifying class name
+   * @param base base class of type
+   * @param defaultInstance instance to use if creation fails
+   * @return new class instance, or default instance if creation failed
+   * @see AccumuloVFSClassLoader
+   */
   public static <T> T createInstanceFromPropertyName(AccumuloConfiguration conf, Property
property, Class<T> base, T defaultInstance) {
     String clazzName = conf.get(property);
     T instance = null;
@@ -619,6 +731,16 @@ public enum Property {
     return instance;
   }
 
+  /**
+   * Collects together properties from the given configuration pertaining to
+   * compaction strategies. The relevant properties all begin with the prefix
+   * in {@link #TABLE_COMPACTION_STRATEGY_PREFIX}. In the returned map, the
+   * prefix is removed from each property's key.
+   *
+   * @param tableConf configuration
+   * @return map of compaction strategy property keys and values, with the
+   * detection prefix removed from each key
+   */
   public static Map<String,String> getCompactionStrategyOptions(AccumuloConfiguration
tableConf) {
     Map<String,String> longNames = tableConf.getAllPropertiesWithPrefix(Property.TABLE_COMPACTION_STRATEGY_PREFIX);
     Map<String,String> result = new HashMap<String,String>();

http://git-wip-us.apache.org/repos/asf/accumulo/blob/3a2e0a92/core/src/main/java/org/apache/accumulo/core/conf/PropertyType.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/conf/PropertyType.java b/core/src/main/java/org/apache/accumulo/core/conf/PropertyType.java
index 688b186..304ccc5 100644
--- a/core/src/main/java/org/apache/accumulo/core/conf/PropertyType.java
+++ b/core/src/main/java/org/apache/accumulo/core/conf/PropertyType.java
@@ -21,6 +21,10 @@ import java.util.regex.Pattern;
 import org.apache.accumulo.core.Constants;
 import org.apache.hadoop.fs.Path;
 
+/**
+ * Types of {@link Property} values. Each type has a short name, a description,
+ * and a regex which valid values match. All of these fields are optional.
+ */
 public enum PropertyType {
   PREFIX(null, null, null),
   
@@ -82,10 +86,20 @@ public enum PropertyType {
     return shortname;
   }
   
+  /**
+   * Gets the description of this type.
+   *
+   * @return description
+   */
   String getFormatDescription() {
     return format;
   }
   
+  /**
+   * Checks if the given value is valid for this type.
+   *
+   * @return true if value is valid or null, or if this type has no regex
+   */
   public boolean isValidFormat(String value) {
     return (regex == null && value == null) ? true : regex.matcher(value).matches();
   }

http://git-wip-us.apache.org/repos/asf/accumulo/blob/3a2e0a92/core/src/main/java/org/apache/accumulo/core/conf/SiteConfiguration.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/conf/SiteConfiguration.java b/core/src/main/java/org/apache/accumulo/core/conf/SiteConfiguration.java
index 8f1f72a..ad9597c 100644
--- a/core/src/main/java/org/apache/accumulo/core/conf/SiteConfiguration.java
+++ b/core/src/main/java/org/apache/accumulo/core/conf/SiteConfiguration.java
@@ -22,6 +22,17 @@ import java.util.Map.Entry;
 import org.apache.hadoop.conf.Configuration;
 import org.apache.log4j.Logger;
 
+/**
+ * An {@link AccumuloConfiguration} which loads properties from an XML file,
+ * usually accumulo-site.xml. This implementation supports defaulting undefined
+ * property values to a parent configuration's definitions.
+ * <p>
+ * The system property "org.apache.accumulo.config.file" can be used to specify
+ * the location of the XML configuration file on the classpath. If the system
+ * property is not defined, it defaults to "accumulo-site.xml".
+ * <p>
+ * This class is a singleton.
+ */
 public class SiteConfiguration extends AccumuloConfiguration {
   private static final Logger log = Logger.getLogger(SiteConfiguration.class);
   
@@ -34,6 +45,13 @@ public class SiteConfiguration extends AccumuloConfiguration {
     SiteConfiguration.parent = parent;
   }
   
+  /**
+   * Gets an instance of this class. A new instance is only created on the first
+   * call, and so the parent configuration cannot be changed later.
+   *
+   * @param parent parent (default) configuration
+   * @throws RuntimeException if the configuration is invalid
+   */
   synchronized public static SiteConfiguration getInstance(AccumuloConfiguration parent)
{
     if (instance == null) {
       instance = new SiteConfiguration(parent);
@@ -79,7 +97,8 @@ public class SiteConfiguration extends AccumuloConfiguration {
   }
 
   /**
-   * method here to support testing, do not call
+   * Clears the configuration properties in this configuration (but not the
+   * parent). This method supports testing and should not be called.
    */
   public void clear() {
     getXmlConfig().clear();
@@ -87,7 +106,9 @@ public class SiteConfiguration extends AccumuloConfiguration {
   
   
   /**
-   * method here to support testing, do not call
+   * Clears the configuration properties in this configuration (but not the
+   * parent) and nulls it. This method supports testing and should not be
+   * called.
    */
   public synchronized void clearAndNull() {
     if (xmlConfig != null) {
@@ -97,14 +118,20 @@ public class SiteConfiguration extends AccumuloConfiguration {
   }
   
   /**
-   * method here to support testing, do not call
+   * Sets a property. This method supports testing and should not be called.
+   *
+   * @param property property to set
+   * @param value property value
    */
   public void set(Property property, String value) {
     set(property.getKey(), value);
   }
   
   /**
-   * method here to support testing, do not call
+   * Sets a property. This method supports testing and should not be called.
+   *
+   * @param key key of property to set
+   * @param value property value
    */
   public void set(String key, String value) {
     getXmlConfig().set(key, value);


Mime
View raw message