CoprocessorHost (Apache HBase 1.2.12 API)

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
`(package private) static class`	`CoprocessorHost.EnvironmentPriorityComparator` Environment priority comparator.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ABORT_ON_ERROR_KEY`
`protected Abortable`	`abortable`
`protected org.apache.hadoop.conf.Configuration`	`conf`
`private static Set<String>`	`coprocessorNames` Not to be confused with the per-object _coprocessors_ (above), coprocessorNames is static and stores the set of all coprocessors ever loaded by any thread in this JVM.
`protected SortedList<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`
`private static Set<Class<? extends Coprocessor>>`	`legacyWarning` Used to limit legacy handling to once per Coprocessor class per classloader.
`protected AtomicInteger`	`loadSequence`
`private static org.apache.commons.logging.Log`	`LOG`
`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)

Constructors
Constructor and Description
`CoprocessorHost(Abortable abortable)`

Method Summary

Methods
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, org.apache.hadoop.conf.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.
`(package private) Set<ClassLoader>`	`getExternalClassLoaders()` Retrieves the set of classloaders used to instantiate Coprocessor classes defined in external jar files.
`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, org.apache.hadoop.conf.Configuration conf)`
`E`	`load(org.apache.hadoop.fs.Path path, String className, int priority, org.apache.hadoop.conf.Configuration conf)` Load a coprocessor implementation into the host
`E`	`loadInstance(Class<?> implClass, int priority, org.apache.hadoop.conf.Configuration conf)`
`protected void`	`loadSystemCoprocessors(org.apache.hadoop.conf.Configuration conf, String confKey)` Load system coprocessors once only.
`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
  - LOG
```
private static final org.apache.commons.logging.Log LOG
```
  - abortable
```
protected Abortable abortable
```
  - coprocessors
```
protected SortedList<E extends CoprocessorEnvironment> coprocessors
```
    Ordered set of loaded coprocessors with lock
  - conf
```
protected org.apache.hadoop.conf.Configuration conf
```
  - pathPrefix
```
protected String pathPrefix
```
  - loadSequence
```
protected AtomicInteger loadSequence
```
  - coprocessorNames
```
private static Set<String> coprocessorNames
```
    Not to be confused with the per-object _coprocessors_ (above), coprocessorNames is static and stores the set of all coprocessors ever loaded by any thread in this JVM. It is strictly additive: coprocessors are added to coprocessorNames, by loadInstance() but are never removed, since the intention is to preserve a history of all loaded coprocessors for diagnosis in case of server crash (HBASE-4014).
  - legacyWarning
```
private static final Set<Class<? extends Coprocessor>> legacyWarning
```
    Used to limit legacy handling to once per Coprocessor class per classloader.
- 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(org.apache.hadoop.conf.Configuration conf,
                          String confKey)
```
    Load system coprocessors once only. Read the class names from configuration. Called by constructor.
  - load
```
public E load(org.apache.hadoop.fs.Path path,
     String className,
     int priority,
     org.apache.hadoop.conf.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,
        org.apache.hadoop.conf.Configuration conf)
          throws IOException
```
    Parameters:
    implClass - Implementation class
    priority - priority
    conf - configuration
    
    Throws:
    
    IOException - Exception
  - loadInstance
```
public E loadInstance(Class<?> implClass,
             int priority,
             org.apache.hadoop.conf.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,
                  org.apache.hadoop.conf.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
  - getExternalClassLoaders
```
Set<ClassLoader> getExternalClassLoaders()
```
    Retrieves the set of classloaders used to instantiate Coprocessor classes defined in external jar files.
    
    Returns:
    A set of ClassLoader instances
  - 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.

Class CoprocessorHost<E extends CoprocessorEnvironment>

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

REGION_COPROCESSOR_CONF_KEY

REGIONSERVER_COPROCESSOR_CONF_KEY

USER_REGION_COPROCESSOR_CONF_KEY

MASTER_COPROCESSOR_CONF_KEY

WAL_COPROCESSOR_CONF_KEY

ABORT_ON_ERROR_KEY

DEFAULT_ABORT_ON_ERROR

COPROCESSORS_ENABLED_CONF_KEY

DEFAULT_COPROCESSORS_ENABLED

USER_COPROCESSORS_ENABLED_CONF_KEY

DEFAULT_USER_COPROCESSORS_ENABLED

LOG

abortable

coprocessors

conf

pathPrefix

loadSequence

coprocessorNames

legacyWarning

Constructor Detail

CoprocessorHost

Method Detail

getLoadedCoprocessors

getCoprocessors

loadSystemCoprocessors

load

load

loadInstance

createEnvironment

shutdown

findCoprocessor

findCoprocessors

findCoprocessorEnvironment

getExternalClassLoaders

abortServer

abortServer

handleCoprocessorThrowable

useLegacyMethod

legacyWarning