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