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 }