net.openhft.koloboke.collect.hash.ByteHashFactory Maven / Gradle / Ivy

/*
 * Copyright 2014 the original author or authors.
 *
 * Licensed 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 net.openhft.koloboke.collect.hash;


/**
 * Common configuration for factories of hash containers with {@code byte} keys.
 *
 * Currently {@code ByteHashFactory} allows to specify consecutive range of keys which could be
 * inserted into hash container - keys domain. This is a performance hint:
 * hash containers might, but aren't required to throw {@link IllegalArgumentException}
 * on inserting a key out of the keys domain.
 *
 * 
By default, all keys are allowed (keys domain is a whole range of {@code byte}s, from
 * {@link Byte#MIN_VALUE} to {@link Byte#MAX_VALUE}.
 *
 * 
For example, map keys or elements of the set could be unique IDs, counting from 1, thus it's
 * guaranteed that these keys are positive. Or one specific key has a special meaning in the logic
 * of your application. When you are sure that some keys range could never be put into
 * hash container, it is recommended to configure corresponding factory, which extends this
 * interface, with complement of that range as keys domain (or, alternatively, with that range
 * as keys domain complement).
 *
 * 
It's OK to specify keys domain which include some actually impossible keys, but you shouldn't
 * leave a single valid key out of the domain. If the set of possible (impossible) keys consist of
 * several ranges, and/or standalone keys, it is still recommended to specify the domain to "forbid"
 * some impossible keys. For example, if possible keys are odd numbers, you should exclude one even number, zero:
 * 
{@code
 * factory = factory.withKeysDomainComplement((byte) 0, (byte) 0);}
 * 
 *
 * @param  the concrete factory type which extends this interface
 */
public interface ByteHashFactory> extends HashContainerFactory {

    /**
     * Returns lower (inclusive) bound of keys domain.
     *
     * Default: {@link Byte#MIN_VALUE}.
     *
     * @return lower (inclusive) bound of keys domain
     */
    byte getLowerKeyDomainBound();

    /**
     * Returns upper (inclusive) bound of keys domain.
     *
     * 
Default: {@link Byte#MAX_VALUE}.
     *
     * @return upper (inclusive) bound of keys domain
     */
    byte getUpperKeyDomainBound();

    /**
     * Returns a copy of this factory with keys domain set to the specified range.
     *
     * 
This is a performance hint: hash containers might, but aren't required to throw
     * {@link IllegalArgumentException} on putting key out of the keys domain.
     *
     * 
Example:
     * 
 {@code
     * // only positive keys
     * factory = factory.withKeysDomain((byte) 1, Byte.MAX_VALUE);}
     *
     * @param minPossibleKey lower (inclusive) bound of the target keys domain
     * @param maxPossibleKey upper (inclusive) bound of the target keys domain
     * @return a copy of this factory with keys domain set to the specified range
     * @throws IllegalArgumentException if {@code minPossibleKey} is greater
     *         than {@code maxPossibleKey}
     */
    F withKeysDomain(byte minPossibleKey, byte maxPossibleKey);



    /**
     * Returns a copy of this factory with keys domain set to the complement of the specified range.
     *
     * This is a performance hint: hash containers might, but aren't required to throw
     * {@link IllegalArgumentException} on putting key out of the keys domain.
     *
     * 
This method is needed to specify keys domain that include both {@link Byte#MIN_VALUE}
     * and {@link Byte#MAX_VALUE}, but with a "hole" somewhere in between. Providing a single
     * {@link #withKeysDomain(byte, byte)} method for this and "ordinary" keys domain application
     * is error-prone, because there is no way to distinguish intention (domain with a "hole")
     * and mistakenly reordered arguments while attempting to specify "ordinary" domain.
     *
     * 
Example:
     * 
 {@code
     * // any keys except 0
     * factory = factory.withKeysDomainComplement((byte) 0, (byte) 0);}
     *
     * @param minImpossibleKey upper (exclusive) bound of the target keys domain
     * @param maxImpossibleKey lower (exclusive) bound of the target keys domain
     * @return a copy of this factory with keys domain set to the complement of the specified range
     * @throws IllegalArgumentException if {@code minImpossibleKey} is greater
     *         than {@code maxImpossibleKey}
     */
    F withKeysDomainComplement(byte minImpossibleKey, byte maxImpossibleKey);
}