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