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.types; 019 020import org.apache.hadoop.hbase.util.Order; 021import org.apache.hadoop.hbase.util.PositionedByteRange; 022import org.apache.yetus.audience.InterfaceAudience; 023 024/** 025 * <p> 026 * {@code DataType} is the base class for all HBase data types. Data type implementations are 027 * designed to be serialized to and deserialized from byte[]. Serialized representations can retain 028 * the natural sort ordering of the source object, when a suitable encoding is supported by the 029 * underlying implementation. This is a desirable feature for use in rowkeys and column qualifiers. 030 * </p> 031 * <p> 032 * {@code DataType}s are different from Hadoop 033 * {@link org.apache.hadoop.hbase.io.ImmutableBytesWritable}s in two significant ways. First, 034 * {@code DataType} describes how to serialize a value, it does not encapsulate a serialized value. 035 * Second, {@code DataType} implementations provide hints to consumers about relationships between 036 * the POJOs they represent and richness of the encoded representation. 037 * </p> 038 * <p> 039 * Data type instances are designed to be stateless, thread-safe, and reused. Implementations should 040 * provide {@code static final} instances corresponding to each variation on configurable 041 * parameters. This is to encourage and simplify instance reuse. For instance, order-preserving 042 * types should provide static ASCENDING and DESCENDING instances. It is also encouraged for 043 * implementations operating on Java primitive types to provide primitive implementations of the 044 * {@code encode} and {@code decode} methods. This advice is a performance consideration to clients 045 * reading and writing values in tight loops. 046 * </p> 047 */ 048@InterfaceAudience.Public 049public interface DataType<T> { 050 051 /** 052 * Indicates whether this instance writes encoded {@code byte[]}'s which preserve the natural sort 053 * order of the unencoded value. 054 * @return {@code true} when natural order is preserved, {@code false} otherwise. 055 */ 056 boolean isOrderPreserving(); 057 058 /** 059 * Retrieve the sort {@link Order} imposed by this data type, or null when natural ordering is not 060 * preserved. Value is either ascending or descending. Default is assumed to be 061 * {@link Order#ASCENDING}. 062 */ 063 Order getOrder(); 064 065 /** 066 * Indicates whether this instance supports encoding null values. This depends on the 067 * implementation details of the encoding format. All {@code DataType}s that support null should 068 * treat null as comparing less than any non-null value for default sort ordering purposes. 069 * @return {@code true} when null is supported, {@code false} otherwise. 070 */ 071 boolean isNullable(); 072 073 /** 074 * Indicates whether this instance is able to skip over it's encoded value. {@code DataType}s that 075 * are not skippable can only be used as the right-most field of a {@link Struct}. 076 */ 077 boolean isSkippable(); 078 079 /** 080 * Inform consumers how long the encoded {@code byte[]} will be. 081 * @param val The value to check. 082 * @return the number of bytes required to encode {@code val}.a 083 */ 084 int encodedLength(T val); 085 086 /** 087 * Inform consumers over what type this {@code DataType} operates. Useful when working with bare 088 * {@code DataType} instances. 089 */ 090 Class<T> encodedClass(); 091 092 /** 093 * Skip {@code src}'s position forward over one encoded value. 094 * @param src the buffer containing the encoded value. 095 * @return number of bytes skipped. 096 */ 097 int skip(PositionedByteRange src); 098 099 /** 100 * Read an instance of {@code T} from the buffer {@code src}. 101 * @param src the buffer containing the encoded value. 102 */ 103 T decode(PositionedByteRange src); 104 105 /** 106 * Write instance {@code val} into buffer {@code dst}. 107 * @param dst the buffer containing the encoded value. 108 * @param val the value to encode onto {@code dst}. 109 * @return number of bytes written. 110 */ 111 int encode(PositionedByteRange dst, T val); 112}