solr/core/src/java/org/apache/solr/util/hll/ISchemaVersion.java

/*
 * 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.solr.util.hll;

/**
 * A serialization schema for HLLs. Reads and writes HLL metadata to
 * and from <code>byte[]</code> representations.
 */
public interface ISchemaVersion {
    /**
     * The number of metadata bytes required for a serialized HLL of the
     * specified type.
     *
     * @param  type the type of the serialized HLL
     * @return the number of padding bytes needed in order to fully accommodate
     *         the needed metadata.
     */
    int paddingBytes(HLLType type);

    /**
     * Writes metadata bytes to serialized HLL.
     *
     * @param bytes the padded data bytes of the HLL
     * @param metadata the metadata to write to the padding bytes
     */
    void writeMetadata(byte[] bytes, IHLLMetadata metadata);

    /**
     * Reads the metadata bytes of the serialized HLL.
     *
     * @param  bytes the serialized HLL
     * @return the HLL metadata
     */
    IHLLMetadata readMetadata(byte[] bytes);

    /**
     * Builds an HLL serializer that matches this schema version.
     *
     * @param  type the HLL type that will be serialized. This cannot be
     *         <code>null</code>.
     * @param  wordLength the length of the 'words' that comprise the data of the
     *         HLL. Words must be at least 5 bits and at most 64 bits long.
     * @param  wordCount the number of 'words' in the HLL's data.
     * @return a byte array serializer used to serialize a HLL according
     *         to this schema version's specification.
     * @see #paddingBytes(HLLType)
     * @see IWordSerializer
     */
    IWordSerializer getSerializer(HLLType type, int wordLength, int wordCount);

    /**
     * Builds an HLL deserializer that matches this schema version.
     *
     * @param  type the HLL type that will be deserialized. This cannot be
     *         <code>null</code>.
     * @param  wordLength the length of the 'words' that comprise the data of the
     *         serialized HLL. Words must be at least 5 bits and at most 64
     *         bits long.
     * @param  bytes the serialized HLL to deserialize. This cannot be
     *         <code>null</code>.
     * @return a byte array deserializer used to deserialize a HLL serialized
     *         according to this schema version's specification.
     */
    IWordDeserializer getDeserializer(HLLType type, int wordLength, byte[] bytes);

    /**
     * @return the schema version number.
     */
    int schemaVersionNumber();
}