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}