Package one.microstream

Class X

  • public final class X
extends Object
    Central class for general utility methods regarding collections, arrays and some basic general functionality that is missing in Java like notNull(Object) or ints(int...).

    This class uses the following sound extension of the java naming conventions:
    Static methods that resemble a constructor, begin with an upper case letter. This is consistent with existing naming rules: method names begin with a lower case letter EXCEPT for constructor methods. This extension does nothing more than applying the same exception to constructur-like static methods. Resembling a constructor means: 1.) Indicating by name that a new instance is created. 2.) Always returning a new instance, without exception. No caching, no casting. For example: empty() or asX(List) are NOT constructor-like methods because they do not (always) create new instances.

    • Constructor Detail

      • X

        public X()

    • Method Detail

      • empty

        public static final <T> Empty<T> empty()

      • emptyTable

        public static final <K,​V> EmptyTable<K,​V> emptyTable()

      • checkArrayRange

        public static final int checkArrayRange​(long capacity)
                                 throws ArrayCapacityException
        Central validation point for Java's current technical limitation of max int as max array capacity. Note that because of dependencies of many types to arrays (e.g. toArray() methods, etc.), this limitation indirectly affects many other types, for example String, collections, ByteBuffers (which is extremely painful). It can be read that there are plans to overcome this outdated insufficiency for Java 9 or 10, so it's best to have one central point of validation that can later easily be refactored out.
        Parameters:
        capacity - the desired (array-dependent) capacity which may effectively be not greater thanInteger.MAX_VALUE.
        Returns:
        the safely downcasted capacity as an int value.
        Throws:
        ArrayCapacityException - if the passed capacity is greater than Integer.MAX_VALUE

      • isTrue

        public static final boolean isTrue​(Boolean b)
        Helper method to project ternary values to binary logic.
        Useful for checking "really true" (not false and not unknown).
        Parameters:
        b - a Boolean object.
        Returns:
        false if b is null or false

      • isFalse

        public static final boolean isFalse​(Boolean b)
        Helper method to project ternary values to binary logic.
        Useful for checking "really false" (not true and not unknown).
        Parameters:
        b - a Boolean object.
        Returns:
        false if b is null or true, otherwise true

      • isNotTrue

        public static final boolean isNotTrue​(Boolean b)
        Helper method to project ternary values to binary logic.
        Useful for checking "really not true" (either false or unknown).
        Parameters:
        b - a Boolean object.
        Returns:
        true if b is null or false, otherwise false

      • isNotFalse

        public static final boolean isNotFalse​(Boolean b)
        Helper method to project ternary values to binary logic.
        Useful for checking "really not false" (either true or unknown).
        Parameters:
        b - a Boolean object.
        Returns:
        true if b is null or true, otherwise false

      • isNull

        public static final boolean isNull​(Object reference)

      • isNotNull

        public static final boolean isNotNull​(Object reference)

      • notNull

        public static final <T> T notNull​(T object)
                           throws NullPointerException
        Transiently ensures the passed object to be not null by either returning it in case it is not null or throwing a NullPointerException otherwise.

        (Really, no idea why java.util.Objects.notNull got renamed to requireNotNull after some odd objection from some guy in the mailing list that the name would be misleading. Of course "notNull" means "the thing you pass has to be not null, otherwise you'll get an exception". What else could the meaning of a transient method named "notNull" be? If "requireNotNull" is needed to express this behavior, than what would "notNull" alone mean?
        In the end, "requireNotNull" is just additional clutter, hence not usable and is replaced by this, still properly named "notNull" method.)

        Type Parameters:
        T - the type of the object to be ensured to be not null.
        Parameters:
        object - the object to be ensured to be not null.
        Returns:
        the passed object, guaranteed to be not null.
        Throws:
        NullPointerException - if null was passed.

      • mayNull

        public static final <T> T mayNull​(T object)
        This method is a complete dummy, simply serving as a semantical counterpart to notNull(Object).
        The use is small, but still there:
        - the sourcecode is easier to read if the same structure is used next to a notNull(Object) call instead of missing method calls and comments (like "may be null" or "optional"). - the IDE can search for all occurances of this method, listing all places where something may be null.
        Parameters:
        object - the passed reference.
        Returns:
        the passed reference without doing ANYTHING else.

      • coalesce

        public static final <T> T coalesce​(T firstElement,
                                   T secondElement)

      • coalesce

        @SafeVarargs
public static final <T> T coalesce​(T... elements)

      • equal

        public static final <T> boolean equal​(T o1,
                                      T o2)

      • unbox

        public static final byte unbox​(Byte d)

      • unbox

        public static final byte unbox​(Byte d,
                               byte nullSubstitute)

      • unbox

        public static final boolean unbox​(Boolean d)

      • unbox

        public static final boolean unbox​(Boolean d,
                                  boolean nullSubstitute)

      • unbox

        public static final short unbox​(Short d)

      • unbox

        public static final short unbox​(Short d,
                                short nullSubstitute)

      • unbox

        public static final char unbox​(Character d)

      • unbox

        public static final int unbox​(Integer d)

      • unbox

        public static final int unbox​(Integer d,
                              int nullSubstitute)

      • unbox

        public static final char unbox​(Character d,
                               char nullSubstitute)

      • unbox

        public static final float unbox​(Float d)

      • unbox

        public static final float unbox​(Float d,
                                float nullSubstitute)

      • unbox

        public static final long unbox​(Long d)

      • unbox

        public static final long unbox​(Long d,
                               long nullSubstitute)

      • unbox

        public static final double unbox​(Double d)

      • unbox

        public static final double unbox​(Double d,
                                 double nullSubstitute)

      • box

        public static final Byte[] box​(byte... bytes)

      • box

        public static final Boolean[] box​(boolean... booleans)

      • box

        public static final Short[] box​(short... shorts)

      • box

        public static final Integer[] box​(int... ints)

      • box

        public static final Character[] box​(char... chars)

      • box

        public static final Float[] box​(float... floats)

      • box

        public static final Long[] box​(long... longs)

      • box

        public static final Double[] box​(double... doubles)

      • unbox

        public static final int[] unbox​(Integer[] array)

      • unbox

        public static final int[] unbox​(Integer[] array,
                                int nullReplacement)

      • unbox

        public static final long[] unbox​(Long[] array)

      • unbox

        public static final long[] unbox​(Long[] array,
                                 long nullReplacement)

      • booleans

        public static boolean[] booleans​(boolean... elements)

      • bytes

        public static byte[] bytes​(byte... elements)

      • shorts

        public static short[] shorts​(short... elements)

      • ints

        public static int[] ints​(int... elements)

      • longs

        public static long[] longs​(long... elements)

      • floats

        public static float[] floats​(float... elements)

      • doubles

        public static double[] doubles​(double... elements)

      • chars

        public static char[] chars​(char... elements)

      • array

        @SafeVarargs
public static <T> T[] array​(T... elements)

      • objects

        public static Object[] objects​(Object... elements)

      • strings

        public static String[] strings​(String... elements)

      • times

        public static XList<Integer> times​(int n)
        Utility method to create a list of integers from 1 to the passed n value. Useful for executing a logic via XList.iterate(Consumer) exactely n times.
        Parameters:
        n -

      • range

        public static XList<Integer> range​(int firstValue,
                                   int lastValue)
        Utility method to create a list of integers from firstValue to lastValue.
        Parameters:
        firstValue -
        lastValue -

      • Singleton

        public static <E> Singleton<E> Singleton​(E element)

      • Constant

        public static <E> Constant<E> Constant​(E element)

      • Table

        public static <K,​V> HashTable<K,​V> Table​(K key,
                                                     V value)

      • Reference

        public static <T> XReference<T> Reference​(T object)

      • ArrayForElementType

        public static final <T> T[] ArrayForElementType​(T sampleInstance,
                                                int length)

      • ArrayOfSameType

        public static <E> E[] ArrayOfSameType​(E[] sampleArray,
                                      int length)

      • ArrayOfSameType

        public static final <E> E[] ArrayOfSameType​(E[] sampleArray)

      • Array

        public static <E> E[] Array​(Class<E> componentType,
                            int length)

      • Array

        public static <T,​E extends T> T[] Array​(Class<T> type,
                                              XGettingCollection<E> collection)
        Static workaround for the Java typing deficiency that it is not possible to define public <T super E> T[] toArray(Class<T> type).
        Type Parameters:
        E - the collection's element type.
        T - the component type used to create the array, possibly a super type of E
        Parameters:
        collection - the collection whose elements shall be copied to the array.
        type - the Class representing type T at runtime.
        Returns:
        a new array instance of component type T containing all elements of the passed collection.

      • Array

        public static <E> E[] Array​(Class<E> componentType,
                            int length,
                            Supplier<E> supplier)
        Instantiaties a new array instance that has a compent type defined by the passed ClasscomponentType, a length as defined by the passed length value and that is filled in order with elements supplied by the passed Supplier instance.
        Parameters:
        length - the length of the array to be created.
        componentType - the component type of the array to be created.
        supplier - the function supplying the instances that make up the array's elements.
        Returns:
        a new array instance filled with elements provided by the passed supplier.
        See Also:
        Array(Class,int,Supplier)

      • asX

        public static <E> XList<E> asX​(List<E> oldList)

      • asX

        public static <E> XSet<E> asX​(Set<E> oldSet)

      • asX

        public static <K,​V> XMap<K,​V> asX​(Map<K,​V> oldMap)

      • notEmpty

        public static final <S extends Sized> S notEmpty​(S sized)

      • notEmpty

        public static final <E> E[] notEmpty​(E[] array)

      • toKeyValue

        public static <T,​K,​V> KeyValue<K,​V> toKeyValue​(T instance,
                                                                 Function<? super T,​KeyValue<K,​V>> mapper)

      • KeyValue

        public static <K,​V> KeyValue<K,​V> KeyValue​(K key,
                                                       V value)

      • _longKeyValue

        public static _longKeyValue _longKeyValue​(long key,
                                          long value)

      • synchronize

        public static <E> XList<E> synchronize​(XList<E> list)
        Ensures that the returned XList instance based on the passed list is thread safe to use.
        This normally means wrapping the passed list in a SynchList, making it effectively synchronized.
        If the passed list already is thread safe (indicated by the marker interface ThreadSafe), then the list itself is returned without further actions. This automatically ensures that a SynchList is not redundantly wrapped again in another SynchList.
        Type Parameters:
        E - the element type.
        Parameters:
        list - the XList instance to be synchronized.
        Returns:
        a thread safe XList using the passed list.

      • synchronize

        public static <E> XSet<E> synchronize​(XSet<E> set)
        Ensures that the returned XSet instance based on the passed set is thread safe to use.
        This normally means wrapping the passed set in a SynchSet, making it effectively synchronized.
        If the passed set already is thread safe (indicated by the marker interface ThreadSafe), then the set itself is returned without further actions. This automatically ensures that a SynchSet is not redundantly wrapped again in another SynchSet.
        Type Parameters:
        E - the element type.
        Parameters:
        set - the XSet instance to be synchronized.
        Returns:
        a thread safe XSet using the passed set.

      • synchronize

        public static <E> XCollection<E> synchronize​(XCollection<E> collection)
        Ensures that the returned XCollection instance based on the passed collection is thread safe to use.
        This normally means wrapping the passed collection in a SynchCollection, making it effectively synchronized.
        If the passed collection already is thread safe (indicated by the marker interface ThreadSafe), then the collection itself is returned without further actions. This automatically ensures that a SynchCollection is not redundantly wrapped again in another SynchCollection.
        Type Parameters:
        E - the element type.
        Parameters:
        collection - the XCollection instance to be synchronized.
        Returns:
        a thread safe XCollection using the passed collection.

      • addSuppressed

        public static final <T extends Throwable> T addSuppressed​(T throwable,
                                                          Throwable suppressed)
        As usual, the JDK developers fail to create smoothly usable methods, so one has to clean up after them.
        Usage:
        throw addSuppressed(new SomethingIsWrongException(), e);

      • addSuppressed

        public static final <T extends Throwable> T addSuppressed​(T throwable,
                                                          Throwable... suppresseds)

      • on

        public static final <S> S on​(S subject,
                             Consumer<? super S> logic)
        Abbreviation for "execute on". Read as "on [subject] execute [logic]" Nifty little helper logic that allows to execute custom logic on a subject instance but still return that instance. Useful for method chaining.
        Parameters:
        subject -
        logic -

      • check

        public static void check​(BooleanTerm condition)
                  throws Error
        Forces the passed condition to evaluate to true by throwing an Error otherwise.
        Parameters:
        condition -
        Throws:
        Error - if the passed condition fails.

      • check

        public static void check​(BooleanTerm condition,
                         String message)
                  throws Error
        Forces the passed condition to evaluate to true by throwing an Error otherwise.
        Parameters:
        condition -
        message -
        Throws:
        Error - if the passed condition fails.

      • check

        public static void check​(BooleanTerm condition,
                         String message,
                         int stackLevels)
                  throws Error
        Forces the passed condition to evaluate to true by throwing an Error otherwise.
        Parameters:
        condition -
        message -
        stackLevels -
        Throws:
        Error - if the passed condition fails.