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.client.Durability;
27  import org.apache.hadoop.hbase.client.Mutation;
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<Mutation> 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 the process() but before applying the Mutations to region. Also
99     * by the time this hook is been called, mvcc transaction is started.
100    * @param region
101    * @param walEdit the output WAL edits to apply to write ahead log
102    * @throws IOException
103    */
104   void preBatchMutate(HRegion region, WALEdit walEdit) throws IOException;
105 
106   /**
107    * The hook to be executed after the process() and applying the Mutations to region. The
108    * difference of this one with {@link #postProcess(HRegion, WALEdit, boolean)} is this hook will
109    * be executed before the mvcc transaction completion.
110    * @param region
111    * @throws IOException
112    */
113   void postBatchMutate(HRegion region) throws IOException;
114 
115   /**
116    * The hook to be executed after process() and applying the Mutations to region.
117    *
118    * @param region the HRegion
119    * @param walEdit the output WAL edits to apply to write ahead log
120    * @param success true if batch operation is successful otherwise false.
121    */
122   void postProcess(HRegion region, WALEdit walEdit, boolean success) throws IOException;
123 
124   /**
125    * @return The cluster ids that have the change.
126    */
127   List<UUID> getClusterIds();
128 
129   /**
130    * Human readable name of the processor
131    * @return The name of the processor
132    */
133   String getName();
134 
135   /**
136    * This method should return any additional data that is needed on the
137    * server side to construct the RowProcessor. The server will pass this to
138    * the {@link #initialize(Message msg)} method. If there is no RowProcessor
139    * specific data then null should be returned.
140    * @return the PB message
141    * @throws IOException
142    */
143   S getRequestData() throws IOException;
144 
145   /**
146    * This method should initialize any field(s) of the RowProcessor with
147    * a parsing of the passed message bytes (used on the server side).
148    * @param msg
149    * @throws IOException
150    */
151   void initialize(S msg) throws IOException;
152 
153   /**
154    * @return The {@link Durability} to use
155    */
156   Durability useDurability();
157 }