hbase-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From te...@apache.org
Subject svn commit: r1223024 - in /hbase/trunk/src: docbkx/ main/java/org/apache/hadoop/hbase/constraint/ test/java/org/apache/hadoop/hbase/constraint/
Date Sat, 24 Dec 2011 21:42:32 GMT
Author: tedyu
Date: Sat Dec 24 21:42:31 2011
New Revision: 1223024

URL: http://svn.apache.org/viewvc?rev=1223024&view=rev
Log:
HBASE-5070 Constraints implementation and javadoc changes (Jesse Yates)

Modified:
    hbase/trunk/src/docbkx/book.xml
    hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/BaseConstraint.java
    hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/Constraint.java
    hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/Constraints.java
    hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/package-info.java
    hbase/trunk/src/test/java/org/apache/hadoop/hbase/constraint/CheckConfigurationConstraint.java

Modified: hbase/trunk/src/docbkx/book.xml
URL: http://svn.apache.org/viewvc/hbase/trunk/src/docbkx/book.xml?rev=1223024&r1=1223023&r2=1223024&view=diff
==============================================================================
--- hbase/trunk/src/docbkx/book.xml (original)
+++ hbase/trunk/src/docbkx/book.xml Sat Dec 24 21:42:31 2011
@@ -870,7 +870,9 @@ System.out.println("md5 digest as string
 
   <section xml:id="constraints"><title>Constraints</title>
     <para>HBase currently supports 'constraints' in traditional (SQL) database parlance.
The advised usage for Constraints is in enforcing business rules for attributes in the table
(eg. make sure values are in the range 1-10).
-    Constraints could also be used to enforce referential integrity, but this is strongly
discouraged as it will dramatically decrease the write throughput of the tables where integrity
checking enabled.</para>
+    Constraints could also be used to enforce referential integrity, but this is strongly
discouraged as it will dramatically decrease the write throughput of the tables where integrity
checking is enabled.
+    Extensive documentation on using Constraints can be found at: <link xlink:href="http://hbase.apache.org/apidocs/org/apache/hadoop/hbase/constraint">Constraint</link>
since version 0.94.
+    </para>
   </section>
 
   </chapter>   <!--  schema design -->

Modified: hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/BaseConstraint.java
URL: http://svn.apache.org/viewvc/hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/BaseConstraint.java?rev=1223024&r1=1223023&r2=1223024&view=diff
==============================================================================
--- hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/BaseConstraint.java (original)
+++ hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/BaseConstraint.java Sat Dec
24 21:42:31 2011
@@ -17,25 +17,12 @@
  */
 package org.apache.hadoop.hbase.constraint;
 
-import org.apache.hadoop.conf.Configuration;
+import org.apache.hadoop.conf.Configured;
 
 /**
  * Base class to use when actually implementing a {@link Constraint}. It takes
  * care of getting and setting of configuration for the constraint.
  */
-public abstract class BaseConstraint implements
-    Constraint {
-
-  private Configuration conf;
-
-  @Override
-  public void setConf(Configuration conf) {
-    this.conf = conf;
-  }
-
-  @Override
-  public Configuration getConf() {
-    return this.conf;
-  }
+public abstract class BaseConstraint extends Configured implements Constraint {
 
 }

Modified: hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/Constraint.java
URL: http://svn.apache.org/viewvc/hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/Constraint.java?rev=1223024&r1=1223023&r2=1223024&view=diff
==============================================================================
--- hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/Constraint.java (original)
+++ hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/Constraint.java Sat Dec 24
21:42:31 2011
@@ -37,8 +37,8 @@ import org.apache.hadoop.hbase.client.Pu
  * {@link Constraints#disableConstraint(HTableDescriptor, Class)} for
  * enabling/disabling of a given {@link Constraint} after it has been added.
  * <p>
- * If a {@link Put} is not valid, the Constraint should throw some sort
- * {@link ConstraintException} indicating that the {@link Put} has failed. When
+ * If a {@link Put} is invalid, the Constraint should throw some sort of
+ * {@link ConstraintException}, indicating that the {@link Put} has failed. When
  * this exception is thrown, not further retries of the {@link Put} are
  * attempted nor are any other {@link Constraint Constraints} attempted (the
  * {@link Put} is clearly not valid). Therefore, there are performance
@@ -49,14 +49,17 @@ import org.apache.hadoop.hbase.client.Pu
  * {@link ConstraintException}, but instead throws a {@link RuntimeException},
  * the entire constraint processing mechanism ({@link ConstraintProcessor}) will
  * be unloaded from the table. This ensures that the region server is still
- * functional, but not more {@link Put Puts} will be checked via
+ * functional, but no more {@link Put Puts} will be checked via
  * {@link Constraint Constraints}.
  * <p>
- * Further, {@link Constraint Constraints} probably not be used to enforce
- * cross-table references as it will cause tremendous write slowdowns, but it is
- * possible.
+ * Further, {@link Constraint Constraints} should probably not be used to
+ * enforce cross-table references as it will cause tremendous write slowdowns,
+ * but it is possible.
  * <p>
  * NOTE: Implementing classes must have a nullary (no-args) constructor
+ *
+ * @see BaseConstraint
+ * @see Constraints
  */
 public interface Constraint extends Configurable {
 

Modified: hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/Constraints.java
URL: http://svn.apache.org/viewvc/hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/Constraints.java?rev=1223024&r1=1223023&r2=1223024&view=diff
==============================================================================
--- hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/Constraints.java (original)
+++ hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/Constraints.java Sat Dec
24 21:42:31 2011
@@ -83,8 +83,9 @@ public final class Constraints {
   public static void enable(HTableDescriptor desc) throws IOException {
     // if the CP has already been loaded, do nothing
     String clazz = ConstraintProcessor.class.getName();
-    if (desc.hasCoprocessor(clazz))
+    if (desc.hasCoprocessor(clazz)) {
       return;
+    }
 
     // add the constrain processor CP to the table
     desc.addCoprocessor(clazz);
@@ -164,9 +165,8 @@ public final class Constraints {
     // get the serialized version of the constraint
     String key = serializeConstraintClass(clazz);
     String value = desc.getValue(key);
-    if (value == null)
-      return null;
-    return new Pair<String, String>(key, value);
+
+    return value == null ? null : new Pair<String, String>(key, value);
   }
 
   /**
@@ -174,6 +174,12 @@ public final class Constraints {
    * <p>
    * This will overwrite any configuration associated with the previous
    * constraint of the same class.
+   * <p>
+   * Each constraint, when added to the table, will have a specific priority,
+   * dictating the order in which the {@link Constraint} will be run. A
+   * {@link Constraint} earlier in the list will be run before those later in
+   * the list. The same logic applies between two Constraints over time (earlier
+   * added is run first on the regionserver).
    * 
    * @param desc
    *          {@link HTableDescriptor} to add {@link Constraint Constraints}
@@ -201,6 +207,12 @@ public final class Constraints {
    * <p>
    * Adding the same constraint class twice will overwrite the first
    * constraint's configuration
+   * <p>
+   * Each constraint, when added to the table, will have a specific priority,
+   * dictating the order in which the {@link Constraint} will be run. A
+   * {@link Constraint} earlier in the list will be run before those later in
+   * the list. The same logic applies between two Constraints over time (earlier
+   * added is run first on the regionserver).
    * 
    * @param desc
    *          {@link HTableDescriptor} to add a {@link Constraint}
@@ -227,6 +239,11 @@ public final class Constraints {
 
   /**
    * Add a {@link Constraint} to the table with the given configuration
+   * <p>
+   * Each constraint, when added to the table, will have a specific priority,
+   * dictating the order in which the {@link Constraint} will be run. A
+   * {@link Constraint} added will run on the regionserver before those added to
+   * the {@link HTableDescriptor} later.
    * 
    * @param desc
    *          table descriptor to the constraint to
@@ -296,9 +313,11 @@ public final class Constraints {
   }
 
   /**
-   * Just write the class to the byte [] we are expecting
+   * Just write the class to a String representation of the class as a key for
+   * the {@link HTableDescriptor}
    * 
    * @param clazz
+   *          Constraint class to convert to a {@link HTableDescriptor} key
    * @return key to store in the {@link HTableDescriptor}
    */
   private static String serializeConstraintClass(
@@ -385,8 +404,8 @@ public final class Constraints {
   }
 
   /**
-   * Update the configuration for the {@link Constraint}. Does not change the
-   * order in which the constraint is run. If the
+   * Update the configuration for the {@link Constraint}; does not change the
+   * order in which the constraint is run.
    * 
    * @param desc
    *          {@link HTableDescriptor} to update
@@ -405,9 +424,10 @@ public final class Constraints {
     // get the entry for this class
     Pair<String, String> e = getKeyValueForClass(desc, clazz);
 
-    if (e == null)
+    if (e == null) {
       throw new IllegalArgumentException("Constraint: " + clazz.getName()
           + " is not associated with this table.");
+    }
 
     // clone over the configuration elements
     Configuration conf = new Configuration(configuration);
@@ -480,9 +500,10 @@ public final class Constraints {
       Class<? extends Constraint> clazz, boolean enabled) throws IOException {
     // get the original constraint
     Pair<String, String> entry = getKeyValueForClass(desc, clazz);
-    if (entry == null)
+    if (entry == null) {
       throw new IllegalArgumentException("Constraint: " + clazz.getName()
           + " is not associated with this table. You can't enable it!");
+    }
 
     // create a new configuration from that conf
     Configuration conf = readConfiguration(entry.getSecond());
@@ -511,8 +532,9 @@ public final class Constraints {
     // get the kv
     Pair<String, String> entry = getKeyValueForClass(desc, clazz);
     // its not enabled so just return false. In fact, its not even present!
-    if (entry == null)
+    if (entry == null) {
       return false;
+    }
 
     // get the info about the constraint
     Configuration conf = readConfiguration(entry.getSecond());
@@ -526,7 +548,10 @@ public final class Constraints {
    * @param desc
    *          To read from
    * @param classloader
-   *          To use when loading classes
+   *          To use when loading classes. If a special classloader is used on a
+   *          region, for instance, then that should be the classloader used to
+   *          load the constraints. This could also apply to unit-testing
+   *          situation, where want to ensure that class is reloaded or not.
    * @return List of configured {@link Constraint Constraints}
    * @throws IOException
    *           if any part of reading/arguments fails

Modified: hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/package-info.java
URL: http://svn.apache.org/viewvc/hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/package-info.java?rev=1223024&r1=1223023&r2=1223024&view=diff
==============================================================================
--- hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/package-info.java (original)
+++ hbase/trunk/src/main/java/org/apache/hadoop/hbase/constraint/package-info.java Sat Dec
24 21:42:31 2011
@@ -35,51 +35,54 @@
  For instance, you can ensure that a certain column family-column qualifier pair always has
a value between 1 and 10. 
  Otherwise, the {@link org.apache.hadoop.hbase.client.Put} is rejected and the data integrity
is maintained.
  <p>
- Constraints are designed to be configurable, so a constraints can be used across different
tables, but implement different behavior depending on the specific configuration given to
that constraint.
+ Constraints are designed to be configurable, so a constraint can be used across different
tables, but implement different 
+ behavior depending on the specific configuration given to that constraint.
  <p>
  By adding a constraint to a table (see <a href="#usage">Example Usage</a>),
constraints will automatically enabled. 
- You also then have the option of disabling (just 'turn off') or remove (delete all associated
information) constraints on a table. 
- If you remove all constraints (see {@link org.apache.hadoop.hbase.constraint.Constraints#remove(org.apache.hadoop.hbase.HTableDescriptor)},
you must re-add any {@link org.apache.hadoop.hbase.constraint.Constraint} you want on that
table. 
- However, if they are just disabled (see {@link org.apache.hadoop.hbase.constraint.Constraints#disable(org.apache.hadoop.hbase.HTableDescriptor)},
all you need to do is enable constraints again, and everything will be turned back on. 
- Individual constraints can also be individually enabled, disabled or removed without affecting
others.
+ You also then have the option of to disable (just 'turn off') or remove (delete all associated
information) all constraints on a table. 
+ If you remove all constraints 
+ (see {@link org.apache.hadoop.hbase.constraint.Constraints#remove(org.apache.hadoop.hbase.HTableDescriptor)},

+ you must re-add any {@link org.apache.hadoop.hbase.constraint.Constraint} you want on that
table. 
+ However, if they are just disabled (see {@link org.apache.hadoop.hbase.constraint.Constraints#disable(org.apache.hadoop.hbase.HTableDescriptor)},

+ all you need to do is enable constraints again, and everything will be turned back on as
it was configured.
+ Individual constraints can also be individually enabled, disabled or removed without affecting
other constraints.
  <p>
  By default, constraints are disabled on a table. 
  This means you will not see <i>any</i> slow down on a table if constraints are
not enabled.
  <p>
- <b>NOTES</b>
- <ol>
- <li>Constraints are run in the order that they are added to a table. This has implications
for what order constraints should be added to a table.</li>
- <li>There are certain keys that are reserved for the Configuration namespace:
- <ul>
- <li>_ENABLED - used server-side to determine if a constraint should be run</li>
- <li>_PRIORITY - used server-side to determine what order a constraint should be run</li>
- </ul>
- If these items are set, they will be respected in the constraint configuration, but they
are taken care of by default in when adding constraints to an {@link org.apache.hadoop.hbase.HTableDescriptor}
via the usual method.</li>
- </ol>
- <p> 
- Under the hood, constraints are implemented as a Coprocessor (see {@link org.apache.hadoop.hbase.constraint.ConstraintProcessor}
if you are interested).
 
  <h2><a name="concurrency">Concurrency and Atomicity</a></h2>
- Currently, no attempts at enforcing correctness in a multi-threaded scenario when modifying
a constraint, via {@link org.apache.hadoop.hbase.constraint.Constraints}, to the the {@link
org.apache.hadoop.hbase.HTableDescriptor}. 
- This is particularly important when adding a constraint(s) to the descriptor as it first
retrieves the next priority from a custom value set in the descriptor,
- adds each constraint (with increasing priority) to the descriptor, and then the next available
priority is re-stored back in the {@link org.apache.hadoop.hbase.HTableDescriptor}. 
- Locking is recommended around each of Constraints add methods: {@link org.apache.hadoop.hbase.constraint.Constraints#add(org.apache.hadoop.hbase.HTableDescriptor,
Class...)}, 
- {@link org.apache.hadoop.hbase.constraint.Constraints#add(org.apache.hadoop.hbase.HTableDescriptor,
org.apache.hadoop.hbase.util.Pair...)}, and {@link org.apache.hadoop.hbase.constraint.Constraints#add(org.apache.hadoop.hbase.HTableDescriptor,
Class, org.apache.hadoop.conf.Configuration)}.
+ Currently, no attempts at enforcing correctness in a multi-threaded scenario when modifying
a constraint, via 
+ {@link org.apache.hadoop.hbase.constraint.Constraints}, to the the {@link org.apache.hadoop.hbase.HTableDescriptor}.

+ This is particularly important when adding a constraint(s) to the {@link org.apache.hadoop.hbase.HTableDescriptor}

+ as it first retrieves the next priority from a custom value set in the descriptor,
+ adds each constraint (with increasing priority) to the descriptor, and then the next available
priority is re-stored 
+ back in the {@link org.apache.hadoop.hbase.HTableDescriptor}. 
+ <p>
+ Locking is recommended around each of Constraints add methods: 
+ {@link org.apache.hadoop.hbase.constraint.Constraints#add(org.apache.hadoop.hbase.HTableDescriptor,
Class...)}, 
+ {@link org.apache.hadoop.hbase.constraint.Constraints#add(org.apache.hadoop.hbase.HTableDescriptor,
org.apache.hadoop.hbase.util.Pair...)}, 
+ and {@link org.apache.hadoop.hbase.constraint.Constraints#add(org.apache.hadoop.hbase.HTableDescriptor,
Class, org.apache.hadoop.conf.Configuration)}.
  Any changes on <i>a single HTableDescriptor</i> should be serialized, either
within a single thread or via external mechanisms.
  <p>
- Note that having a higher priority means that a constraint will run later; e.g. a constraint
with priority 1 will run before a constraint with priority 2. 
+ Note that having a higher priority means that a constraint will run later; e.g. a constraint
with priority 1 will run before a 
+ constraint with priority 2. 
  <p>
- Since Constraints currently are designed to just implement simple checks (e.g. is the value
in the right range), there will be no atomicity conflicts. 
- Even if one of the puts finishes the constraint first, the single row will not be corrupted
and the 'fastest' write will win; the underlying region takes care of breaking the tie and
ensuring that writes get serialized to the table.
+ Since Constraints currently are designed to just implement simple checks (e.g. is the value
in the right range), there will 
+ be no atomicity conflicts. 
+ Even if one of the puts finishes the constraint first, the single row will not be corrupted
and the 'fastest' write will win; 
+ the underlying region takes care of breaking the tie and ensuring that writes get serialized
to the table.
  So yes, this doesn't ensure that we are going to get specific ordering or even a fully consistent
view of the underlying data. 
  <p>
- Each constraint should only use local/instance variables, unless doing more advanced usage.
Static variables could cause difficulties when checking concurrent writes to the same region,
leading to either highly locked situations (decreasing throughtput) or higher probability
of errors.
- However, as long as each constraint just uses local variables, each thread interacting with
the constraint will be completely fine.
+ Each constraint should only use local/instance variables, unless doing more advanced usage.
Static variables could cause difficulties
+ when checking concurrent writes to the same region, leading to either highly locked situations
(decreasing through-put) or higher probability of errors.
+ However, as long as each constraint just uses local variables, each thread interacting with
the constraint will execute correctly and efficiently.
 
  <h2><a name="caveats">Caveats</a></h2>
  In traditional (SQL) databases, Constraints are often used to enforce <a href="http://en.wikipedia.org/wiki/Relational_database#Constraints">referential
integrity</a>. 
- However, in HBase, this will likely cause significant overhead and dramatically decrease
the number of {@link org.apache.hadoop.hbase.client.Put Puts}/second possible on a table.
- This is because to check the referential integrity when making a {@link org.apache.hadoop.hbase.client.Put},
one must block on a scan for the 'remote' table, checking for the valid reference.
+ However, in HBase, this will likely cause significant overhead and dramatically decrease
the number of 
+ {@link org.apache.hadoop.hbase.client.Put Puts}/second possible on a table. This is because
to check the referential integrity 
+ when making a {@link org.apache.hadoop.hbase.client.Put}, one must block on a scan for the
'remote' table, checking for the valid reference.
  For millions of {@link org.apache.hadoop.hbase.client.Put Puts} a second, this will breakdown
very quickly. 
  There are several options around the blocking behavior including, but not limited to:
  <ul>
@@ -87,44 +90,71 @@
  <li>Designing for 'incorrect' references</li>
  <li>Using an external enforcement mechanism</li>
  </ul>
- 
+ There are also several general considerations that must be taken into account, when using
Constraints:
+ <ol>
+ <li>All changes made via {@link org.apache.hadoop.hbase.constraint.Constraints} will
make modifications to the 
+ {@link org.apache.hadoop.hbase.HTableDescriptor} for a given table. As such, the usual renabling
of tables should be used for 
+ propagating changes to the table. When at all possible, Constraints should be added to the
table before the table is created.</li>
+ <li>Constraints are run in the order that they are added to a table. This has implications
for what order constraints should 
+ be added to a table.</li>
+ <li>Whenever new Constraint jars are added to a region server, those region servers
need to go through a rolling restart to 
+ make sure that they pick up the new jars and can enable the new constraints.</li>
+ <li>There are certain keys that are reserved for the Configuration namespace:
+ <ul>
+ <li>_ENABLED - used server-side to determine if a constraint should be run</li>
+ <li>_PRIORITY - used server-side to determine what order a constraint should be run</li>
+ </ul>
+ If these items are set, they will be respected in the constraint configuration, but they
are taken care of by default in when 
+ adding constraints to an {@link org.apache.hadoop.hbase.HTableDescriptor} via the usual
method.</li>
+ </ol>
+ <p> 
+ Under the hood, constraints are implemented as a Coprocessor (see {@link org.apache.hadoop.hbase.constraint.ConstraintProcessor}

+ if you are interested).
+
+
  <h2><a name="usage">Example usage</a></h2>
  First, you must define a {@link org.apache.hadoop.hbase.constraint.Constraint}. 
- The best way to do this is to extend {@link org.apache.hadoop.hbase.constraint.BaseConstraint},
which takes care of some of the more mundane details of using a {@link org.apache.hadoop.hbase.constraint.Constraint}.
+ The best way to do this is to extend {@link org.apache.hadoop.hbase.constraint.BaseConstraint},
which takes care of some of the more
+ mundane details of using a {@link org.apache.hadoop.hbase.constraint.Constraint}.
  <p>
  Let's look at one possible implementation of a constraint - an IntegerConstraint(there are
also several simple examples in the tests). 
  The IntegerConstraint checks to make sure that the value is a String-encoded <code>int</code>.
- It is really simple to implement this kind of constraint, the only method needs to be implemented
is {@link org.apache.hadoop.hbase.constraint.Constraint#check(org.apache.hadoop.hbase.client.Put)}:
+ It is really simple to implement this kind of constraint, the only method needs to be implemented
is
+ {@link org.apache.hadoop.hbase.constraint.Constraint#check(org.apache.hadoop.hbase.client.Put)}:
 
  <div style="background-color: #cccccc; padding: 2px">
  <blockquote><pre>
  public class IntegerConstraint extends BaseConstraint {
-   public void check(Put p) throws ConstraintException {
-  
-     Map&ltbyte[], List&ltKeyValue&gt&gt familyMap = p.getFamilyMap();
-    
-     for (List &ltKeyValue&gt kvs : familyMap.values()) {
-       for (KeyValue kv : kvs) {
-      
-       // just make sure that we can actually pull out an int
-       // this will automatically throw a NumberFormatException if we try to
-       // store something that isn't an Integer.
-      
-       try {
-       Integer.parseInt(new String(kv.getValue()));
-       } catch (NumberFormatException e) {
-       throw new ConstraintException("Value in Put (" + p
-       + ") was not a String-encoded integer", e);
-   } } } 
+ public void check(Put p) throws ConstraintException {
+
+ Map&ltbyte[], List&ltKeyValue&gt&gt familyMap = p.getFamilyMap();
+
+ for (List &ltKeyValue&gt kvs : familyMap.values()) {
+ for (KeyValue kv : kvs) {
+
+ // just make sure that we can actually pull out an int
+ // this will automatically throw a NumberFormatException if we try to
+ // store something that isn't an Integer.
+
+ try {
+ Integer.parseInt(new String(kv.getValue()));
+ } catch (NumberFormatException e) {
+ throw new ConstraintException("Value in Put (" + p
+ + ") was not a String-encoded integer", e);
+ } } } 
  </pre></blockquote>
  </div>
  <p>
- Note that all exceptions that you expect to be thrown must be caught and then rethrown as
a {@link org.apache.hadoop.hbase.constraint.ConstraintException}. 
- This way, you can be sue that a {@link org.apache.hadoop.hbase.client.Put} fails for an
expected reason, rather than for any reason. 
- For example, an {@link java.lang.OutOfMemoryError} is probably indicative of an inherent
problem in the {@link org.apache.hadoop.hbase.constraint.Constraint}, rather than a failed
{@link org.apache.hadoop.hbase.client.Put}.
- <p>
- If an unexpected exception is thrown (for example, any kind of uncaught {@link java.lang.RuntimeException}),
constraint-checking will be 'unloaded' from the regionserver where that error occurred. 
- This means no further {@link org.apache.hadoop.hbase.constraint.Constraint Constraints}
will be checked on that server until it is reloaded. This is done to ensure the system remains
as available as possible.
+ Note that all exceptions that you expect to be thrown must be caught and then rethrown as
a 
+ {@link org.apache.hadoop.hbase.constraint.ConstraintException}. This way, you can be sure
that a 
+ {@link org.apache.hadoop.hbase.client.Put} fails for an expected reason, rather than for
any reason. 
+ For example, an {@link java.lang.OutOfMemoryError} is probably indicative of an inherent
problem in 
+ the {@link org.apache.hadoop.hbase.constraint.Constraint}, rather than a failed {@link org.apache.hadoop.hbase.client.Put}.
+ <p>
+ If an unexpected exception is thrown (for example, any kind of uncaught {@link java.lang.RuntimeException}),
+ constraint-checking will be 'unloaded' from the regionserver where that error occurred.

+ This means no further {@link org.apache.hadoop.hbase.constraint.Constraint Constraints}
will be checked on that server
+ until it is reloaded. This is done to ensure the system remains as available as possible.
  Therefore, be careful when writing your own Constraint.
  <p>
  So now that we have a Constraint, we want to add it to a table. It's as easy as:
@@ -136,10 +166,12 @@
  Constraints.add(desc, IntegerConstraint.class);
  </pre></blockquote></div>
  <p>
- Once we added the IntegerConstraint, constraints will be enabled on the table (once it is
created) and we will always check to make sure that the value is an String-encoded integer.
+ Once we added the IntegerConstraint, constraints will be enabled on the table (once it is
created) and 
+ we will always check to make sure that the value is an String-encoded integer.
  <p> 
  However, suppose we also write our own constraint, <code>MyConstraint.java</code>.
- First, you need to make sure this class-files are in the classpath (in a jar) on the regionserver
where that constraint will be run.
+ First, you need to make sure this class-files are in the classpath (in a jar) on the regionserver
where 
+ that constraint will be run (this could require a rolling restart on the region server -
see <a href="#caveats">Caveats</a> above)
  <p>
  Suppose that MyConstraint also uses a Configuration (see {@link org.apache.hadoop.hbase.constraint.Constraint#getConf()}).

  Then adding MyConstraint looks like this:
@@ -147,7 +179,7 @@
  <div style="background-color: #cccccc; padding: 2px">
  <blockquote><pre>
  HTableDescriptor desc = new HTableDescriptor(TABLE_NAME);
- Configuration conf = new Configuration();
+ Configuration conf = new Configuration(false);
  ...
  (add values to the conf)
  (modify the table descriptor)
@@ -155,9 +187,12 @@
  Constraints.add(desc, new Pair(MyConstraint.class, conf));
  </pre></blockquote></div>
  <p>
- At this point we added both the IntegerConstraint and MyConstraint to the table, the IntegerConstraint
<i>will be run first</i>, followed by MyConstraint.
+ At this point we added both the IntegerConstraint and MyConstraint to the table, the IntegerConstraint
+ <i>will be run first</i>, followed by MyConstraint.
  <p>
- Suppose we realize that the {@link org.apache.hadoop.conf.Configuration} for MyConstraint
is actually wrong when it was added to the table. Note, when it is added to the table, it
is <i>not</i> added by reference, but is instead copied into the {@link org.apache.hadoop.hbase.HTableDescriptor}.
+ Suppose we realize that the {@link org.apache.hadoop.conf.Configuration} for MyConstraint
is actually wrong
+ when it was added to the table. Note, when it is added to the table, it is <i>not</i>
added by reference, 
+ but is instead copied into the {@link org.apache.hadoop.hbase.HTableDescriptor}.
  Thus, to change the {@link org.apache.hadoop.conf.Configuration} we are using for MyConstraint,
we need to do this:
 
  <div style="background-color: #cccccc; padding: 2px">
@@ -167,7 +202,8 @@
  Constraints.setConfiguration(desc, MyConstraint.class, conf);
  </pre></blockquote></div>
  <p>
- This will overwrite the previous configuration for MyConstraint, but <i>not</i>
change the order of the constraint nor if it is enabled/disabled.
+ This will overwrite the previous configuration for MyConstraint, but <i>not</i>
change the order of the 
+ constraint nor if it is enabled/disabled.
  <p>
  Note that the same constraint class can be added multiple times to a table without repercussion.
  A use case for this is the same constraint working differently based on its configuration.
@@ -212,7 +248,17 @@
  Constraints.remove(desc);
  </pre></blockquote></div>
  This will remove all constraints (and associated information) from the table and turn off
the constraint processing.
-
- 
+ <p><b>NOTE</b><p>
+ It is important to note the use above of
+ <div style="background-color: #cccccc">
+ <blockquote><pre>
+ Configuration conf = new Configuration(false);
+ </pre></blockquote></div>
+ If you just use <code> new Configuration()</code>, then the Configuration will
be loaded with the default
+ properties. While in the simple case, this is not going to be an issue, it will cause pain
down the road.
+ First, these extra properties are going to cause serious bloat in your {@link org.apache.hadoop.hbase.HTableDescriptor},
+ meaning you are keeping around a ton of redundant information. Second, it is going to make
examining
+ your table in the shell, via <code>describe 'table'</code>, a huge pain as you
will have to dig through
+ a ton of irrelevant config values to find the ones you set. In short, just do it the right
way.
  */
-package org.apache.hadoop.hbase.constraint;
\ No newline at end of file
+package org.apache.hadoop.hbase.constraint;

Modified: hbase/trunk/src/test/java/org/apache/hadoop/hbase/constraint/CheckConfigurationConstraint.java
URL: http://svn.apache.org/viewvc/hbase/trunk/src/test/java/org/apache/hadoop/hbase/constraint/CheckConfigurationConstraint.java?rev=1223024&r1=1223023&r2=1223024&view=diff
==============================================================================
--- hbase/trunk/src/test/java/org/apache/hadoop/hbase/constraint/CheckConfigurationConstraint.java
(original)
+++ hbase/trunk/src/test/java/org/apache/hadoop/hbase/constraint/CheckConfigurationConstraint.java
Sat Dec 24 21:42:31 2011
@@ -25,7 +25,6 @@ import org.apache.hadoop.hbase.client.Pu
  */
 public class CheckConfigurationConstraint extends BaseConstraint {
 
-
   private static String key = "testKey";
   private static String value = "testValue";
 
@@ -42,11 +41,13 @@ public class CheckConfigurationConstrain
 
   @Override
   public void setConf(Configuration conf) {
-    String val = conf.get(key);
-    if (val == null || !val.equals(value))
-      throw new IllegalArgumentException(
-          "Configuration was not passed correctly");
     super.setConf(conf);
+    if (conf != null) {
+      String val = conf.get(key);
+      if (val == null || !val.equals(value))
+        throw new IllegalArgumentException(
+            "Configuration was not passed correctly");
+    }
   }
 
 }



Mime
View raw message