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