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 */ getFilter()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 */ setFilter(Filter filter)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 */ setAuthorizations(Authorizations authorizations)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 */ getAuthorizations()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 */ getACL()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 */ setACL(String user, Permission perms)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 */ setACL(Map<String, Permission> perms)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 */ getConsistency()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 */ setConsistency(Consistency consistency)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 */ setReplicaId(int Id)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 */ getReplicaId()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 */ setIsolationLevel(IsolationLevel level)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 */ getIsolationLevel()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 setColumnFamilyTimeRange(byte[] cf, long minStamp, long maxStamp)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 */ getColumnFamilyTimeRange()207 public Map<byte[], TimeRange> getColumnFamilyTimeRange() { 208 return this.colFamTimeRangeMap; 209 } 210 211 212 } 213