org.ObjectLayout

Class StructuredArrayBuilder<S extends StructuredArray<T>,T>

java.lang.Object

org.ObjectLayout.StructuredArrayBuilder<S,T>

Type Parameters:

S - The class of the StructuredArray that is to be instantiated by the builder

T - The class of the elements in the StructuredArray that is to be instantiated the builder

public class StructuredArrayBuilder<S extends StructuredArray<T>,T>
extends java.lang.Object

A builder used for instantiating a StructuredArray<T>

StructuredArrayBuilder follows the commonly used builder pattern, and is useful for capturing the instantiation parameters of StructuredArrays.

StructuredArrayBuilders can be created for "flat" and "nested" StructuredArray constructs, and can range from the simplest forms used when default constructors are employed, to forms that supply customized per-element construction arguments that can take construction context (such as index, containing array, and arbitrary data passed in a contextCookie) into account.

A simple example of using a StructuredArrayBuilder to instantiate a StructuredArray is:

 StructuredArray<MyElementClass> array =
      new StructuredArrayBuilder(StructuredArray.class, MyElementClass.class, length).
          build();
 

An example of passing specific (but identical) construction arguments to element constructors is:

 Constructor<MyElementClass> constructor = MyElementClass.class.getConstructor(int.Class, int.Class);

 StructuredArray<MyElementClass> array =
      new StructuredArrayBuilder(
          StructuredArray.class,
          MyElementClass.class,
          length).
          elementCtorAndArgs(constructor, initArg1, initArg2).
          build();
 

Some examples of providing per-element construction parameters that depend on construction context include:

 Constructor<MyElementClass> constructor = MyElementClass.class.getConstructor(long.Class, long.Class);

 // Using a pre-constructed elementCtorAndArgsProvider:
 StructuredArray<MyElementClass> array =
      new StructuredArrayBuilder(
          StructuredArray.class,
          MyElementClass.class,
          length).
          elementCtorAndArgsProvider(myCtorAndArgsProvider).
          build();

 // Using a Lambda expression for elementCtorAndArgsProvider:
 StructuredArray<MyElementClass> array2 =
      new StructuredArrayBuilder(
          StructuredArray.class,
          MyElementClass.class,
          length).
          elementCtorAndArgsProvider(
              context -> new CtorAndArgs<MyElementClass>(
                  constructor, context.getIndex(), context.getIndex() * 2)
          ).
          build();

 // Using an anonymous class for elementCtorAndArgsProvider:
 StructuredArray<MyElementClass> array3 =
      new StructuredArrayBuilder(
          StructuredArray.class,
          MyElementClass.class,
          length).
          elementCtorAndArgsProvider(
              new CtorAndArgsProvider() {
                   @Override
                  public CtorAndArgs getForContext(ConstructionContext context) throws NoSuchMethodException {
                      return new CtorAndArgs(constructor, context.getIndex(), context.getIndex() * 2);
                  }
              }
          ).
          build();
 

Constructor Summary

Constructors

Constructor and Description
StructuredArrayBuilder(java.lang.Class<S> arrayClass, java.lang.Class<T> elementClass, long length) Constructs a new StructuredArrayBuilder object for creating arrays of type S with elements of type T, and the given length.
StructuredArrayBuilder(java.lang.Class<S> arrayClass, PrimitiveArrayBuilder<A> subArrayBuilder, long length) Constructs a new StructuredArrayBuilder object for creating an array of type S with elements of type T, and the given length.
StructuredArrayBuilder(java.lang.Class<S> arrayClass, StructuredArrayBuilder<A,E> subArrayBuilder, long length) Constructs a new StructuredArrayBuilder object for creating an array of type S with elements of type T, and the given length.
StructuredArrayBuilder(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class<S> arrayClass, java.lang.Class<T> elementClass, long length) Constructs a new StructuredArrayBuilder object for creating arrays of type S with elements of type T, and the given length.
StructuredArrayBuilder(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class<S> arrayClass, PrimitiveArrayBuilder<A> subArrayBuilder, long length) Constructs a new StructuredArrayBuilder object for creating an array of type S with elements of type T, and the given length.
StructuredArrayBuilder(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class<S> arrayClass, StructuredArrayBuilder<A,E> subArrayBuilder, long length) Constructs a new StructuredArrayBuilder object for creating an array of type S with elements of type T, and the given length.
StructuredArrayBuilder(java.lang.invoke.MethodHandles.Lookup lookup, StructuredArrayModel<S,T> arrayModel) Constructs a new StructuredArrayBuilder object for creating arrays of the given array model.
StructuredArrayBuilder(StructuredArrayModel<S,T> arrayModel) Constructs a new StructuredArrayBuilder object for creating arrays of the given array model.

Method Summary

Modifier and Type	Method and Description
StructuredArrayBuilder<S,T>	arrayCtorAndArgs(java.lang.reflect.Constructor<S> constructor, java.lang.Object... args) Set the Constructor and construction arguments to be used in constructing arrays.
StructuredArrayBuilder<S,T>	arrayCtorAndArgs(CtorAndArgs<S> arrayCtorAndArgs) Set the CtorAndArgs to be used in constructing arrays.
S	build() Build a StructuredArray according to the information captured in this builder
StructuredArrayBuilder<S,T>	contextCookie(java.lang.Object contextCookie) Set the (opaque) contextCookie object associated with this builder.
StructuredArrayBuilder<S,T>	elementCtorAndArgs(java.lang.reflect.Constructor<T> constructor, java.lang.Object... args) Set the Constructor and construction arguments to be used for all elements in the array.
StructuredArrayBuilder<S,T>	elementCtorAndArgs(CtorAndArgs<T> ctorAndArgs) Set the CtorAndArgs to be used for all elements in the array.
StructuredArrayBuilder<S,T>	elementCtorAndArgsProvider(CtorAndArgsProvider<T> ctorAndArgsProvider) Set the CtorAndArgsProvider used for determining the constructor and construction arguments used for each element in the array.
CtorAndArgs<S>	getArrayCtorAndArgs() Get the CtorAndArgs describing the constructor and arguments used to instantiate arrays with this builder.
StructuredArrayModel<S,T>	getArrayModel() Get the StructuredArrayModel that describes the arrays built by this builder
java.lang.Object	getContextCookie() Get the (opaque) contextCookie object associated with this builder.
CtorAndArgsProvider<T>	getElementCtorAndArgsProvider() Get the CtorAndArgsProvider which provides the constructor and arguments used to construct individual elements of arrays instantiated with this builder.
PrimitiveArrayBuilder	getPrimitiveSubArrayBuilder() Get the StructuredArrayBuilder for the elements of the arrays built by this builder.
StructuredArrayBuilder	getStructuredSubArrayBuilder() Get the StructuredArrayBuilder for the elements of the arrays built by this builder.
StructuredArrayBuilder<S,T>	resolve() Resolve any not-yet-resolved constructor information needed by this builder.

Methods inherited from class java.lang.Object

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

Constructor Detail

StructuredArrayBuilder

public StructuredArrayBuilder(java.lang.Class<S> arrayClass,
                              java.lang.Class<T> elementClass,
                              long length)

Constructs a new StructuredArrayBuilder object for creating arrays of type S with elements of type T, and the given length. Note: This constructor form cannot be used with an element type T that extends StructuredArray. Use the constructor form StructuredArrayBuilder(Class, StructuredArrayBuilder, long) to create builders that instantiate nested StructuredArrays.

Parameters:

arrayClass - The class of the array to be built by this builder

elementClass - The class of elements in the array to be built by this builder

length - The length of the array to be build by this builder

StructuredArrayBuilder

public StructuredArrayBuilder(java.lang.invoke.MethodHandles.Lookup lookup,
                              java.lang.Class<S> arrayClass,
                              java.lang.Class<T> elementClass,
                              long length)

Constructs a new StructuredArrayBuilder object for creating arrays of type S with elements of type T, and the given length. Note: This constructor form cannot be used with an element type T that extends StructuredArray. Use the constructor form StructuredArrayBuilder(Class, StructuredArrayBuilder, long) to create builders that instantiate nested StructuredArrays.

Parameters:

lookup - The lookup object to use for accessing constructors when resolving this builder

arrayClass - The class of the array to be built by this builder

elementClass - The class of elements in the array to be built by this builder

length - The length of the array to be build by this builder

StructuredArrayBuilder

public StructuredArrayBuilder(StructuredArrayModel<S,T> arrayModel)

Constructs a new StructuredArrayBuilder object for creating arrays of the given array model.

Parameters:

arrayModel - The model of the array to be built by this builder

StructuredArrayBuilder

public StructuredArrayBuilder(java.lang.invoke.MethodHandles.Lookup lookup,
                              StructuredArrayModel<S,T> arrayModel)

Constructs a new StructuredArrayBuilder object for creating arrays of the given array model.

Parameters:

lookup - The lookup object to use for accessing constructors when resolving this builder

arrayModel - The model of the array to be built by this builder

StructuredArrayBuilder

public StructuredArrayBuilder(java.lang.Class<S> arrayClass,
                              StructuredArrayBuilder<A,E> subArrayBuilder,
                              long length)

Constructs a new StructuredArrayBuilder object for creating an array of type S with elements of type T, and the given length. Used when T extends StructuredArray, such that the arrays instantiated by this builder would include nested StructuredArrays.

Type Parameters:

A - The class or the subArray (should match T for the StructuredArrayBuilder)

E - The element class in the subArray.

Parameters:

arrayClass - The class of the array to be built by this builder

subArrayBuilder - The builder used for creating individual array elements (which are themselves StructuredArrays)

length - The length of the array to be build by this builder

StructuredArrayBuilder

public StructuredArrayBuilder(java.lang.invoke.MethodHandles.Lookup lookup,
                              java.lang.Class<S> arrayClass,
                              StructuredArrayBuilder<A,E> subArrayBuilder,
                              long length)

Constructs a new StructuredArrayBuilder object for creating an array of type S with elements of type T, and the given length. Used when T extends StructuredArray, such that the arrays instantiated by this builder would include nested StructuredArrays.

Type Parameters:

A - The class or the subArray (should match T for the StructuredArrayBuilder)

E - The element class in the subArray.

Parameters:

lookup - The lookup object to use for accessing constructors when resolving this builder

arrayClass - The class of the array to be built by this builder

subArrayBuilder - The builder used for creating individual array elements (which are themselves StructuredArrays)

length - The length of the array to be build by this builder

StructuredArrayBuilder

public StructuredArrayBuilder(java.lang.Class<S> arrayClass,
                              PrimitiveArrayBuilder<A> subArrayBuilder,
                              long length)

Constructs a new StructuredArrayBuilder object for creating an array of type S with elements of type T, and the given length. Used when T extends PrimitiveArray, such that the arrays instantiated by this builder would include elements that are PrimitiveArrays.

Type Parameters:

A - The class in the subArray (should match T for the StructuredArrayBuilder)

Parameters:

arrayClass - The class of the array to be built by this builder

subArrayBuilder - The builder used for creating individual array elements (which are themselves subclassable PrimitiveArrays)

length - The length of the array to be build by this builder

StructuredArrayBuilder

public StructuredArrayBuilder(java.lang.invoke.MethodHandles.Lookup lookup,
                              java.lang.Class<S> arrayClass,
                              PrimitiveArrayBuilder<A> subArrayBuilder,
                              long length)

Constructs a new StructuredArrayBuilder object for creating an array of type S with elements of type T, and the given length. Used when T extends PrimitiveArray, such that the arrays instantiated by this builder would include elements that are PrimitiveArrays.

Type Parameters:

A - The class in the subArray (should match T for the StructuredArrayBuilder)

Parameters:

lookup - The lookup object to use for accessing constructors when resolving this builder

arrayClass - The class of the array to be built by this builder

subArrayBuilder - The builder used for creating individual array elements (which are themselves subclassable PrimitiveArrays)

length - The length of the array to be build by this builder

Method Detail

elementCtorAndArgsProvider

public StructuredArrayBuilder<S,T> elementCtorAndArgsProvider(CtorAndArgsProvider<T> ctorAndArgsProvider)

Set the CtorAndArgsProvider used for determining the constructor and construction arguments used for each element in the array. The provider may use the specific element's construction context in determining the construction parameters. Note: This method overlaps in purpose with the alternate methods for controlling element construction. Namely elementCtorAndArgs(CtorAndArgs) and elementCtorAndArgs(Constructor, Object...).

Parameters:

ctorAndArgsProvider - The provider used for determining the constructor and construction arguments used for each element in instantiated arrays

Returns:

The builder

elementCtorAndArgs

public StructuredArrayBuilder<S,T> elementCtorAndArgs(CtorAndArgs<T> ctorAndArgs)

Set the CtorAndArgs to be used for all elements in the array. All elements will be constructed with the same constructor and the same arguments. Note: This method overlaps in purpose with the alternate methods for controlling element construction. Namely elementCtorAndArgsProvider(CtorAndArgsProvider) and elementCtorAndArgs(Constructor, Object...).

Parameters:

ctorAndArgs - The constructor and arguments used for all elements in arrays

Returns:

The builder

elementCtorAndArgs

public StructuredArrayBuilder<S,T> elementCtorAndArgs(java.lang.reflect.Constructor<T> constructor,
                                                      java.lang.Object... args)

Set the Constructor and construction arguments to be used for all elements in the array. All elements will be constructed with the same constructor and the same arguments. Note: This method overlaps in purpose with the alternate methods for controlling element construction. Namely elementCtorAndArgsProvider(CtorAndArgsProvider) and elementCtorAndArgs(CtorAndArgs).

Parameters:

constructor - The constructor used for all elements in arrays

args - The construction arguments supplied for the constructor, used for all elements in the array

Returns:

The builder

arrayCtorAndArgs

public StructuredArrayBuilder<S,T> arrayCtorAndArgs(CtorAndArgs<S> arrayCtorAndArgs)

Set the CtorAndArgs to be used in constructing arrays. Setting the means for array construction is Required if the array class (S) does not support a default constructor, or if a non-default construction of the array instance is needed.

Parameters:

arrayCtorAndArgs - The constructor and arguments used for constructing arrays

Returns:

The builder

arrayCtorAndArgs

public StructuredArrayBuilder<S,T> arrayCtorAndArgs(java.lang.reflect.Constructor<S> constructor,
                                                    java.lang.Object... args)

Set the Constructor and construction arguments to be used in constructing arrays. Setting the means for array construction is Required if the array class (S) does not support a default constructor, or if a non-default construction of the array instance is needed.

Parameters:

constructor - The constructor used for constructing arrays

args - The construction arguments supplied for the constructor

Returns:

The builder

contextCookie

public StructuredArrayBuilder<S,T> contextCookie(java.lang.Object contextCookie)

Set the (opaque) contextCookie object associated with this builder. This contextCookie object will be set in ConstructionContext object passed to the element CtorAndArgsProvider provider for each element in instantiated arrays.

Parameters:

contextCookie - the contextCookie object

Returns:

The builder

resolve

public StructuredArrayBuilder<S,T> resolve()

Resolve any not-yet-resolved constructor information needed by this builder. Calling resolve() is not necessary ahead of building, but it is useful for ensuring resolution works ahead of actual building attempts.

Returns:

This builder

Throws:

java.lang.IllegalArgumentException - if the array constructor or element constructor fail to resolve given the current information in the builder

build

public S build()
        throws java.lang.IllegalArgumentException

Build a StructuredArray according to the information captured in this builder

Returns:

A newly instantiated StructuredArray

Throws:

java.lang.IllegalArgumentException - if the array constructor or element constructor fail to resolve given the current information in the builder

getArrayModel

public StructuredArrayModel<S,T> getArrayModel()

Get the StructuredArrayModel that describes the arrays built by this builder

Returns:

The StructuredArrayModel that describes the arrays built by this builder

getStructuredSubArrayBuilder

public StructuredArrayBuilder getStructuredSubArrayBuilder()

Get the StructuredArrayBuilder for the elements of the arrays built by this builder. Null

Returns:

The StructuredArrayBuilder for the elements of the arrays built by this builder. Null if the array element type T does not extend StructuredArray.

getPrimitiveSubArrayBuilder

public PrimitiveArrayBuilder getPrimitiveSubArrayBuilder()

Get the StructuredArrayBuilder for the elements of the arrays built by this builder. Null

Returns:

The StructuredArrayBuilder for the elements of the arrays built by this builder. Null if the array element type T does not extend StructuredArray.

getArrayCtorAndArgs

public CtorAndArgs<S> getArrayCtorAndArgs()

Get the CtorAndArgs describing the constructor and arguments used to instantiate arrays with this builder. May be null if non of arrayCtorAndArgs, resolve() or build() have been called yet.

Returns:

The CtorAndArgs describing the constructor and arguments used to instantiate arrays with this builder.

getElementCtorAndArgsProvider

public CtorAndArgsProvider<T> getElementCtorAndArgsProvider()

Get the CtorAndArgsProvider which provides the constructor and arguments used to construct individual elements of arrays instantiated with this builder. May be null if non of elementCtorAndArgsProvider, elementCtorAndArgs(org.ObjectLayout.CtorAndArgs<T>), resolve(boolean) or build() have been called yet.

Returns:

The CtorAndArgsProvider which provides the constructor and arguments used to construct individual elements of arrays instantiated with this builder

getContextCookie

public java.lang.Object getContextCookie()

Get the (opaque) contextCookie object associated with this builder. This contextCookie object will be set in ConstructionContext object passed to the element CtorAndArgsProvider provider for each element in instantiated arrays.

Returns:

The (opaque) contextCookie object associated with this builder