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.types; 19 20 import org.apache.hadoop.hbase.classification.InterfaceAudience; 21 import org.apache.hadoop.hbase.classification.InterfaceStability; 22 import org.apache.hadoop.hbase.util.Order; 23 import org.apache.hadoop.hbase.util.PositionedByteRange; 24 25 /** 26 * <p> 27 * {@code DataType} is the base class for all HBase data types. Data 28 * type implementations are designed to be serialized to and deserialized from 29 * byte[]. Serialized representations can retain the natural sort ordering of 30 * the source object, when a suitable encoding is supported by the underlying 31 * implementation. This is a desirable feature for use in rowkeys and column 32 * qualifiers. 33 * </p> 34 * <p> 35 * {@code DataType}s are different from Hadoop 36 * {@link org.apache.hadoop.hbase.io.ImmutableBytesWritable}s in two 37 * significant ways. First, {@code DataType} describes how to serialize a 38 * value, it does not encapsulate a serialized value. Second, {@code DataType} 39 * implementations provide hints to consumers about relationships between the 40 * POJOs they represent and richness of the encoded representation. 41 * </p> 42 * <p> 43 * Data type instances are designed to be stateless, thread-safe, and reused. 44 * Implementations should provide {@code static final} instances corresponding 45 * to each variation on configurable parameters. This is to encourage and 46 * simplify instance reuse. For instance, order-preserving types should provide 47 * static ASCENDING and DESCENDING instances. It is also encouraged for 48 * implementations operating on Java primitive types to provide primitive 49 * implementations of the {@code encode} and {@code decode} methods. This 50 * advice is a performance consideration to clients reading and writing values 51 * in tight loops. 52 * </p> 53 */ 54 @InterfaceAudience.Public 55 @InterfaceStability.Evolving 56 public interface DataType<T> { 57 58 /** 59 * Indicates whether this instance writes encoded {@code byte[]}'s 60 * which preserve the natural sort order of the unencoded value. 61 * @return {@code true} when natural order is preserved, 62 * {@code false} otherwise. 63 */ 64 public boolean isOrderPreserving(); 65 66 /** 67 * Retrieve the sort {@link Order} imposed by this data type, or null when 68 * natural ordering is not preserved. Value is either ascending or 69 * descending. Default is assumed to be {@link Order#ASCENDING}. 70 */ 71 public Order getOrder(); 72 73 /** 74 * Indicates whether this instance supports encoding null values. This 75 * depends on the implementation details of the encoding format. All 76 * {@code DataType}s that support null should treat null as comparing 77 * less than any non-null value for default sort ordering purposes. 78 * @return {@code true} when null is supported, {@code false} otherwise. 79 */ 80 public boolean isNullable(); 81 82 /** 83 * Indicates whether this instance is able to skip over it's encoded value. 84 * {@code DataType}s that are not skippable can only be used as the 85 * right-most field of a {@link Struct}. 86 */ 87 public boolean isSkippable(); 88 89 /** 90 * Inform consumers how long the encoded {@code byte[]} will be. 91 * @param val The value to check. 92 * @return the number of bytes required to encode {@code val}.a 93 */ 94 public int encodedLength(T val); 95 96 /** 97 * Inform consumers over what type this {@code DataType} operates. Useful 98 * when working with bare {@code DataType} instances. 99 */ 100 public Class<T> encodedClass(); 101 102 /** 103 * Skip {@code src}'s position forward over one encoded value. 104 * @param src the buffer containing the encoded value. 105 * @return number of bytes skipped. 106 */ 107 public int skip(PositionedByteRange src); 108 109 /** 110 * Read an instance of {@code T} from the buffer {@code src}. 111 * @param src the buffer containing the encoded value. 112 */ 113 public T decode(PositionedByteRange src); 114 115 /** 116 * Write instance {@code val} into buffer {@code dst}. 117 * @param dst the buffer containing the encoded value. 118 * @param val the value to encode onto {@code dst}. 119 * @return number of bytes written. 120 */ 121 public int encode(PositionedByteRange dst, T val); 122 }