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.regionserver;
019
020import java.io.IOException;
021import java.util.Collection;
022import java.util.List;
023import java.util.UUID;
024
025import org.apache.yetus.audience.InterfaceAudience;
026import org.apache.yetus.audience.InterfaceStability;
027import org.apache.hadoop.hbase.client.Durability;
028import org.apache.hadoop.hbase.client.Mutation;
029import org.apache.hadoop.hbase.HBaseInterfaceAudience;
030import org.apache.hadoop.hbase.wal.WALEdit;
031
032import com.google.protobuf.Message;
033
034/**
035 * Defines the procedures to atomically perform multiple scans and mutations
036 * on a HRegion.
037 *
038 * This is invoked by {@link Region#processRowsWithLocks(RowProcessor)}.
039 * This class performs scans and generates mutations and WAL edits.
040 * The locks and MVCC will be handled by HRegion.
041 *
042 * The RowProcessor user code could have data that needs to be
043 * sent across for proper initialization at the server side. The generic type
044 * parameter S is the type of the request data sent to the server.
045 * The generic type parameter T is the return type of RowProcessor.getResult().
046 *
047 * @deprecated As of release 2.0.0, this will be removed in HBase 3.0.0. For customization, use
048 * Coprocessors instead.
049 */
050@Deprecated
051@InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC)
052@InterfaceStability.Evolving
053public interface RowProcessor<S extends Message, T extends Message> {
054
055  /**
056   * Rows to lock while operation.
057   * They have to be sorted with <code>RowProcessor</code>
058   * to avoid deadlock.
059   */
060  Collection<byte[]> getRowsToLock();
061
062  /**
063   * Obtain the processing result. All row processor implementations must
064   * implement this, even if the method is simply returning an empty
065   * Message.
066   */
067  T getResult();
068
069  /**
070   * Is this operation read only? If this is true, process() should not add
071   * any mutations or it throws IOException.
072   * @return ture if read only operation
073   */
074  boolean readOnly();
075
076  /**
077   * HRegion handles the locks and MVCC and invokes this method properly.
078   *
079   * You should override this to create your own RowProcessor.
080   *
081   * If you are doing read-modify-write here, you should consider using
082   * <code>IsolationLevel.READ_UNCOMMITTED</code> for scan because
083   * we advance MVCC after releasing the locks for optimization purpose.
084   *
085   * @param now the current system millisecond
086   * @param region the HRegion
087   * @param mutations the output mutations to apply to memstore
088   * @param walEdit the output WAL edits to apply to write ahead log
089   */
090  void process(long now,
091               HRegion region,
092               List<Mutation> mutations,
093               WALEdit walEdit) throws IOException;
094
095  /**
096   * The hook to be executed before process().
097   *
098   * @param region the HRegion
099   * @param walEdit the output WAL edits to apply to write ahead log
100   */
101  void preProcess(HRegion region, WALEdit walEdit) throws IOException;
102
103  /**
104   * The hook to be executed after the process() but before applying the Mutations to region. Also
105   * by the time this hook is called, mvcc transaction have started.
106   * @param walEdit the output WAL edits to apply to write ahead log
107   */
108  void preBatchMutate(HRegion region, WALEdit walEdit) throws IOException;
109
110  /**
111   * The hook to be executed after the process() and applying the Mutations to region. The
112   * difference of this one with {@link #postProcess(HRegion, WALEdit, boolean)} is this hook will
113   * be executed before the mvcc transaction completion.
114   */
115  void postBatchMutate(HRegion region) throws IOException;
116
117  /**
118   * The hook to be executed after process() and applying the Mutations to region.
119   *
120   * @param region the HRegion
121   * @param walEdit the output WAL edits to apply to write ahead log
122   * @param success true if batch operation is successful otherwise false.
123   */
124  void postProcess(HRegion region, WALEdit walEdit, boolean success) throws IOException;
125
126  /**
127   * @return The cluster ids that have the change.
128   */
129  List<UUID> getClusterIds();
130
131  /**
132   * Human readable name of the processor
133   * @return The name of the processor
134   */
135  String getName();
136
137  /**
138   * This method should return any additional data that is needed on the
139   * server side to construct the RowProcessor. The server will pass this to
140   * the {@link #initialize(Message msg)} method. If there is no RowProcessor
141   * specific data then null should be returned.
142   * @return the PB message
143   * @throws IOException
144   */
145  S getRequestData() throws IOException;
146
147  /**
148   * This method should initialize any field(s) of the RowProcessor with
149   * a parsing of the passed message bytes (used on the server side).
150   * @param msg
151   * @throws IOException
152   */
153  void initialize(S msg) throws IOException;
154
155  /**
156   * @return The {@link Durability} to use
157   */
158  Durability useDurability();
159}