ch.claude_martin.enumbitset

Interface Summary
Interface	Description
Domain<T>	A domain defines the elements that a `DomainBitSet` can contain.
DomainBitSet<T>	A bit set with a defined domain (universe).
EnumBitSetHelper<E extends Enum<E> & EnumBitSetHelper<E>>	This extends any enum type with methods for bitwise operations and use in an `EnumBitSet`.

Class Summary
Class	Description
BitSetUtilities	A collection of utility methods for `DomainBitSet`s.
EnumBitSet<E extends Enum<E> & EnumBitSetHelper<E>>	This data structure allows managing enum constants in a mutable set with methods similar to EnumSet and BitSet.
GeneralDomainBitSet<T>	Provides a mutable implementation of `DomainBitSet`, that can be used with any type.
Pair<T,X extends T,Y extends T>	An immutable, ordered pair (2-tuple) of two non-null elements.
SmallDomainBitSet<T>	BitSet with a domain of up to 64 elements.

Exception Summary
Exception	Description
MoreThan64ElementsException	Unchecked exception for any method that uses a bit set of type long (64 bits) even though the set contains more than 64 elements.

Package ch.claude_martin.enumbitset Description

EnumBitSetHelper allows to extend any enum type with methods to work with sets and bit fields, while the class EnumBitSet is an alternative for EnumSet, also containing more methods for set operations and to work with bit fields.

Bit sets are by default of type EnumBitSet, but BigInteger, BitSet, and long can be used as well. Bit masks should not be stored into a database unless you can guarantee that no problematic changes are made in the future. The only changes that would not break your code is to add new enums at the end of the list of existing enums and renaming without changing the meaning of the value. Note that EnumSet and BigInteger already has many methods to help using sets of enums and large integers.

A bit field is always used to store a set of bits. Each bit can represent one enum value. Each enum has a distinct bit mask.

Nomenclature:

enum type: Any type that is an enum. I.e. it uses "enum" instead of "class" in its declaration.
Example: Planet.class
enum: A field of an enum type. This is one single value of any enum type. To make a distinction between enum and enum type other terms such as enum element or enum constant are used.
Example: Planet.VENUS
bit field: A field whose value represents a set. A database may contain a single integer type field, which is used as a bit field. A bit set can be stored to such a bit field.
bit set: An binary number that represents a set of values. For each containing value a bit is set to 1. This can be a BitSet, a BigInteger, or a long value.
bit mask: A binary number that is used for bitwise operations on a bit set. It's basically a bit set that is applied to another set.

The goal of this interface is to allow the use of existing date types. The type EnumBitSet combines the features of such types and can be used instead, as it can be converted to all other types.

Naming conventions:
Commonly used terms from set theory are preferred. So union is used instead of AND, &, ∧ etc.

Table of set operations
name	set	logic	binary*	example	explanation
union	A ∪ B	A ∨ B	A \| B	{1,2,3} ∪ {3,4,5} = {1,2,3,4,5}	All elements that are in either A or B.
intersect	A ∩ B	A ∧ B	A & B	{1,2,3} ∩ {3,4,5} = {3}	All elements that are in both A and B.
minus	A ∖ B	A ∧ ¬B	A & ~B	{1,2,3} ∖ {3,4,5} = {1,2}	All elements that are in A, but not in B.
complement	A^C	¬A	D & ~A	A^C = Domain ∖ A	All elements that are not in A.

* bitwise operators, as used in Java.

Method names: Methods named "toXY" create a new object of type XY that represents the same set on which it is invoked. toString returns the default string representation of and equal EnumSet. Methods named "asXY" are static and take a set to convert it into a new set. Many methods of EnumBitSetHelper treat an enum constant as if it were a set with just its own value set. Conversion to a set will return a new set containing just one single value (also called singleton or unit set). toBigInteger() is an alias for bitmask().
All these methods create a new data structure. Only the methods of Set allow modification of the EnumBitSet. Enum elements can not be modified by the methods of EnumBitSetHelper.

You can use database fields with less than 64 bits. Just make sure you use an unsigned type (if your database supports this, note that standard-SQL does not). Your DB Access Library (e.g. JDBC) should handle the type conversions correctly for you. I do recommend using 64 bits in the first place as you don't have much benefit from saving some bits. To use fewer bits you can convert the value like this:
byte b = (byte) (myEnumBitSet.toLong() & 0xFF);
Invoking a method that uses 64 bit on a set with a domain of more than 64 elements will throw a MoreThan64ElementsException.