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