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 }