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 edu.umd.cs.findbugs.annotations.Nullable;
23  import org.apache.hadoop.hbase.classification.InterfaceAudience;
24  import org.apache.hadoop.hbase.classification.InterfaceStability;
25  import org.apache.hadoop.hbase.CoprocessorEnvironment;
26  import org.apache.hadoop.hbase.HBaseInterfaceAudience;
27  import org.apache.hadoop.hbase.ipc.RpcServer;
28  import org.apache.hadoop.hbase.security.User;
29
30  /**
31   * Carries the execution state for a given invocation of an Observer coprocessor
32   * ({@link RegionObserver}, {@link MasterObserver}, or {@link WALObserver})
33   * method.  The same ObserverContext instance is passed sequentially to all loaded
34   * coprocessors for a given Observer method trigger, with the
35   * <code>CoprocessorEnvironment</code> reference swapped out for each
36   * coprocessor.
37   * @param <E> The {@link CoprocessorEnvironment} subclass applicable to the
38   *     revelant Observer interface.
39   */
40  @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC)
41  @InterfaceStability.Evolving
42  public class ObserverContext<E extends CoprocessorEnvironment> {
43    private E env;
44    private boolean bypass;
45    private boolean complete;
46    private User caller;
47
48    public ObserverContext(User caller) {
49      this.caller = caller;
50    }
51
52    public E getEnvironment() {
53      return env;
54    }
55
56    public void prepare(E env) {
57      this.env = env;
58    }
59
60    /**
61     * Call to indicate that the current coprocessor's return value should be
62     * used in place of the normal HBase obtained value.
63     */
64    public void bypass() {
65      bypass = true;
66    }
67
68    /**
69     * Call to indicate that additional coprocessors further down the execution
70     * chain do not need to be invoked.  Implies that this coprocessor's response
71     * is definitive.
72     */
73    public void complete() {
74      complete = true;
75    }
76
77    /**
78     * For use by the coprocessor framework.
79     * @return <code>true</code> if {@link ObserverContext#bypass()}
80     *     was called by one of the loaded coprocessors, <code>false</code> otherwise.
81     */
82    public boolean shouldBypass() {
83      boolean current = bypass;
84      bypass = false;
85      return current;
86    }
87
88    /**
89     * For use by the coprocessor framework.
90     * @return <code>true</code> if {@link ObserverContext#complete()}
91     *     was called by one of the loaded coprocessors, <code>false</code> otherwise.
92     */
93    public boolean shouldComplete() {
94      boolean current = complete;
95      complete = false;
96      return current;
97    }
98
99    /**
100    * Returns the active user for the coprocessor call.
101    * If an explicit {@code User} instance was provided to the constructor, that will be returned,
102    * otherwise if we are in the context of an RPC call, the remote user is used.  May return null
103    * if the execution is outside of an RPC context.
104    */
105   @Nullable
106   public User getCaller() {
107     return caller;
108   }
109
110   /**
111    * Instantiates a new ObserverContext instance if the passed reference is
112    * <code>null</code> and sets the environment in the new or existing instance.
113    * This allows deferring the instantiation of a ObserverContext until it is
114    * actually needed.
115    *
116    * @param env The coprocessor environment to set
117    * @param context An existing ObserverContext instance to use, or <code>null</code>
118    *     to create a new instance
119    * @param <T> The environment type for the context
120    * @return An instance of <code>ObserverContext</code> with the environment set
121    */
122   @Deprecated
123   // TODO: Remove this method, ObserverContext should not depend on RpcServer
124   public static <T extends CoprocessorEnvironment> ObserverContext<T> createAndPrepare(
125       T env, ObserverContext<T> context) {
126     if (context == null) {
127       context = new ObserverContext<T>(RpcServer.getRequestUser());
128     }
129     context.prepare(env);
130     return context;
131   }
132
133   /**
134    * Instantiates a new ObserverContext instance if the passed reference is
135    * <code>null</code> and sets the environment in the new or existing instance.
136    * This allows deferring the instantiation of a ObserverContext until it is
137    * actually needed.
138    *
139    * @param env The coprocessor environment to set
140    * @param context An existing ObserverContext instance to use, or <code>null</code>
141    *     to create a new instance
142    * @param user The requesting caller for the execution context
143    * @param <T> The environment type for the context
144    * @return An instance of <code>ObserverContext</code> with the environment set
145    */
146   public static <T extends CoprocessorEnvironment> ObserverContext<T> createAndPrepare(
147       T env, ObserverContext<T> context, User user) {
148     if (context == null) {
149       context = new ObserverContext<T>(user);
150     }
151     context.prepare(env);
152     return context;
153   }
154 }