1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 package org.apache.hadoop.hbase.regionserver; 19 20 import java.io.IOException; 21 import java.util.Collection; 22 import java.util.List; 23 import java.util.UUID; 24 25 import org.apache.hadoop.hbase.classification.InterfaceAudience; 26 import org.apache.hadoop.hbase.classification.InterfaceStability; 27 import org.apache.hadoop.hbase.client.Durability; 28 import org.apache.hadoop.hbase.client.Mutation; 29 import org.apache.hadoop.hbase.HBaseInterfaceAudience; 30 import org.apache.hadoop.hbase.regionserver.wal.WALEdit; 31 32 import com.google.protobuf.Message; 33 34 /** 35 * Defines the procedure to atomically perform multiple scans and mutations 36 * on a HRegion. 37 * 38 * This is invoked by HRegion#processRowsWithLocks(). 39 * This class performs scans and generates mutations and WAL edits. 40 * The locks and MVCC will be handled by HRegion. 41 * 42 * The RowProcessor user code could have data that needs to be 43 * sent across for proper initialization at the server side. The generic type 44 * parameter S is the type of the request data sent to the server. 45 * The generic type parameter T is the return type of RowProcessor.getResult(). 46 */ 47 @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC) 48 @InterfaceStability.Evolving 49 public interface RowProcessor<S extends Message, T extends Message> { 50 51 /** 52 * Rows to lock while operation. 53 * They have to be sorted with <code>RowProcessor</code> 54 * to avoid deadlock. 55 */ 56 Collection<byte[]> getRowsToLock(); 57 58 /** 59 * Obtain the processing result. All row processor implementations must 60 * implement this, even if the method is simply returning an empty 61 * Message. 62 */ 63 T getResult(); 64 65 /** 66 * Is this operation read only? If this is true, process() should not add 67 * any mutations or it throws IOException. 68 * @return ture if read only operation 69 */ 70 boolean readOnly(); 71 72 /** 73 * HRegion handles the locks and MVCC and invokes this method properly. 74 * 75 * You should override this to create your own RowProcessor. 76 * 77 * If you are doing read-modify-write here, you should consider using 78 * <code>IsolationLevel.READ_UNCOMMITTED</code> for scan because 79 * we advance MVCC after releasing the locks for optimization purpose. 80 * 81 * @param now the current system millisecond 82 * @param region the HRegion 83 * @param mutations the output mutations to apply to memstore 84 * @param walEdit the output WAL edits to apply to write ahead log 85 */ 86 void process(long now, 87 HRegion region, 88 List<Mutation> mutations, 89 WALEdit walEdit) throws IOException; 90 91 /** 92 * The hook to be executed before process(). 93 * 94 * @param region the HRegion 95 * @param walEdit the output WAL edits to apply to write ahead log 96 */ 97 void preProcess(HRegion region, WALEdit walEdit) throws IOException; 98 99 /** 100 * The hook to be executed after the process() but before applying the Mutations to region. Also 101 * by the time this hook is been called, mvcc transaction is started. 102 * @param region 103 * @param walEdit the output WAL edits to apply to write ahead log 104 * @throws IOException 105 */ 106 void preBatchMutate(HRegion region, WALEdit walEdit) throws IOException; 107 108 /** 109 * The hook to be executed after the process() and applying the Mutations to region. The 110 * difference of this one with {@link #postProcess(HRegion, WALEdit, boolean)} is this hook will 111 * be executed before the mvcc transaction completion. 112 * @param region 113 * @throws IOException 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 }