Package acdp.design

Class SimpleType<T>

java.lang.Object
acdp.internal.types.Type_
acdp.design.SimpleType<T>
Type Parameters:
T - The value type of this simple type, for example Integer.
All Implemented Interfaces:
Type
public abstract class SimpleType<T> extends acdp.internal.types.Type_
The super class of all non-array custom and built-in column types with the exception of the built-in reference column type. Values of a simple column type can be used as elements of an array column type.

Users that do not implement a custom column type can ignore this class. This class must be part of the API because it appears in the signatures of the CL.ofArray(int, acdp.design.SimpleType<T>) and CL.create(acdp.design.SimpleType<T>) methods and because implementers of custom column types need to provide a concrete subclass of this class. However, even implementers of a custom column type can vastly ignore all methods declared with a public access modifier and focus on the instance methods declared with a protected access modifier. Those public methods are either returning the arguments of the constructor or are used internally by ACDP.

Implementers of a custom column type must implement the toBytes(Object) and the fromBytes(byte[], int, int) methods and may want to override the toBytes(Object, byte[], int) and the typeDescPrefix() methods. Furthermore, implementers of a custom column type must implement a public and static type factory method annotated with the SimpleType.TypeFromDesc annotation.

A simple column type has a length. If this simple column type has an inrow storage scheme then its length is identical to the maximum number n of bytes of the byte representation of any value of this simple column type. If this simple column type has an outrow storage scheme then n is equal to min(256length - 1, Integer.MAX_VALUE) where length denotes the length of this simple column type.

Other properties are explained in the description of the constructor.

Author:
Beat Hörmann

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected static final class 
    SimpleType.TypeDesc
    Provides convenient access to the individual fields of a type descriptor that is represented by a String.
    static @interface 
    SimpleType.TypeFromDesc
    A class method annotated with the TypeFromDesc annotation takes the String representation of a type descriptor and returns an instance of a subclass of SimpleType.

    Nested classes/interfaces inherited from interface acdp.types.Type

    Type.Scheme

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final int
    length
    See here.

    Fields inherited from class acdp.internal.types.Type_

    scheme

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    SimpleType(Class<T> valueType, Type.Scheme scheme, boolean nullable, int limit, boolean variable)
    The constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    final T
    convertFromBytes(byte[] bytes, int offset)
    Converts the specified byte subarray to an Object.
    final T
    convertFromBytes(byte[] bytes, int offset, int len)
    Converts len bytes of the specified byte subarray to an Object.
    final byte[]
    convertToBytes(Object val)
    Converts the specified value to a byte array.
    final int
    convertToBytes(Object val, byte[] bytes, int offset)
    Converts the specified value to a byte array and puts it into the specified byte array starting at the specified offset.
    protected abstract T
    fromBytes(byte[] bytes, int offset, int len)
    Converts the byte representation of the value contained in the specified byte subarray to an Object.
    final String
    getTypeFactoryClassName()
    Returns the name of the custom type factory class.
    final String
    getTypeFactoryClasspath()
    Returns the classpath of the custom type factory class.
    final boolean
    isCompatible(Object val)
    Tests if the specified value is compatible with this column type.
    final int
    length()
    Returns the length of this column type.
    final boolean
    nullable()
    Returns the information whether values of this column type are allowed to be null.
    final void
    setTypeFactoryClassName(acdp.internal.types.TypeFactory.Friend friend, String cn)
    Friend-only setter of the name of the custom type factory class.
    final void
    setTypeFactoryClasspath(acdp.internal.types.TypeFactory.Friend friend, String cp)
    Friend-only setter of the classpath of the custom type factory class.
    protected abstract byte[]
    toBytes(T val)
    Converts the specified value to its byte representation.
    protected int
    toBytes(T val, byte[] bytes, int offset)
    Converts the specified value to its byte representation and puts it into the specified byte array starting at the specified offset.
    final String
    typeDesc()
    Returns the type descriptor of this column type.
    protected String
    typeDescPrefix()
    Returns the first part of the descriptor of this column type.
    protected static final String
    typeDescSuffix(Type.Scheme scheme, boolean nullable, int limit, boolean variable)
    Returns the second part of the descriptor for a column type constructed with the specified arguments.
    final Class<T>
    valueType()
    Returns the value type of this column type.
    final boolean
    variable()
    Returns the information whether the length of the byte representation of a value of this column type, which is supposed to have an inrow storage scheme, may vary from value to value.

    Methods inherited from class acdp.internal.types.Type_

    isBuiltInType, scheme

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • length

      protected final int length
      See here.

  • Constructor Details

    • SimpleType

      protected SimpleType(Class<T> valueType, Type.Scheme scheme, boolean nullable, int limit, boolean variable) throws NullPointerException, IllegalArgumentException
      The constructor.
      Parameters:
      valueType - The object representing the value type of this column type, not allowed to be null.
      scheme - The storage scheme of this column type, not allowed to be null.
      nullable - The information whether this column type allows the null value (true) or not (false). Typically, values of column types forbidding the null value can be persisted more efficiently than values of column types allowing the null value.
      limit - The limit is directly related to the length of this column type. This value must be greater than or equal to 1 and if scheme is equal to Scheme.OUTROW then it must be less than or equal to 4.
      variable - The information whether the length of the byte representation of a value of this column type may vary from value to value (true) or if the length is fixed (false). This value is ignored if scheme is equal to Scheme.OUTROW.
      Throws:
      NullPointerException - If scheme or valueType is null.
      IllegalArgumentException - If limit is less than 1 or, provided that scheme is equal to Scheme.OUTROW, limit is greater than 4. Furthermore, this exception is thrown if scheme is equal to Scheme.INROW and variable is equal to true and limit is greater than Integer.MAX_VALUE - 4.

  • Method Details

    • typeDescSuffix

      protected static final String typeDescSuffix(Type.Scheme scheme, boolean nullable, int limit, boolean variable)
      Returns the second part of the descriptor for a column type constructed with the specified arguments.

      This method is hardly ever used by type implementers.

      Parameters:
      scheme - The storage scheme of the column type, not allowed to be null.
      nullable - The information whether the column type allows the null value (true) or not (false).
      limit - The limit of the column type. This value must be greater than or equal to 1 and if scheme is equal to Scheme.OUTROW then it must be less than or equal to 4.
      variable - The information whether the length of the byte representation of a value of the column type may vary from value to value (true) or if the length is fixed (false). This value is ignored if scheme is equal to Scheme.OUTROW.
      Returns:
      The suffix of the type descriptor, never null and never an empty string.

    • setTypeFactoryClassName

      public final void setTypeFactoryClassName(acdp.internal.types.TypeFactory.Friend friend, String cn) throws NullPointerException
      Friend-only setter of the name of the custom type factory class. (Since the friend resides in a different package, this method has to be public.)
      Parameters:
      friend - The friend, not allowed to be null.
      cn - The name of the custom type factory class.
      Throws:
      NullPointerException - If friend is null.

    • getTypeFactoryClassName

      public final String getTypeFactoryClassName()
      Returns the name of the custom type factory class.
      Returns:
      The name of the custom type factory class. This value is null if and only if this column type is a built-in column type.

    • setTypeFactoryClasspath

      public final void setTypeFactoryClasspath(acdp.internal.types.TypeFactory.Friend friend, String cp) throws NullPointerException
      Friend-only setter of the classpath of the custom type factory class. (Since the friend resides in a different package, this method has to be public.)
      Parameters:
      friend - The friend, not allowed to be null.
      cp - The classpath of the custom type factory.
      Throws:
      NullPointerException - If friend is null.

    • getTypeFactoryClasspath

      public final String getTypeFactoryClasspath()
      Returns the classpath of the custom type factory class.
      Returns:
      The classpath of the custom type factory class, may be null.

    • typeDescPrefix

      protected String typeDescPrefix()
      Returns the first part of the descriptor of this column type.

      Implementers can override this implementation to return a prefix with a smaller length or to handle prefixes that encode custom specific information.

      Note that the returned value must start with an upper case letter so that ACDP can easily distinguish between the type descriptor of a built-in column type (which starts with a lower case letter) and a type descriptor of a custom column type.

      Returns:
      The prefix of the type descriptor, never null and never an empty string.

    • typeDesc

      public final String typeDesc()
      Description copied from interface: Type
      Returns the type descriptor of this column type.

      The type descriptor uniquely identifies a particular column type among all other column types. It is used by a type factory to create an instance of that column type.

      If the type descriptor starts with an upper case character then this column type is a custom column type otherwise it is a built-in column type. (A custom column type is provided by a client whereas a built-in column type is provided by ACDP.)

      Implementers of this method must ensure that the value returned by this method is indeed unique and that it remains consistent even across session boundaries.

      Returns:
      The column type descriptor, never null.

    • valueType

      public final Class<T> valueType()
      Returns the value type of this column type.

      The value type is used, for example, when an arbitrary value of type Object is tested for compatibility with this column type.

      Returns:
      The value type of this column type, never null.

    • nullable

      public final boolean nullable()
      Returns the information whether values of this column type are allowed to be null.
      Returns:
      The boolean value true if values of this column type are allowed to be null, false otherwise.

    • length

      public final int length()
      Returns the length of this column type. The length is equal to the limit argument of the constructor unless this column type has an inrow storage scheme and the variable argument of the constructor is equal to true. In such a case the length is equal to limit + ⌊log256(limit)⌋ + 1.
      Returns:
      The length of this column type, always greater than or equal to 1 and if the storage scheme is an outrow storage scheme then this value is less than or equal to 4.

    • variable

      public final boolean variable()
      Returns the information whether the length of the byte representation of a value of this column type, which is supposed to have an inrow storage scheme, may vary from value to value.
      Returns:
      The boolean value true if and only if this column type has an inrow storage scheme and if the variable argument passed to the constructor was set to true.

    • isCompatible

      public final boolean isCompatible(Object val)
      Tests if the specified value is compatible with this column type. In accordance with the general definition of compatibility the specified value is compatible with this column type if and only if
      • The value is null and the nullable method returns true or
      • The value is not null but the value is assignment-compatible with the value type of this column type.
      Parameters:
      val - The value to test for compatibility.
      Returns:
      The boolean value true if the value is compatible with this column type, false otherwise.

    • toBytes

      protected abstract byte[] toBytes(T val) throws NullPointerException
      Converts the specified value to its byte representation.

      This method assumes that calling the isCompatible(java.lang.Object) method on val returns true. If this is not the case then this method may throw an exception not mentioned below.

      The returned length of the byte representation must be less than or equal to the value returned by the length() method. Implementers of this method should not check if this condition is met because it is internally checked anyway.

      Parameters:
      val - The value to convert, not allowed to be null.
      Returns:
      The byte representation of the value, never null.
      Throws:
      NullPointerException - If val is null.

    • convertToBytes

      public final byte[] convertToBytes(Object val) throws NullPointerException, IllegalArgumentException
      Converts the specified value to a byte array.

      This method assumes that calling the isCompatible method on val returns true. If this is not the case then this method may throw an exception that is not mentioned below.

      This method should be invoked only if this column type has an outrow storage scheme.

      Parameters:
      val - The value to convert, not allowed to be null.
      Returns:
      The value as a byte array, never null.
      Throws:
      NullPointerException - If val is null.
      IllegalArgumentException - If the length of the byte representation of the specified value exceeds the maximum number of bytes allowed by this column type.

    • toBytes

      protected int toBytes(T val, byte[] bytes, int offset) throws NullPointerException, IndexOutOfBoundsException
      Converts the specified value to its byte representation and puts it into the specified byte array starting at the specified offset.

      This method assumes that calling the isCompatible(java.lang.Object) method on val returns true. If this is not the case then this method may throw an exception not mentioned below.

      The returned length of the byte representation must be less than or equal to the value returned by the length() method. Implementers of this method should not check if this condition is met because it is internally checked anyway.

      Type implementers are encouraged to override this method if they can avoid a call to the System.arraycopy method.

      Parameters:
      val - The value to convert, not allowed to be null.
      bytes - The destination byte array, not allowed to be null.
      offset - The index within bytes where to start saving the byte representation.
      Returns:
      The length of the byte representation.
      Throws:
      NullPointerException - If val or bytes are null.
      IndexOutOfBoundsException - If saving the byte representation would cause access of data outside of the array bounds of the specified byte array.

    • convertToBytes

      public final int convertToBytes(Object val, byte[] bytes, int offset) throws NullPointerException, IllegalArgumentException, IndexOutOfBoundsException
      Converts the specified value to a byte array and puts it into the specified byte array starting at the specified offset.

      This method assumes that calling the isCompatible method on val returns true. If this is not the case then this method may throw an exception that is not mentioned below.

      This method should be invoked only if this column type has an inrow storage scheme.

      Parameters:
      val - The value to convert, not allowed to be null.
      bytes - The destination byte array, not allowed to be null.
      offset - The index within bytes where to start saving the the converted value.
      Returns:
      The length of the byte representation.
      Throws:
      NullPointerException - If val or bytes is null.
      IllegalArgumentException - If the length of the byte representation of the specified value exceeds the maximum number of bytes allowed by this column type.
      IndexOutOfBoundsException - If saving the byte representation would cause access of data outside of the array bounds of the specified byte array.

    • fromBytes

      protected abstract T fromBytes(byte[] bytes, int offset, int len) throws IndexOutOfBoundsException
      Converts the byte representation of the value contained in the specified byte subarray to an Object.
      Parameters:
      bytes - The byte array containing the byte representation of the value, not allowed to be null.
      offset - The index within bytes of the first byte to convert, must be greater than or equal to zero.
      len - The number of bytes to convert.
      Returns:
      The resulting object.
      Throws:
      IndexOutOfBoundsException - If converting the byte representation would cause access of data outside of the array bounds of the specified byte array.

    • convertFromBytes

      public final T convertFromBytes(byte[] bytes, int offset) throws IndexOutOfBoundsException
      Converts the specified byte subarray to an Object.

      This method should be invoked only if this column type has an inrow storage scheme.

      Parameters:
      bytes - The byte array containing the byte representation of the value, not allowed to be null.
      offset - The index within bytes of the first byte to convert, must be greater than or equal to zero.
      Returns:
      The resulting object.
      Throws:
      IndexOutOfBoundsException - If converting the byte representation would cause access of data outside of the array bounds of the specified byte array.

    • convertFromBytes

      public final T convertFromBytes(byte[] bytes, int offset, int len) throws IndexOutOfBoundsException
      Converts len bytes of the specified byte subarray to an Object.

      This method should be invoked only if this column type has an outrow storage scheme.

      Parameters:
      bytes - The byte array containing the byte representation of the value, not allowed to be null.
      offset - The index within bytes of the first byte to convert, must be greater than or equal to zero.
      len - The number of bytes to convert.
      Returns:
      The resulting object.
      Throws:
      IndexOutOfBoundsException - If converting the byte representation would cause access of data outside of the array bounds of the specified byte array.