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.client; 019 020import java.io.Closeable; 021import java.io.IOException; 022import java.util.List; 023import org.apache.hadoop.conf.Configuration; 024import org.apache.hadoop.hbase.TableName; 025import org.apache.yetus.audience.InterfaceAudience; 026 027/** 028 * <p> 029 * Used to communicate with a single HBase table similar to {@link Table} but meant for batched, 030 * asynchronous puts. Obtain an instance from a {@link Connection} and call {@link #close()} 031 * afterwards. Customizations can be applied to the {@code BufferedMutator} via the 032 * {@link BufferedMutatorParams}. 033 * </p> 034 * <p> 035 * Exception handling with asynchronously via the {@link BufferedMutator.ExceptionListener}. The 036 * default implementation is to throw the exception upon receipt. This behavior can be overridden 037 * with a custom implementation, provided as a parameter with 038 * {@link BufferedMutatorParams#listener(BufferedMutator.ExceptionListener)}. 039 * </p> 040 * <p> 041 * Map/Reduce jobs are good use cases for using {@code BufferedMutator}. Map/reduce jobs benefit 042 * from batching, but have no natural flush point. {@code BufferedMutator} receives the puts from 043 * the M/R job and will batch puts based on some heuristic, such as the accumulated size of the 044 * puts, and submit batches of puts asynchronously so that the M/R logic can continue without 045 * interruption. 046 * </p> 047 * <p> 048 * {@code BufferedMutator} can also be used on more exotic circumstances. Map/Reduce batch jobs will 049 * have a single {@code BufferedMutator} per thread. A single {@code BufferedMutator} can also be 050 * effectively used in high volume online systems to batch puts, with the caveat that extreme 051 * circumstances, such as JVM or machine failure, may cause some data loss. 052 * </p> 053 * <p> 054 * NOTE: This class replaces the functionality that used to be available via 055 * HTable#setAutoFlush(boolean) set to {@code false}. 056 * </p> 057 * <p> 058 * See also the {@code BufferedMutatorExample} in the hbase-examples module. 059 * </p> 060 * @see ConnectionFactory 061 * @see Connection 062 * @since 1.0.0 063 */ 064@InterfaceAudience.Public 065public interface BufferedMutator extends Closeable { 066 /** 067 * Key to use setting non-default BufferedMutator implementation in Configuration. 068 * <p/> 069 * @deprecated Since 3.0.0, will be removed in 4.0.0. For internal test use only, do not use it 070 * any more. 071 */ 072 @Deprecated 073 String CLASSNAME_KEY = "hbase.client.bufferedmutator.classname"; 074 075 /** 076 * Having the timer tick run more often that once every 100ms is needless and will probably cause 077 * too many timer events firing having a negative impact on performance. 078 */ 079 long MIN_WRITE_BUFFER_PERIODIC_FLUSH_TIMERTICK_MS = 100; 080 081 /** 082 * Gets the fully qualified table name instance of the table that this BufferedMutator writes to. 083 */ 084 TableName getName(); 085 086 /** 087 * Returns the {@link org.apache.hadoop.conf.Configuration} object used by this instance. 088 * <p> 089 * The reference returned is not a copy, so any change made to it will affect this instance. 090 */ 091 Configuration getConfiguration(); 092 093 /** 094 * Sends a {@link Mutation} to the table. The mutations will be buffered and sent over the wire as 095 * part of a batch. Currently only supports {@link Put} and {@link Delete} mutations. 096 * @param mutation The data to send. 097 * @throws IOException if a remote or network exception occurs. 098 */ 099 void mutate(Mutation mutation) throws IOException; 100 101 /** 102 * Send some {@link Mutation}s to the table. The mutations will be buffered and sent over the wire 103 * as part of a batch. There is no guarantee of sending entire content of {@code mutations} in a 104 * single batch; it will be broken up according to the write buffer capacity. 105 * @param mutations The data to send. 106 * @throws IOException if a remote or network exception occurs. 107 */ 108 void mutate(List<? extends Mutation> mutations) throws IOException; 109 110 /** 111 * Performs a {@link #flush()} and releases any resources held. 112 * @throws IOException if a remote or network exception occurs. 113 */ 114 @Override 115 void close() throws IOException; 116 117 /** 118 * Executes all the buffered, asynchronous {@link Mutation} operations and waits until they are 119 * done. 120 * @throws IOException if a remote or network exception occurs. 121 */ 122 void flush() throws IOException; 123 124 /** 125 * Sets the maximum time before the buffer is automatically flushed checking once per second. 126 * @param timeoutMs The maximum number of milliseconds how long records may be buffered before 127 * they are flushed. Set to 0 to disable. 128 */ 129 default void setWriteBufferPeriodicFlush(long timeoutMs) { 130 setWriteBufferPeriodicFlush(timeoutMs, 1000L); 131 } 132 133 /** 134 * Sets the maximum time before the buffer is automatically flushed. 135 * @param timeoutMs The maximum number of milliseconds how long records may be buffered before 136 * they are flushed. Set to 0 to disable. 137 * @param timerTickMs The number of milliseconds between each check if the timeout has been 138 * exceeded. Must be 100ms (as defined in 139 * {@link #MIN_WRITE_BUFFER_PERIODIC_FLUSH_TIMERTICK_MS}) or larger to avoid 140 * performance problems. 141 */ 142 default void setWriteBufferPeriodicFlush(long timeoutMs, long timerTickMs) { 143 throw new UnsupportedOperationException( 144 "The BufferedMutator::setWriteBufferPeriodicFlush has not been implemented"); 145 } 146 147 /** 148 * Disable periodic flushing of the write buffer. 149 */ 150 default void disableWriteBufferPeriodicFlush() { 151 setWriteBufferPeriodicFlush(0, MIN_WRITE_BUFFER_PERIODIC_FLUSH_TIMERTICK_MS); 152 } 153 154 /** 155 * Returns the current periodic flush timeout value in milliseconds. 156 * @return The maximum number of milliseconds how long records may be buffered before they are 157 * flushed. The value 0 means this is disabled. 158 */ 159 default long getWriteBufferPeriodicFlushTimeoutMs() { 160 throw new UnsupportedOperationException( 161 "The BufferedMutator::getWriteBufferPeriodicFlushTimeoutMs has not been implemented"); 162 } 163 164 /** 165 * Returns the current periodic flush timertick interval in milliseconds. 166 * @return The number of milliseconds between each check if the timeout has been exceeded. This 167 * value only has a real meaning if the timeout has been set to > 0 168 */ 169 default long getWriteBufferPeriodicFlushTimerTickMs() { 170 throw new UnsupportedOperationException( 171 "The BufferedMutator::getWriteBufferPeriodicFlushTimerTickMs has not been implemented"); 172 } 173 174 /** 175 * Returns the maximum size in bytes of the write buffer for this HTable. 176 * <p> 177 * The default value comes from the configuration parameter {@code hbase.client.write.buffer}. 178 * @return The size of the write buffer in bytes. 179 */ 180 default long getWriteBufferSize() { 181 throw new UnsupportedOperationException( 182 "The BufferedMutator::getWriteBufferSize has not been implemented"); 183 } 184 185 /** 186 * Set rpc timeout for this mutator instance 187 * @deprecated Since 3.0.0, will be removed in 4.0.0. Please set this through the 188 * {@link BufferedMutatorParams}. 189 */ 190 @Deprecated 191 default void setRpcTimeout(int timeout) { 192 throw new UnsupportedOperationException( 193 "The BufferedMutator::setRpcTimeout has not been implemented"); 194 } 195 196 /** 197 * Set operation timeout for this mutator instance 198 * @deprecated Since 3.0.0, will be removed in 4.0.0. Please set this through the 199 * {@link BufferedMutatorParams}. 200 */ 201 @Deprecated 202 default void setOperationTimeout(int timeout) { 203 throw new UnsupportedOperationException( 204 "The BufferedMutator::setOperationTimeout has not been implemented"); 205 } 206 207 /** 208 * Listens for asynchronous exceptions on a {@link BufferedMutator}. 209 */ 210 @InterfaceAudience.Public 211 interface ExceptionListener { 212 public void onException(RetriesExhaustedWithDetailsException exception, BufferedMutator mutator) 213 throws RetriesExhaustedWithDetailsException; 214 } 215}