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.KeyValue;
28  import org.apache.hadoop.hbase.regionserver.wal.WALEdit;
29  
30  import com.google.protobuf.ByteString;
31  import com.google.protobuf.Message;
32  
33  @InterfaceAudience.Public
34  @InterfaceStability.Evolving
35  
36  /**
37   * Defines the procedure to atomically perform multiple scans and mutations
38   * on a HRegion.
39   *
40   * This is invoked by HRegion#processRowsWithLocks().
41   * This class performs scans and generates mutations and WAL edits.
42   * The locks and MVCC will be handled by HRegion.
43   *
44   * The RowProcessor user code could have data that needs to be 
45   * sent across for proper initialization at the server side. The generic type 
46   * parameter S is the type of the request data sent to the server.
47   * The generic type parameter T is the return type of RowProcessor.getResult().
48   */
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<KeyValue> 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 process().
101    *
102    * @param region the HRegion
103    * @param walEdit the output WAL edits to apply to write ahead log
104    */
105   void postProcess(HRegion region, WALEdit walEdit) throws IOException;
106 
107 
108   /**
109    * @return The replication cluster id.
110    */
111   UUID getClusterId();
112 
113   /**
114    * Human readable name of the processor
115    * @return The name of the processor
116    */
117   String getName();
118 
119   /**
120    * This method should return any additional data that is needed on the
121    * server side to construct the RowProcessor. The server will pass this to
122    * the {@link #initialize(Message msg)} method. If there is no RowProcessor
123    * specific data then null should be returned.
124    * @return the PB message
125    * @throws IOException
126    */
127   S getRequestData() throws IOException;
128 
129   /**
130    * This method should initialize any field(s) of the RowProcessor with
131    * a parsing of the passed message bytes (used on the server side).
132    * @param msg
133    * @throws IOException
134    */
135   void initialize(S msg) throws IOException;
136 }