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 }