View Javadoc

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.classification.InterfaceAudience;
26  import org.apache.hadoop.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 }