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 org.apache.hadoop.conf.Configuration; 022import org.apache.hadoop.hbase.CoprocessorEnvironment; 023import org.apache.hadoop.hbase.HBaseInterfaceAudience; 024import org.apache.hadoop.hbase.ServerName; 025import org.apache.hadoop.hbase.client.Connection; 026import org.apache.hadoop.hbase.metrics.MetricRegistry; 027import org.apache.hadoop.hbase.regionserver.OnlineRegions; 028import org.apache.yetus.audience.InterfaceAudience; 029import org.apache.yetus.audience.InterfaceStability; 030 031@InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC) 032@InterfaceStability.Evolving 033public interface RegionServerCoprocessorEnvironment 034 extends CoprocessorEnvironment<RegionServerCoprocessor> { 035 /** Returns Hosting Server's ServerName */ 036 ServerName getServerName(); 037 038 /** Returns Interface to Map of regions online on this RegionServer {@link #getServerName()}}. */ 039 OnlineRegions getOnlineRegions(); 040 041 /** 042 * Returns the hosts' Connection to the Cluster. <b>Do not close! This is a shared connection with 043 * the hosting server. Throws {@link UnsupportedOperationException} if you try to close or abort 044 * it</b>. For light-weight usage only. Heavy-duty usage will pull down the hosting RegionServer 045 * responsiveness as well as that of other Coprocessors making use of this Connection. Use to 046 * create table on start or to do administrative operations. Coprocessors should create their own 047 * Connections if heavy usage to avoid impinging on hosting Server operation. To create a 048 * Connection or if a Coprocessor requires a region with a particular Configuration, use 049 * {@link org.apache.hadoop.hbase.client.ConnectionFactory} or 050 * {@link #createConnection(Configuration)}}. 051 * <p> 052 * Be aware that operations that make use of this Connection are executed as the RegionServer 053 * User, the hbase super user that started this server process. Exercise caution running 054 * operations as this User (See {@link #createConnection(Configuration)}} to run as other than the 055 * RegionServer User). 056 * <p> 057 * Be careful RPC'ing from a Coprocessor context. RPC's will fail, stall, retry, and/or crawl 058 * because the remote side is not online, is struggling or it is on the other side of a network 059 * partition. Any use of Connection from inside a Coprocessor must be able to handle all such 060 * hiccups. 061 * @see #createConnection(Configuration) 062 * @return The host's Connection to the Cluster. 063 */ 064 Connection getConnection(); 065 066 /** 067 * Creates a cluster connection using the passed Configuration. Creating a Connection is a 068 * heavy-weight operation. The resultant Connection's cache of region locations will be empty. 069 * Therefore you should cache and reuse Connections rather than create a Connection on demand. 070 * Create on start of your Coprocessor. You will have to cast the CoprocessorEnvironment 071 * appropriately to get at this API at start time because Coprocessor start method is passed a 072 * subclass of this CoprocessorEnvironment or fetch Connection using a synchronized accessor 073 * initializing the Connection on first access. Close the returned Connection when done to free 074 * resources. Using this API rather than 075 * {@link org.apache.hadoop.hbase.client.ConnectionFactory#createConnection(Configuration)} 076 * returns a Connection that will short-circuit RPC if the target is a local resource. Use 077 * ConnectionFactory if you don't need this ability. 078 * <p> 079 * Be careful RPC'ing from a Coprocessor context. RPC's will fail, stall, retry, and/or crawl 080 * because the remote side is not online, is struggling or it is on the other side of a network 081 * partition. Any use of Connection from inside a Coprocessor must be able to handle all such 082 * hiccups. 083 * @return Connection created using the passed conf. 084 */ 085 Connection createConnection(Configuration conf) throws IOException; 086 087 /** 088 * Returns a MetricRegistry that can be used to track metrics at the region server level. 089 * <p> 090 * See ExampleMasterObserverWithMetrics class in the hbase-examples modules for examples of how 091 * metrics can be instantiated and used. 092 * </p> 093 * @return A MetricRegistry for the coprocessor class to track and export metrics. 094 */ 095 MetricRegistry getMetricRegistryForRegionServer(); 096}