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.client.Durability;
29  import org.apache.hadoop.hbase.regionserver.wal.WALEdit;
30  
31  import com.google.protobuf.ByteString;
32  import com.google.protobuf.Message;
33  
34  @InterfaceAudience.Public
35  @InterfaceStability.Evolving
36  
37  /**
38   * Defines the procedure to atomically perform multiple scans and mutations
39   * on a HRegion.
40   *
41   * This is invoked by HRegion#processRowsWithLocks().
42   * This class performs scans and generates mutations and WAL edits.
43   * The locks and MVCC will be handled by HRegion.
44   *
45   * The RowProcessor user code could have data that needs to be 
46   * sent across for proper initialization at the server side. The generic type 
47   * parameter S is the type of the request data sent to the server.
48   * The generic type parameter T is the return type of RowProcessor.getResult().
49   */
50  public interface RowProcessor<S extends Message, T extends Message> {
51  
52    /**
53     * Rows to lock while operation.
54     * They have to be sorted with <code>RowProcessor</code>
55     * to avoid deadlock.
56     */
57    Collection<byte[]> getRowsToLock();
58  
59    /**
60     * Obtain the processing result. All row processor implementations must
61     * implement this, even if the method is simply returning an empty
62     * Message.
63     */
64    T getResult();
65  
66    /**
67     * Is this operation read only? If this is true, process() should not add
68     * any mutations or it throws IOException.
69     * @return ture if read only operation
70     */
71    boolean readOnly();
72  
73    /**
74     * HRegion handles the locks and MVCC and invokes this method properly.
75     *
76     * You should override this to create your own RowProcessor.
77     *
78     * If you are doing read-modify-write here, you should consider using
79     * <code>IsolationLevel.READ_UNCOMMITTED</code> for scan because
80     * we advance MVCC after releasing the locks for optimization purpose.
81     *
82     * @param now the current system millisecond
83     * @param region the HRegion
84     * @param mutations the output mutations to apply to memstore
85     * @param walEdit the output WAL edits to apply to write ahead log
86     */
87    void process(long now,
88                 HRegion region,
89                 List<KeyValue> mutations,
90                 WALEdit walEdit) throws IOException;
91  
92    /**
93     * The hook to be executed before process().
94     *
95     * @param region the HRegion
96     * @param walEdit the output WAL edits to apply to write ahead log
97     */
98    void preProcess(HRegion region, WALEdit walEdit) throws IOException;
99  
100   /**
101    * The hook to be executed after process().
102    *
103    * @param region the HRegion
104    * @param walEdit the output WAL edits to apply to write ahead log
105    */
106   void postProcess(HRegion region, WALEdit walEdit) throws IOException;
107 
108 
109   /**
110    * @return The replication cluster id.
111    */
112   UUID getClusterId();
113 
114   /**
115    * Human readable name of the processor
116    * @return The name of the processor
117    */
118   String getName();
119 
120   /**
121    * This method should return any additional data that is needed on the
122    * server side to construct the RowProcessor. The server will pass this to
123    * the {@link #initialize(Message msg)} method. If there is no RowProcessor
124    * specific data then null should be returned.
125    * @return the PB message
126    * @throws IOException
127    */
128   S getRequestData() throws IOException;
129 
130   /**
131    * This method should initialize any field(s) of the RowProcessor with
132    * a parsing of the passed message bytes (used on the server side).
133    * @param msg
134    * @throws IOException
135    */
136   void initialize(S msg) throws IOException;
137 
138   /**
139    * @return The {@link Durability} to use
140    */
141   Durability useDurability();
142 }