View Javadoc

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