org.apache.hudi.org.apache.hadoop.hbase.types.Struct Maven / Gradle / Ivy
/**
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.hadoop.hbase.types;
import java.util.Iterator;
import org.apache.hadoop.hbase.util.Order;
import org.apache.hadoop.hbase.util.PositionedByteRange;
import org.apache.yetus.audience.InterfaceAudience;
/**
*
* {@code Struct} is a simple {@link DataType} for implementing "compound
* rowkey" and "compound qualifier" schema design strategies.
*
* Encoding
*
* {@code Struct} member values are encoded onto the target byte[] in the order
* in which they are declared. A {@code Struct} may be used as a member of
* another {@code Struct}. {@code Struct}s are not {@code nullable} but their
* component fields may be.
*
* Trailing Nulls
*
* {@code Struct} treats the right-most nullable field members as special.
* Rather than writing null values to the output buffer, {@code Struct} omits
* those records all together. When reading back a value, it will look for the
* scenario where the end of the buffer has been reached but there are still
* nullable fields remaining in the {@code Struct} definition. When this
* happens, it will produce null entries for the remaining values. For example:
*
*
* StructBuilder builder = new StructBuilder()
* .add(OrderedNumeric.ASCENDING) // nullable
* .add(OrderedString.ASCENDING) // nullable
* Struct shorter = builder.toStruct();
* Struct longer = builder.add(OrderedNumeric.ASCENDING) // nullable
* .toStruct();
*
* PositionedByteRange buf1 = new SimplePositionedByteRange(7);
* PositionedByteRange buf2 = new SimplePositionedByteRange(7);
* Object[] val = new Object[] { BigDecimal.ONE, "foo" };
* shorter.encode(buf1, val); // write short value with short Struct
* buf1.setPosition(0); // reset position marker, prepare for read
* longer.decode(buf1); // => { BigDecimal.ONE, "foo", null } ; long Struct reads implied null
* longer.encode(buf2, val); // write short value with long struct
* Bytes.equals(buf1.getBytes(), buf2.getBytes()); // => true; long Struct skips writing null
*
* Sort Order
*
* {@code Struct} instances sort according to the composite order of their
* fields, that is, left-to-right and depth-first. This can also be thought of
* as lexicographic comparison of concatenated members.
*
*
* {@link StructIterator} is provided as a convenience for consuming the
* sequence of values. Users may find it more appropriate to provide their own
* custom {@link DataType} for encoding application objects rather than using
* this {@code Object[]} implementation. Examples are provided in test.
*
* @see StructIterator
* @see DataType#isNullable()
*/
@InterfaceAudience.Public
public class Struct implements DataType