001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, software 013 * distributed under the License is distributed on an "AS IS" BASIS, 014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 015 * See the License for the specific language governing permissions and 016 * limitations under the License. 017 */ 018package org.apache.hadoop.hbase.coprocessor; 019 020import java.io.IOException; 021import java.util.concurrent.ConcurrentMap; 022import org.apache.hadoop.conf.Configuration; 023import org.apache.hadoop.hbase.CoprocessorEnvironment; 024import org.apache.hadoop.hbase.HBaseInterfaceAudience; 025import org.apache.hadoop.hbase.RawCellBuilder; 026import org.apache.hadoop.hbase.ServerName; 027import org.apache.hadoop.hbase.client.Connection; 028import org.apache.hadoop.hbase.client.RegionInfo; 029import org.apache.hadoop.hbase.metrics.MetricRegistry; 030import org.apache.hadoop.hbase.regionserver.OnlineRegions; 031import org.apache.hadoop.hbase.regionserver.Region; 032import org.apache.yetus.audience.InterfaceAudience; 033import org.apache.yetus.audience.InterfaceStability; 034 035@InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC) 036@InterfaceStability.Evolving 037public interface RegionCoprocessorEnvironment extends CoprocessorEnvironment<RegionCoprocessor> { 038 /** Returns the region associated with this coprocessor */ 039 Region getRegion(); 040 041 /** Returns region information for the region this coprocessor is running on */ 042 RegionInfo getRegionInfo(); 043 044 /** Returns Interface to Map of regions online on this RegionServer {@link #getServerName()}}. */ 045 OnlineRegions getOnlineRegions(); 046 047 /** Returns shared data between all instances of this coprocessor */ 048 ConcurrentMap<String, Object> getSharedData(); 049 050 /** Returns Hosting Server's ServerName */ 051 ServerName getServerName(); 052 053 /** 054 * Returns the hosts' Connection to the Cluster. <b>Do not close! This is a shared connection with 055 * the hosting server. Throws {@link UnsupportedOperationException} if you try to close or abort 056 * it</b>. For light-weight usage only. Heavy-duty usage will pull down the hosting RegionServer 057 * responsiveness as well as that of other Coprocessors making use of this Connection. Use to 058 * create table on start or to do administrative operations. Coprocessors should create their own 059 * Connections if heavy usage to avoid impinging on hosting Server operation. To create a 060 * Connection or if a Coprocessor requires a region with a particular Configuration, use 061 * {@link org.apache.hadoop.hbase.client.ConnectionFactory} or 062 * {@link #createConnection(Configuration)}}. 063 * <p> 064 * Be aware that operations that make use of this Connection are executed as the RegionServer 065 * User, the hbase super user that started this server process. Exercise caution running 066 * operations as this User (See {@link #createConnection(Configuration)}} to run as other than the 067 * RegionServer User). 068 * <p> 069 * Be careful RPC'ing from a Coprocessor context. RPC's will fail, stall, retry, and/or crawl 070 * because the remote side is not online, is struggling or it is on the other side of a network 071 * partition. Any use of Connection from inside a Coprocessor must be able to handle all such 072 * hiccups. 073 * @see #createConnection(Configuration) 074 * @return The host's Connection to the Cluster. 075 */ 076 Connection getConnection(); 077 078 /** 079 * Creates a cluster connection using the passed Configuration. Creating a Connection is a 080 * heavy-weight operation. The resultant Connection's cache of region locations will be empty. 081 * Therefore you should cache and reuse Connections rather than create a Connection on demand. 082 * Create on start of your Coprocessor. You will have to cast the CoprocessorEnvironment 083 * appropriately to get at this API at start time because Coprocessor start method is passed a 084 * subclass of this CoprocessorEnvironment or fetch Connection using a synchronized accessor 085 * initializing the Connection on first access. Close the returned Connection when done to free 086 * resources. Using this API rather than 087 * {@link org.apache.hadoop.hbase.client.ConnectionFactory#createConnection(Configuration)} 088 * returns a Connection that will short-circuit RPC if the target is a local resource. Use 089 * ConnectionFactory if you don't need this ability. 090 * <p> 091 * Be careful RPC'ing from a Coprocessor context. RPC's will fail, stall, retry, and/or crawl 092 * because the remote side is not online, is struggling or it is on the other side of a network 093 * partition. Any use of Connection from inside a Coprocessor must be able to handle all such 094 * hiccups. 095 * @return Connection created using the passed conf. 096 */ 097 Connection createConnection(Configuration conf) throws IOException; 098 099 /** 100 * Returns a MetricRegistry that can be used to track metrics at the region server level. All 101 * metrics tracked at this level will be shared by all the coprocessor instances of the same class 102 * in the same region server process. Note that there will be one region coprocessor environment 103 * per region in the server, but all of these instances will share the same MetricRegistry. The 104 * metric instances (like Counter, Timer, etc) will also be shared among all of the region 105 * coprocessor instances. 106 * <p> 107 * See ExampleRegionObserverWithMetrics class in the hbase-examples modules to see examples of how 108 * metrics can be instantiated and used. 109 * </p> 110 * @return A MetricRegistry for the coprocessor class to track and export metrics. 111 */ 112 // Note: we are not exposing getMetricRegistryForRegion(). per-region metrics are already costly 113 // so we do not want to allow coprocessors to export metrics at the region level. We can allow 114 // getMetricRegistryForTable() to allow coprocessors to track metrics per-table, per-regionserver. 115 MetricRegistry getMetricRegistryForRegionServer(); 116 117 /** 118 * Returns a CellBuilder so that coprocessors can build cells. These cells can also include tags. 119 * Note that this builder does not support updating seqId of the cells 120 * @return the RawCellBuilder 121 */ 122 RawCellBuilder getCellBuilder(); 123}