hbase-client/src/main/java/org/apache/hadoop/hbase/client/Query.java

   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.util.Map;
  21
  22 import org.apache.hbase.thirdparty.com.google.common.collect.Maps;
  23 import org.apache.yetus.audience.InterfaceAudience;
  24 import org.apache.hadoop.hbase.exceptions.DeserializationException;
  25 import org.apache.hadoop.hbase.filter.Filter;
  26 import org.apache.hadoop.hbase.io.TimeRange;
  27 import org.apache.hadoop.hbase.security.access.AccessControlConstants;
  28 import org.apache.hadoop.hbase.security.access.AccessControlUtil;
  29 import org.apache.hadoop.hbase.security.access.Permission;
  30 import org.apache.hadoop.hbase.security.visibility.Authorizations;
  31 import org.apache.hadoop.hbase.security.visibility.VisibilityConstants;
  32 import org.apache.hadoop.hbase.shaded.protobuf.ProtobufUtil;
  33
  34 import org.apache.hbase.thirdparty.com.google.common.collect.ArrayListMultimap;
  35 import org.apache.hbase.thirdparty.com.google.common.collect.ListMultimap;
  36 import org.apache.hadoop.hbase.util.Bytes;
  37
  38 /**
  39  * Base class for HBase read operations; e.g. Scan and Get.
  40  */
  41 @InterfaceAudience.Public
  42 public abstract class Query extends OperationWithAttributes {
  43   private static final String ISOLATION_LEVEL = "_isolationlevel_";
  44   protected Filter filter = null;
  45   protected int targetReplicaId = -1;
  46   protected Consistency consistency = Consistency.STRONG;
  47   protected Map<byte[], TimeRange> colFamTimeRangeMap = Maps.newTreeMap(Bytes.BYTES_COMPARATOR);
  48   protected Boolean loadColumnFamiliesOnDemand = null;
  49   /**
  50    * @return Filter
  51    */
  52   public Filter getFilter() {
  53     return filter;
  54   }
  55
  56   /**
  57    * Apply the specified server-side filter when performing the Query. Only
  58    * {@link Filter#filterCell(org.apache.hadoop.hbase.Cell)} is called AFTER all tests for ttl,
  59    * column match, deletes and column family's max versions have been run.
  60    * @param filter filter to run on the server
  61    * @return this for invocation chaining
  62    */
  63   public Query setFilter(Filter filter) {
  64     this.filter = filter;
  65     return this;
  66   }
  67
  68   /**
  69    * Sets the authorizations to be used by this Query
  70    * @param authorizations
  71    */
  72   public Query setAuthorizations(Authorizations authorizations) {
  73     this.setAttribute(VisibilityConstants.VISIBILITY_LABELS_ATTR_KEY, ProtobufUtil
  74         .toAuthorizations(authorizations).toByteArray());
  75     return this;
  76   }
  77
  78   /**
  79    * @return The authorizations this Query is associated with.
  80    * @throws DeserializationException
  81    */
  82   public Authorizations getAuthorizations() throws DeserializationException {
  83     byte[] authorizationsBytes = this.getAttribute(VisibilityConstants.VISIBILITY_LABELS_ATTR_KEY);
  84     if (authorizationsBytes == null) return null;
  85     return ProtobufUtil.toAuthorizations(authorizationsBytes);
  86   }
  87
  88   /**
  89    * @return The serialized ACL for this operation, or null if none
  90    */
  91   public byte[] getACL() {
  92     return getAttribute(AccessControlConstants.OP_ATTRIBUTE_ACL);
  93   }
  94
  95   /**
  96    * @param user User short name
  97    * @param perms Permissions for the user
  98    */
  99   public Query setACL(String user, Permission perms) {
 100     setAttribute(AccessControlConstants.OP_ATTRIBUTE_ACL,
 101       AccessControlUtil.toUsersAndPermissions(user, perms).toByteArray());
 102     return this;
 103   }
 104
 105   /**
 106    * @param perms A map of permissions for a user or users
 107    */
 108   public Query setACL(Map<String, Permission> perms) {
 109     ListMultimap<String, Permission> permMap = ArrayListMultimap.create();
 110     for (Map.Entry<String, Permission> entry : perms.entrySet()) {
 111       permMap.put(entry.getKey(), entry.getValue());
 112     }
 113     setAttribute(AccessControlConstants.OP_ATTRIBUTE_ACL,
 114         AccessControlUtil.toUsersAndPermissions(permMap).toByteArray());
 115     return this;
 116   }
 117
 118   /**
 119    * Returns the consistency level for this operation
 120    * @return the consistency level
 121    */
 122   public Consistency getConsistency() {
 123     return consistency;
 124   }
 125
 126   /**
 127    * Sets the consistency level for this operation
 128    * @param consistency the consistency level
 129    */
 130   public Query setConsistency(Consistency consistency) {
 131     this.consistency = consistency;
 132     return this;
 133   }
 134
 135   /**
 136    * Specify region replica id where Query will fetch data from. Use this together with
 137    * {@link #setConsistency(Consistency)} passing {@link Consistency#TIMELINE} to read data from
 138    * a specific replicaId.
 139    * <br><b> Expert: </b>This is an advanced API exposed. Only use it if you know what you are doing
 140    * @param Id
 141    */
 142   public Query setReplicaId(int Id) {
 143     this.targetReplicaId = Id;
 144     return this;
 145   }
 146
 147   /**
 148    * Returns region replica id where Query will fetch data from.
 149    * @return region replica id or -1 if not set.
 150    */
 151   public int getReplicaId() {
 152     return this.targetReplicaId;
 153   }
 154
 155   /**
 156    * Set the isolation level for this query. If the
 157    * isolation level is set to READ_UNCOMMITTED, then
 158    * this query will return data from committed and
 159    * uncommitted transactions. If the isolation level
 160    * is set to READ_COMMITTED, then this query will return
 161    * data from committed transactions only. If a isolation
 162    * level is not explicitly set on a Query, then it
 163    * is assumed to be READ_COMMITTED.
 164    * @param level IsolationLevel for this query
 165    */
 166   public Query setIsolationLevel(IsolationLevel level) {
 167     setAttribute(ISOLATION_LEVEL, level.toBytes());
 168     return this;
 169   }
 170
 171   /**
 172    * @return The isolation level of this query.
 173    * If no isolation level was set for this query object,
 174    * then it returns READ_COMMITTED.
 175    * @return The IsolationLevel for this query
 176    */
 177   public IsolationLevel getIsolationLevel() {
 178     byte[] attr = getAttribute(ISOLATION_LEVEL);
 179     return attr == null ? IsolationLevel.READ_COMMITTED :
 180                           IsolationLevel.fromBytes(attr);
 181   }
 182
 183   /**
 184    * Set the value indicating whether loading CFs on demand should be allowed (cluster
 185    * default is false). On-demand CF loading doesn't load column families until necessary, e.g.
 186    * if you filter on one column, the other column family data will be loaded only for the rows
 187    * that are included in result, not all rows like in normal case.
 188    * With column-specific filters, like SingleColumnValueFilter w/filterIfMissing == true,
 189    * this can deliver huge perf gains when there's a cf with lots of data; however, it can
 190    * also lead to some inconsistent results, as follows:
 191    * - if someone does a concurrent update to both column families in question you may get a row
 192    *   that never existed, e.g. for { rowKey = 5, { cat_videos =&gt; 1 }, { video =&gt; "my cat" } }
 193    *   someone puts rowKey 5 with { cat_videos =&gt; 0 }, { video =&gt; "my dog" }, concurrent scan
 194    *   filtering on "cat_videos == 1" can get { rowKey = 5, { cat_videos =&gt; 1 },
 195    *   { video =&gt; "my dog" } }.
 196    * - if there's a concurrent split and you have more than 2 column families, some rows may be
 197    *   missing some column families.
 198    */
 199   public Query setLoadColumnFamiliesOnDemand(boolean value) {
 200     this.loadColumnFamiliesOnDemand = value;
 201     return this;
 202   }
 203
 204   /**
 205    * Get the raw loadColumnFamiliesOnDemand setting; if it's not set, can be null.
 206    */
 207   public Boolean getLoadColumnFamiliesOnDemandValue() {
 208     return this.loadColumnFamiliesOnDemand;
 209   }
 210
 211   /**
 212    * Get the logical value indicating whether on-demand CF loading should be allowed.
 213    */
 214   public boolean doLoadColumnFamiliesOnDemand() {
 215     return (this.loadColumnFamiliesOnDemand != null)
 216       && this.loadColumnFamiliesOnDemand;
 217   }
 218
 219   /**
 220    * Get versions of columns only within the specified timestamp range,
 221    * [minStamp, maxStamp) on a per CF bases.  Note, default maximum versions to return is 1.  If
 222    * your time range spans more than one version and you want all versions
 223    * returned, up the number of versions beyond the default.
 224    * Column Family time ranges take precedence over the global time range.
 225    *
 226    * @param cf       the column family for which you want to restrict
 227    * @param minStamp minimum timestamp value, inclusive
 228    * @param maxStamp maximum timestamp value, exclusive
 229    * @return this
 230    */
 231
 232   public Query setColumnFamilyTimeRange(byte[] cf, long minStamp, long maxStamp) {
 233     colFamTimeRangeMap.put(cf, TimeRange.between(minStamp, maxStamp));
 234     return this;
 235   }
 236
 237   /**
 238    * @return A map of column families to time ranges
 239    */
 240   public Map<byte[], TimeRange> getColumnFamilyTimeRange() {
 241     return this.colFamTimeRangeMap;
 242   }
 243 }