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.client;
19  
20  import java.io.IOException;
21  import java.util.Map;
22  
23  import com.google.common.collect.Maps;
24  import org.apache.hadoop.hbase.classification.InterfaceAudience;
25  import org.apache.hadoop.hbase.classification.InterfaceStability;
26  import org.apache.hadoop.hbase.exceptions.DeserializationException;
27  import org.apache.hadoop.hbase.filter.Filter;
28  import org.apache.hadoop.hbase.io.TimeRange;
29  import org.apache.hadoop.hbase.protobuf.ProtobufUtil;
30  import org.apache.hadoop.hbase.security.access.AccessControlConstants;
31  import org.apache.hadoop.hbase.security.access.Permission;
32  import org.apache.hadoop.hbase.security.visibility.Authorizations;
33  import org.apache.hadoop.hbase.security.visibility.VisibilityConstants;
34  import com.google.common.collect.ArrayListMultimap;
35  import com.google.common.collect.ListMultimap;
36  import org.apache.hadoop.hbase.util.Bytes;
37  
38  @InterfaceAudience.Public
39  @InterfaceStability.Evolving
40  public abstract class Query extends OperationWithAttributes {
41    private static final String ISOLATION_LEVEL = "_isolationlevel_";
42    protected Filter filter = null;
43    protected int targetReplicaId = -1;
44    protected Consistency consistency = Consistency.STRONG;
45    protected Map<byte[], TimeRange> colFamTimeRangeMap = Maps.newTreeMap(Bytes.BYTES_COMPARATOR);
46  
47    /**
48     * @return Filter
49     */
50    public Filter getFilter() {
51      return filter;
52    }
53  
54    /**
55     * Apply the specified server-side filter when performing the Query.
56     * Only {@link Filter#filterKeyValue(Cell)} is called AFTER all tests
57     * for ttl, column match, deletes and max versions have been run.
58     * @param filter filter to run on the server
59     * @return this for invocation chaining
60     */
61    public Query setFilter(Filter filter) {
62      this.filter = filter;
63      return this;
64    }
65  
66    /**
67     * Sets the authorizations to be used by this Query
68     * @param authorizations
69     */
70    public Query setAuthorizations(Authorizations authorizations) {
71      this.setAttribute(VisibilityConstants.VISIBILITY_LABELS_ATTR_KEY, ProtobufUtil
72          .toAuthorizations(authorizations).toByteArray());
73      return this;
74    }
75  
76    /**
77     * @return The authorizations this Query is associated with.
78     * @throws DeserializationException
79     */
80    public Authorizations getAuthorizations() throws DeserializationException {
81      byte[] authorizationsBytes = this.getAttribute(VisibilityConstants.VISIBILITY_LABELS_ATTR_KEY);
82      if (authorizationsBytes == null) return null;
83      return ProtobufUtil.toAuthorizations(authorizationsBytes);
84    }
85  
86    /**
87     * @return The serialized ACL for this operation, or null if none
88     */
89    public byte[] getACL() {
90      return getAttribute(AccessControlConstants.OP_ATTRIBUTE_ACL);
91    }
92  
93    /**
94     * @param user User short name
95     * @param perms Permissions for the user
96     */
97    public Query setACL(String user, Permission perms) {
98      setAttribute(AccessControlConstants.OP_ATTRIBUTE_ACL,
99        ProtobufUtil.toUsersAndPermissions(user, perms).toByteArray());
100     return this;
101   }
102 
103   /**
104    * @param perms A map of permissions for a user or users
105    */
106   public Query setACL(Map<String, Permission> perms) {
107     ListMultimap<String, Permission> permMap = ArrayListMultimap.create();
108     for (Map.Entry<String, Permission> entry : perms.entrySet()) {
109       permMap.put(entry.getKey(), entry.getValue());
110     }
111     setAttribute(AccessControlConstants.OP_ATTRIBUTE_ACL,
112       ProtobufUtil.toUsersAndPermissions(permMap).toByteArray());
113     return this;
114   }
115 
116   /**
117    * Returns the consistency level for this operation
118    * @return the consistency level
119    */
120   public Consistency getConsistency() {
121     return consistency;
122   }
123 
124   /**
125    * Sets the consistency level for this operation
126    * @param consistency the consistency level
127    */
128   public Query setConsistency(Consistency consistency) {
129     this.consistency = consistency;
130     return this;
131   }
132 
133   /**
134    * Specify region replica id where Query will fetch data from. Use this together with
135    * {@link #setConsistency(Consistency)} passing {@link Consistency#TIMELINE} to read data from
136    * a specific replicaId.
137    * <br><b> Expert: </b>This is an advanced API exposed. Only use it if you know what you are doing
138    * @param Id
139    */
140   public Query setReplicaId(int Id) {
141     this.targetReplicaId = Id;
142     return this;
143   }
144 
145   /**
146    * Returns region replica id where Query will fetch data from.
147    * @return region replica id or -1 if not set.
148    */
149   public int getReplicaId() {
150     return this.targetReplicaId;
151   }
152 
153   /**
154    * Set the isolation level for this query. If the
155    * isolation level is set to READ_UNCOMMITTED, then
156    * this query will return data from committed and
157    * uncommitted transactions. If the isolation level
158    * is set to READ_COMMITTED, then this query will return
159    * data from committed transactions only. If a isolation
160    * level is not explicitly set on a Query, then it
161    * is assumed to be READ_COMMITTED.
162    * @param level IsolationLevel for this query
163    */
164   public Query setIsolationLevel(IsolationLevel level) {
165     setAttribute(ISOLATION_LEVEL, level.toBytes());
166     return this;
167   }
168 
169   /**
170    * @return The isolation level of this query.
171    * If no isolation level was set for this query object,
172    * then it returns READ_COMMITTED.
173    * @return The IsolationLevel for this query
174    */
175   public IsolationLevel getIsolationLevel() {
176     byte[] attr = getAttribute(ISOLATION_LEVEL);
177     return attr == null ? IsolationLevel.READ_COMMITTED :
178                           IsolationLevel.fromBytes(attr);
179   }
180 
181 
182   /**
183    * Get versions of columns only within the specified timestamp range,
184    * [minStamp, maxStamp) on a per CF bases.  Note, default maximum versions to return is 1.  If
185    * your time range spans more than one version and you want all versions
186    * returned, up the number of versions beyond the default.
187    * Column Family time ranges take precedence over the global time range.
188    *
189    * @param cf       the column family for which you want to restrict
190    * @param minStamp minimum timestamp value, inclusive
191    * @param maxStamp maximum timestamp value, exclusive
192    * @return this
193    */
194 
195   public Query setColumnFamilyTimeRange(byte[] cf, long minStamp, long maxStamp) {
196     try {
197       colFamTimeRangeMap.put(cf, new TimeRange(minStamp, maxStamp));
198       return this;
199     } catch (IOException ioe) {
200       throw new IllegalArgumentException(ioe);
201     }
202   }
203 
204   /**
205    * @return Map<byte[], TimeRange> a map of column families to time ranges
206    */
207   public Map<byte[], TimeRange> getColumnFamilyTimeRange() {
208     return this.colFamTimeRangeMap;
209   }
210 
211 
212 }