View Javadoc

1   /*
2    *
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *     http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License.
18   */
19  
20  package org.apache.hadoop.hbase.coprocessor;
21  
22  import org.apache.hadoop.classification.InterfaceAudience;
23  import org.apache.hadoop.classification.InterfaceStability;
24  import org.apache.hadoop.hbase.CoprocessorEnvironment;
25  
26  /**
27   * Carries the execution state for a given invocation of an Observer coprocessor
28   * ({@link RegionObserver}, {@link MasterObserver}, or {@link WALObserver})
29   * method.  The same ObserverContext instance is passed sequentially to all loaded
30   * coprocessors for a given Observer method trigger, with the
31   * <code>CoprocessorEnvironment</code> reference swapped out for each
32   * coprocessor.
33   * @param <E> The {@link CoprocessorEnvironment} subclass applicable to the
34   *     revelant Observer interface.
35   */
36  @InterfaceAudience.Public
37  @InterfaceStability.Evolving
38  public class ObserverContext<E extends CoprocessorEnvironment> {
39    private E env;
40    private boolean bypass;
41    private boolean complete;
42  
43    public ObserverContext() {
44    }
45  
46    public E getEnvironment() {
47      return env;
48    }
49  
50    public void prepare(E env) {
51      this.env = env;
52    }
53  
54    /**
55     * Call to indicate that the current coprocessor's return value should be
56     * used in place of the normal HBase obtained value.
57     */
58    public void bypass() {
59      bypass = true;
60    }
61  
62    /**
63     * Call to indicate that additional coprocessors further down the execution
64     * chain do not need to be invoked.  Implies that this coprocessor's response
65     * is definitive.
66     */
67    public void complete() {
68      complete = true;
69    }
70  
71    /**
72     * For use by the coprocessor framework.
73     * @return <code>true</code> if {@link ObserverContext#bypass()}
74     *     was called by one of the loaded coprocessors, <code>false</code> otherwise.
75     */
76    public boolean shouldBypass() {
77      boolean current = bypass;
78      bypass = false;
79      return current;
80    }
81  
82    /**
83     * For use by the coprocessor framework.
84     * @return <code>true</code> if {@link ObserverContext#complete()}
85     *     was called by one of the loaded coprocessors, <code>false</code> otherwise.
86     */
87    public boolean shouldComplete() {
88      boolean current = complete;
89      complete = false;
90      return current;
91    }
92  
93    /**
94     * Instantiates a new ObserverContext instance if the passed reference is
95     * <code>null</code> and sets the environment in the new or existing instance.
96     * This allows deferring the instantiation of a ObserverContext until it is
97     * actually needed.
98     *
99     * @param env The coprocessor environment to set
100    * @param context An existing ObserverContext instance to use, or <code>null</code>
101    *     to create a new instance
102    * @param <T> The environment type for the context
103    * @return An instance of <code>ObserverContext</code> with the environment set
104    */
105   public static <T extends CoprocessorEnvironment> ObserverContext<T> createAndPrepare(
106       T env, ObserverContext<T> context) {
107     if (context == null) {
108       context = new ObserverContext<T>();
109     }
110     context.prepare(env);
111     return context;
112   }
113 }