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}