001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase.client;
019
020import java.util.Map;
021import org.apache.hadoop.hbase.exceptions.DeserializationException;
022import org.apache.hadoop.hbase.filter.Filter;
023import org.apache.hadoop.hbase.io.TimeRange;
024import org.apache.hadoop.hbase.security.access.AccessControlConstants;
025import org.apache.hadoop.hbase.security.access.AccessControlUtil;
026import org.apache.hadoop.hbase.security.access.Permission;
027import org.apache.hadoop.hbase.security.visibility.Authorizations;
028import org.apache.hadoop.hbase.security.visibility.VisibilityConstants;
029import org.apache.hadoop.hbase.util.Bytes;
030import org.apache.yetus.audience.InterfaceAudience;
031
032import org.apache.hbase.thirdparty.com.google.common.collect.ArrayListMultimap;
033import org.apache.hbase.thirdparty.com.google.common.collect.ListMultimap;
034import org.apache.hbase.thirdparty.com.google.common.collect.Maps;
035
036import org.apache.hadoop.hbase.shaded.protobuf.ProtobufUtil;
037
038/**
039 * Base class for HBase read operations; e.g. Scan and Get.
040 */
041@InterfaceAudience.Public
042public abstract class Query extends OperationWithAttributes {
043  private static final String ISOLATION_LEVEL = "_isolationlevel_";
044  protected Filter filter = null;
045  protected int targetReplicaId = -1;
046  protected Consistency consistency = Consistency.STRONG;
047  protected Map<byte[], TimeRange> colFamTimeRangeMap = Maps.newTreeMap(Bytes.BYTES_COMPARATOR);
048  protected Boolean loadColumnFamiliesOnDemand = null;
049
050  public Filter getFilter() {
051    return filter;
052  }
053
054  /**
055   * Apply the specified server-side filter when performing the Query. Only
056   * {@link Filter#filterCell(org.apache.hadoop.hbase.Cell)} is called AFTER all tests for ttl,
057   * column match, deletes and column family's max versions have been run.
058   * @param filter filter to run on the server
059   * @return this for invocation chaining
060   */
061  public Query setFilter(Filter filter) {
062    this.filter = filter;
063    return this;
064  }
065
066  /**
067   * Sets the authorizations to be used by this Query
068   */
069  public Query setAuthorizations(Authorizations authorizations) {
070    this.setAttribute(VisibilityConstants.VISIBILITY_LABELS_ATTR_KEY,
071      ProtobufUtil.toAuthorizations(authorizations).toByteArray());
072    return this;
073  }
074
075  /** Returns The authorizations this Query is associated with. n */
076  public Authorizations getAuthorizations() throws DeserializationException {
077    byte[] authorizationsBytes = this.getAttribute(VisibilityConstants.VISIBILITY_LABELS_ATTR_KEY);
078    if (authorizationsBytes == null) return null;
079    return ProtobufUtil.toAuthorizations(authorizationsBytes);
080  }
081
082  /** Returns The serialized ACL for this operation, or null if none */
083  public byte[] getACL() {
084    return getAttribute(AccessControlConstants.OP_ATTRIBUTE_ACL);
085  }
086
087  /**
088   * Set the ACL for the operation.
089   * @param user  User short name
090   * @param perms Permissions for the user
091   */
092  public Query setACL(String user, Permission perms) {
093    setAttribute(AccessControlConstants.OP_ATTRIBUTE_ACL,
094      AccessControlUtil.toUsersAndPermissions(user, perms).toByteArray());
095    return this;
096  }
097
098  /**
099   * Set the ACL for the operation.
100   * @param perms A map of permissions for a user or users
101   */
102  public Query setACL(Map<String, Permission> perms) {
103    ListMultimap<String, Permission> permMap = ArrayListMultimap.create();
104    for (Map.Entry<String, Permission> entry : perms.entrySet()) {
105      permMap.put(entry.getKey(), entry.getValue());
106    }
107    setAttribute(AccessControlConstants.OP_ATTRIBUTE_ACL,
108      AccessControlUtil.toUsersAndPermissions(permMap).toByteArray());
109    return this;
110  }
111
112  /**
113   * Returns the consistency level for this operation
114   * @return the consistency level
115   */
116  public Consistency getConsistency() {
117    return consistency;
118  }
119
120  /**
121   * Sets the consistency level for this operation
122   * @param consistency the consistency level
123   */
124  public Query setConsistency(Consistency consistency) {
125    this.consistency = consistency;
126    return this;
127  }
128
129  /**
130   * Specify region replica id where Query will fetch data from. Use this together with
131   * {@link #setConsistency(Consistency)} passing {@link Consistency#TIMELINE} to read data from a
132   * specific replicaId. <br>
133   * <b> Expert: </b>This is an advanced API exposed. Only use it if you know what you are doing
134   */
135  public Query setReplicaId(int Id) {
136    this.targetReplicaId = Id;
137    return this;
138  }
139
140  /**
141   * Returns region replica id where Query will fetch data from.
142   * @return region replica id or -1 if not set.
143   */
144  public int getReplicaId() {
145    return this.targetReplicaId;
146  }
147
148  /**
149   * Set the isolation level for this query. If the isolation level is set to READ_UNCOMMITTED, then
150   * this query will return data from committed and uncommitted transactions. If the isolation level
151   * is set to READ_COMMITTED, then this query will return data from committed transactions only. If
152   * a isolation level is not explicitly set on a Query, then it is assumed to be READ_COMMITTED.
153   * @param level IsolationLevel for this query
154   */
155  public Query setIsolationLevel(IsolationLevel level) {
156    setAttribute(ISOLATION_LEVEL, level.toBytes());
157    return this;
158  }
159
160  /**
161   * Returns The isolation level of this query. If no isolation level was set for this query object,
162   * then it returns READ_COMMITTED.
163   */
164  public IsolationLevel getIsolationLevel() {
165    byte[] attr = getAttribute(ISOLATION_LEVEL);
166    return attr == null ? IsolationLevel.READ_COMMITTED : IsolationLevel.fromBytes(attr);
167  }
168
169  /**
170   * Set the value indicating whether loading CFs on demand should be allowed (cluster default is
171   * false). On-demand CF loading doesn't load column families until necessary, e.g. if you filter
172   * on one column, the other column family data will be loaded only for the rows that are included
173   * in result, not all rows like in normal case. With column-specific filters, like
174   * SingleColumnValueFilter w/filterIfMissing == true, this can deliver huge perf gains when
175   * there's a cf with lots of data; however, it can also lead to some inconsistent results, as
176   * follows: - if someone does a concurrent update to both column families in question you may get
177   * a row that never existed, e.g. for { rowKey = 5, { cat_videos =&gt; 1 }, { video =&gt; "my cat"
178   * } } someone puts rowKey 5 with { cat_videos =&gt; 0 }, { video =&gt; "my dog" }, concurrent
179   * scan filtering on "cat_videos == 1" can get { rowKey = 5, { cat_videos =&gt; 1 }, { video =&gt;
180   * "my dog" } }. - if there's a concurrent split and you have more than 2 column families, some
181   * rows may be missing some column families.
182   */
183  public Query setLoadColumnFamiliesOnDemand(boolean value) {
184    this.loadColumnFamiliesOnDemand = value;
185    return this;
186  }
187
188  /**
189   * Get the raw loadColumnFamiliesOnDemand setting; if it's not set, can be null.
190   */
191  public Boolean getLoadColumnFamiliesOnDemandValue() {
192    return this.loadColumnFamiliesOnDemand;
193  }
194
195  /**
196   * Get the logical value indicating whether on-demand CF loading should be allowed.
197   */
198  public boolean doLoadColumnFamiliesOnDemand() {
199    return (this.loadColumnFamiliesOnDemand != null) && this.loadColumnFamiliesOnDemand;
200  }
201
202  /**
203   * Get versions of columns only within the specified timestamp range, [minStamp, maxStamp) on a
204   * per CF bases. Note, default maximum versions to return is 1. If your time range spans more than
205   * one version and you want all versions returned, up the number of versions beyond the default.
206   * Column Family time ranges take precedence over the global time range.
207   * @param cf       the column family for which you want to restrict
208   * @param minStamp minimum timestamp value, inclusive
209   * @param maxStamp maximum timestamp value, exclusive
210   */
211
212  public Query setColumnFamilyTimeRange(byte[] cf, long minStamp, long maxStamp) {
213    colFamTimeRangeMap.put(cf, new TimeRange(minStamp, maxStamp));
214    return this;
215  }
216
217  /** Returns A map of column families to time ranges */
218  public Map<byte[], TimeRange> getColumnFamilyTimeRange() {
219    return this.colFamTimeRangeMap;
220  }
221}