View Javadoc

1   /**
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.apache.hadoop.hbase.constraint;
19  
20  import org.apache.hadoop.conf.Configurable;
21  import org.apache.hadoop.hbase.HTableDescriptor;
22  import org.apache.hadoop.hbase.client.Put;
23  
24  /**
25   * Apply a {@link Constraint} (in traditional database terminology) to a HTable.
26   * Any number of {@link Constraint Constraints} can be added to the table, in
27   * any order.
28   * <p>
29   * A {@link Constraint} must be added to a table before the table is loaded via
30   * {@link Constraints#add(HTableDescriptor, Class...)} or
31   * {@link Constraints#add(HTableDescriptor, org.apache.hadoop.hbase.util.Pair...)}
32   * (if you want to add a configuration with the {@link Constraint}). Constraints
33   * will be run in the order that they are added. Further, a Constraint will be
34   * configured before it is run (on load).
35   * <p>
36   * See {@link Constraints#enableConstraint(HTableDescriptor, Class)} and
37   * {@link Constraints#disableConstraint(HTableDescriptor, Class)} for
38   * enabling/disabling of a given {@link Constraint} after it has been added.
39   * <p>
40   * If a {@link Put} is invalid, the Constraint should throw some sort of
41   * {@link ConstraintException}, indicating that the {@link Put} has failed. When
42   * this exception is thrown, not further retries of the {@link Put} are
43   * attempted nor are any other {@link Constraint Constraints} attempted (the
44   * {@link Put} is clearly not valid). Therefore, there are performance
45   * implications in the order in which {@link BaseConstraint Constraints} are
46   * specified.
47   * <p>
48   * If a {@link Constraint} fails to fail the {@link Put} via a
49   * {@link ConstraintException}, but instead throws a {@link RuntimeException},
50   * the entire constraint processing mechanism ({@link ConstraintProcessor}) will
51   * be unloaded from the table. This ensures that the region server is still
52   * functional, but no more {@link Put Puts} will be checked via
53   * {@link Constraint Constraints}.
54   * <p>
55   * Further, {@link Constraint Constraints} should probably not be used to
56   * enforce cross-table references as it will cause tremendous write slowdowns,
57   * but it is possible.
58   * <p>
59   * NOTE: Implementing classes must have a nullary (no-args) constructor
60   *
61   * @see BaseConstraint
62   * @see Constraints
63   */
64  public interface Constraint extends Configurable {
65  
66    /**
67     * Check a {@link Put} to ensure it is valid for the table. If the {@link Put}
68     * is valid, then just return from the method. Otherwise, throw an
69     * {@link Exception} specifying what happened. This {@link Exception} is
70     * propagated back to the client so you can see what caused the {@link Put} to
71     * fail.
72     * @param p {@link Put} to check
73     * @throws ConstraintException when the {@link Put} does not match the
74     *         constraint.
75     */
76    public void check(Put p) throws ConstraintException;
77  
78  }