net.openhft.koloboke.collect.hash.ByteHashFactory Maven / Gradle / Ivy
Show all versions of koloboke-api-jdk8 Show documentation
/*
* 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);
}