org.apache.hadoop.hbase.coprocessor

Class CoprocessorHost<E extends CoprocessorEnvironment>

java.lang.Object

org.apache.hadoop.hbase.coprocessor.CoprocessorHost<E>

Type Parameters:

E - the specific environment extension that a concrete implementation provides

Direct Known Subclasses:

MasterCoprocessorHost, RegionCoprocessorHost, RegionServerCoprocessorHost, WALCoprocessorHost

@InterfaceAudience.LimitedPrivate(value="Coprocesssor")
 @InterfaceStability.Evolving
public abstract class CoprocessorHost<E extends CoprocessorEnvironment>
extends Object

Provides the common setup framework and runtime services for coprocessor invocation from HBase services.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CoprocessorHost.Environment Encapsulation of the environment of each coprocessor

Field Summary

Fields

Modifier and Type	Field and Description
static String	ABORT_ON_ERROR_KEY
protected Abortable	abortable
protected Configuration	conf
protected SortedSet<E>	coprocessors Ordered set of loaded coprocessors with lock
static String	COPROCESSORS_ENABLED_CONF_KEY
static boolean	DEFAULT_ABORT_ON_ERROR
static boolean	DEFAULT_COPROCESSORS_ENABLED
static boolean	DEFAULT_USER_COPROCESSORS_ENABLED
protected AtomicInteger	loadSequence
static String	MASTER_COPROCESSOR_CONF_KEY
protected String	pathPrefix
static String	REGION_COPROCESSOR_CONF_KEY
static String	REGIONSERVER_COPROCESSOR_CONF_KEY
static String	USER_COPROCESSORS_ENABLED_CONF_KEY
static String	USER_REGION_COPROCESSOR_CONF_KEY
static String	WAL_COPROCESSOR_CONF_KEY

Constructor Summary

Constructors

Constructor and Description
CoprocessorHost(Abortable abortable)

Method Summary

Modifier and Type	Method and Description
protected void	abortServer(CoprocessorEnvironment environment, Throwable e)
protected void	abortServer(String coprocessorName, Throwable e)
abstract E	createEnvironment(Class<?> implClass, Coprocessor instance, int priority, int sequence, Configuration conf) Called when a new Coprocessor class is loaded
Coprocessor	findCoprocessor(String className) Find a coprocessor implementation by class name
CoprocessorEnvironment	findCoprocessorEnvironment(String className) Find a coprocessor environment by class name
<T extends Coprocessor> List<T>	findCoprocessors(Class<T> cls) Find list of coprocessors that extend/implement the given class/interface
Set<String>	getCoprocessors() Used to create a parameter to the HServerLoad constructor so that HServerLoad can provide information about the coprocessors loaded by this regionserver.
static Set<String>	getLoadedCoprocessors()
protected void	handleCoprocessorThrowable(CoprocessorEnvironment env, Throwable e) This is used by coprocessor hooks which are declared to throw IOException (or its subtypes).
protected void	legacyWarning(Class<? extends Coprocessor> clazz, String message) limits the amount of logging to once per coprocessor class.
void	load(Class<?> implClass, int priority, Configuration conf)
E	load(Path path, String className, int priority, Configuration conf) Load a coprocessor implementation into the host
E	loadInstance(Class<?> implClass, int priority, Configuration conf)
protected void	loadSystemCoprocessors(Configuration conf, String confKey) Load system coprocessors.
void	shutdown(CoprocessorEnvironment e)
protected static boolean	useLegacyMethod(Class<? extends Coprocessor> clazz, String methodName, Class<?>... parameterTypes) Used to gracefully handle fallback to deprecated methods when we evolve coprocessor APIs.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

REGION_COPROCESSOR_CONF_KEY

public static final String REGION_COPROCESSOR_CONF_KEY

See Also:

Constant Field Values

REGIONSERVER_COPROCESSOR_CONF_KEY

public static final String REGIONSERVER_COPROCESSOR_CONF_KEY

See Also:

Constant Field Values

USER_REGION_COPROCESSOR_CONF_KEY

public static final String USER_REGION_COPROCESSOR_CONF_KEY

See Also:

Constant Field Values

MASTER_COPROCESSOR_CONF_KEY

public static final String MASTER_COPROCESSOR_CONF_KEY

See Also:

Constant Field Values

WAL_COPROCESSOR_CONF_KEY

public static final String WAL_COPROCESSOR_CONF_KEY

See Also:

Constant Field Values

ABORT_ON_ERROR_KEY

public static final String ABORT_ON_ERROR_KEY

See Also:

Constant Field Values

DEFAULT_ABORT_ON_ERROR

public static final boolean DEFAULT_ABORT_ON_ERROR

See Also:

Constant Field Values

COPROCESSORS_ENABLED_CONF_KEY

public static final String COPROCESSORS_ENABLED_CONF_KEY

See Also:

Constant Field Values

DEFAULT_COPROCESSORS_ENABLED

public static final boolean DEFAULT_COPROCESSORS_ENABLED

See Also:

Constant Field Values

USER_COPROCESSORS_ENABLED_CONF_KEY

public static final String USER_COPROCESSORS_ENABLED_CONF_KEY

See Also:

Constant Field Values

DEFAULT_USER_COPROCESSORS_ENABLED

public static final boolean DEFAULT_USER_COPROCESSORS_ENABLED

See Also:

Constant Field Values

abortable

protected Abortable abortable

coprocessors

protected SortedSet<E extends CoprocessorEnvironment> coprocessors

Ordered set of loaded coprocessors with lock

conf

protected Configuration conf

pathPrefix

protected String pathPrefix

loadSequence

protected AtomicInteger loadSequence

Constructor Detail

CoprocessorHost

public CoprocessorHost(Abortable abortable)

Method Detail

getLoadedCoprocessors

public static Set<String> getLoadedCoprocessors()

getCoprocessors

public Set<String> getCoprocessors()

Used to create a parameter to the HServerLoad constructor so that HServerLoad can provide information about the coprocessors loaded by this regionserver. (HBASE-4070: Improve region server metrics to report loaded coprocessors to master).

loadSystemCoprocessors

protected void loadSystemCoprocessors(Configuration conf,
                                      String confKey)

Load system coprocessors. Read the class names from configuration. Called by constructor.

load

public E load(Path path,
              String className,
              int priority,
              Configuration conf)
       throws IOException

Load a coprocessor implementation into the host

Parameters:

path - path to implementation jar

className - the main class name

priority - chaining priority

conf - configuration for coprocessor

Throws:

IOException - Exception

load

public void load(Class<?> implClass,
                 int priority,
                 Configuration conf)
          throws IOException

Parameters:

implClass - Implementation class

priority - priority

conf - configuration

Throws:

IOException - Exception

loadInstance

public E loadInstance(Class<?> implClass,
                      int priority,
                      Configuration conf)
               throws IOException

Parameters:

implClass - Implementation class

priority - priority

conf - configuration

Throws:

IOException - Exception

createEnvironment

public abstract E createEnvironment(Class<?> implClass,
                                    Coprocessor instance,
                                    int priority,
                                    int sequence,
                                    Configuration conf)

Called when a new Coprocessor class is loaded

shutdown

public void shutdown(CoprocessorEnvironment e)

findCoprocessor

public Coprocessor findCoprocessor(String className)

Find a coprocessor implementation by class name

Parameters:

className - the class name

Returns:

the coprocessor, or null if not found

findCoprocessors

public <T extends Coprocessor> List<T> findCoprocessors(Class<T> cls)

Find list of coprocessors that extend/implement the given class/interface

Parameters:

cls - the class/interface to look for

Returns:

the list of coprocessors, or null if not found

findCoprocessorEnvironment

public CoprocessorEnvironment findCoprocessorEnvironment(String className)

Find a coprocessor environment by class name

Parameters:

className - the class name

Returns:

the coprocessor, or null if not found

abortServer

protected void abortServer(CoprocessorEnvironment environment,
                           Throwable e)

abortServer

protected void abortServer(String coprocessorName,
                           Throwable e)

handleCoprocessorThrowable

protected void handleCoprocessorThrowable(CoprocessorEnvironment env,
                                          Throwable e)
                                   throws IOException

This is used by coprocessor hooks which are declared to throw IOException (or its subtypes). For such hooks, we should handle throwable objects depending on the Throwable's type. Those which are instances of IOException should be passed on to the client. This is in conformance with the HBase idiom regarding IOException: that it represents a circumstance that should be passed along to the client for its own handling. For example, a coprocessor that implements access controls would throw a subclass of IOException, such as AccessDeniedException, in its preGet() method to prevent an unauthorized client's performing a Get on a particular table.

Parameters:

env - Coprocessor Environment

e - Throwable object thrown by coprocessor.

Throws:

IOException - Exception

useLegacyMethod

@InterfaceAudience.Private
protected static boolean useLegacyMethod(Class<? extends Coprocessor> clazz,
                                                                    String methodName,
                                                                    Class<?>... parameterTypes)

Used to gracefully handle fallback to deprecated methods when we evolve coprocessor APIs. When a particular Coprocessor API is updated to change methods, hosts can support fallback to the deprecated API by using this method to determine if an instance implements the new API. In the event that said support is partial, then in the face of a runtime issue that prevents proper operation legacyWarning(Class, String) should be used to let operators know. For examples of this in action, see the implementation of

• RegionCoprocessorHost
• WALCoprocessorHost

Parameters:

clazz - Coprocessor you wish to evaluate

methodName - the name of the non-deprecated method version

parameterTypes - the Class of the non-deprecated method's arguments in the order they are declared.

legacyWarning

@InterfaceAudience.Private
protected void legacyWarning(Class<? extends Coprocessor> clazz,
                                                        String message)

limits the amount of logging to once per coprocessor class. Used in concert with useLegacyMethod(Class, String, Class[]) when a runtime issue prevents properly supporting the legacy version of a coprocessor API. Since coprocessors can be in tight loops this serves to limit the amount of log spam we create.