Module aeonics.core

Package aeonics.template

Class Template<T extends Entity>

java.lang.Object

aeonics.template.Template<T>

Type Parameters:

T - the entity type

All Implemented Interfaces:

Documented, Exportable

Direct Known Subclasses:

Action.Template, Destination.Template, Endpoint.Template, Origin.Template

public class Template<T extends Entity>
extends java.lang.Object
implements Documented

A Template is used to document and create an Entity from user input. It contains the definition of the expected initialization parameters and other entity-related information.

You must provide a creator(Supplier) to provide new instances.

See Also:

Parameter, Relationship

Constructor Summary

Constructors

Constructor	Description
Template(java.lang.Class<? extends T> target, java.lang.Class<? extends Item<? super T>> type, java.lang.Class<? extends Item<? super T>> category)	Creates a new template for the specified target entity in the specified category.

Method Summary

Modifier and Type	Method	Description
<U extends Template<T>> U	add(Parameter parameter)	Adds a parameter that the target entity expects.
<U extends Template<T>> U	add(Relationship relationship)	Adds a relationship for the target entity
<X extends Template<?>> X	cast()	Performs an unsafe cast to the specified subtype.
java.lang.String	category()	Returns the target entity category The entity category is always lower case.
<U extends Template<T>> U	category(java.lang.Class<? extends Item<? super T>> value)	Sets the target entity category The entity category is always lower case.
<U extends Template<T>> U	category(java.lang.String value)	Sets the target entity category The entity category is always lower case.
<U extends Template<T>> U	config(Parameter config)	Creates and registers the specified configuration parameter.
<U extends Template<T>> U	config(java.lang.Class<?> type, Parameter config)	Creates and registers the specified configuration parameter.
<U extends Template<T>> U	config(java.lang.Class<?> type, java.lang.String name)	Registers the specified existing configuration parameter.
<U extends Template<T>> U	config(java.lang.String name)	Registers the specified existing configuration parameter.
<U extends Template<T>> U	config(java.lang.String type, java.lang.String name)	Registers the specified existing configuration parameter.
T	create()	Creates a new entity instance and sets the basic properties and relationships.
T	create(Data data)	Creates a new entity instance and sets the basic properties and relationships.
<U extends Template<T>> U	creator(java.util.function.Supplier<? extends T> creator)	Sets the custom instance creator that provides new instance of the target entity.
java.lang.String	description()	Returns the target entity description
<U extends Template<T>> U	description(java.lang.String value)	Sets the target entity description
boolean	enforceParameterValidation()	Returns whether or not parameter validation is enforced
<U extends Template<T>> U	enforceParameterValidation(boolean value)	Sets whether or not parameter validation is enforced
Data	export()	Renders this class instance to a simple data structure for rendering client-side.
java.lang.String	name()	Returns the target entity name which is the StringUtils.toLowerCase(Class) of the target class.
<U extends Template<T>> U	onCreate(Functions.BiConsumer<Data,T> handler)	Sets a generic callback handler that will be called for every instance created by this template.
<U extends Template<T>> U	onUpdate(Functions.BiConsumer<Data,T> handler)	Sets a generic callback handler that will be called for every instance updated by this template.
<U extends Template<T>> U	removeParameter(java.lang.String parameter)	Removes a parameter that the target entity expects.
<U extends Template<T>> U	removeRelationship(java.lang.String relationship)	Removes a relationship for the target entity
java.lang.String	summary()	Returns the target entity summary
<U extends Template<T>> U	summary(java.lang.String value)	Sets the target entity summary
java.lang.Class<? extends T>	target()	Returns the target entity implementation
<U extends Template<T>> U	target(java.lang.Class<? extends T> value)	Sets the target entity implementation
java.lang.Class<? extends Item<? super T>>	type()	Returns the target entity type The entity type is always lower case.
<U extends Template<T>> U	type(java.lang.Class<? extends Item<? super T>> value)	Sets the target entity type The entity type is always lower case.
T	update(Data data, T instance)	Updates an existing entity given new parameters.

Methods inherited from class java.lang.Object

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

Constructor Detail

Template

public Template(java.lang.Class<? extends T> target,
                java.lang.Class<? extends Item<? super T>> type,
                java.lang.Class<? extends Item<? super T>> category)

Creates a new template for the specified target entity in the specified category. A default Parameter `name` is automatically added.

You should only use this constructor if the target is a substitute for the specified type.

Parameters:

target - the target entity type. It is the entity instance to create. It must match the creator(Supplier) and be the same as (or a sybtype of) the type parameter.

type - the entity supertype. It is the desired entity type as registered in the Factory. See Factory.get(String).

category - the entity category. It is the entity category as registered in the Factory and Registry. See Factory.of(String) and Registry.of(String).

Method Detail

cast

public <X extends Template<?>> X cast()

Performs an unsafe cast to the specified subtype.

This method is useful when using the chained method flow with templates:

 new Item().template() // <-- returns a generic Template
     .<SubTemplate>cast() // <-- unsafe cast
     .foo();
 

Type Parameters:

X - the return type

Returns:

this

creator

public <U extends Template<T>> U creator(java.util.function.Supplier<? extends T> creator)

Sets the custom instance creator that provides new instance of the target entity. The returned objects must be instances of the target() entity type.

This method should not attempt to initialize the instance, if specific initialization is required, you should provide a onCreate(BiConsumer) and a onUpdate(BiConsumer) to account for parameters provided by the user.

Type Parameters:

U - the template type

Parameters:

creator - the custom initializer

Returns:

this

add

public <U extends Template<T>> U add(Parameter parameter)

Adds a parameter that the target entity expects.

Type Parameters:

U - the template type

Parameters:

parameter - the parameter definition

Returns:

this

removeParameter

public <U extends Template<T>> U removeParameter(java.lang.String parameter)

Removes a parameter that the target entity expects.

Type Parameters:

U - the template type

Parameters:

parameter - the parameter name

Returns:

this

config

public <U extends Template<T>> U config(Parameter config)

Creates and registers the specified configuration parameter.

The configuration parameter registration will be bound to the type() of the target entity.

Type Parameters:

U - the template type

Parameters:

config - the parameter definition

Returns:

this

config

public <U extends Template<T>> U config(java.lang.Class<?> type,
                                        Parameter config)

Creates and registers the specified configuration parameter.

The configuration parameter registration will be bound to the specified type regardless of the target entity type.

Type Parameters:

U - the template type

Parameters:

type - the parameter category

config - the parameter definition

Returns:

this

config

public <U extends Template<T>> U config(java.lang.Class<?> type,
                                        java.lang.String name)

Registers the specified existing configuration parameter.

Type Parameters:

U - the template type

Parameters:

type - the parameter category

name - the parameter name

Returns:

this

config

public <U extends Template<T>> U config(java.lang.String type,
                                        java.lang.String name)

Registers the specified existing configuration parameter.

Type Parameters:

U - the template type

Parameters:

type - the parameter category

name - the parameter name

Returns:

this

config

public <U extends Template<T>> U config(java.lang.String name)

Registers the specified existing configuration parameter.

Type Parameters:

U - the template type

Parameters:

name - the parameter name

Returns:

this

add

public <U extends Template<T>> U add(Relationship relationship)

Adds a relationship for the target entity

Type Parameters:

U - the template type

Parameters:

relationship - the relationship definition

Returns:

this

removeRelationship

public <U extends Template<T>> U removeRelationship(java.lang.String relationship)

Removes a relationship for the target entity

Type Parameters:

U - the template type

Parameters:

relationship - the relationship name

Returns:

this

target

public java.lang.Class<? extends T> target()

Returns the target entity implementation

Returns:

the target entity implementation

target

public <U extends Template<T>> U target(java.lang.Class<? extends T> value)

Sets the target entity implementation

Type Parameters:

U - the template type

Parameters:

value - the target entity implementation

Returns:

this

category

public java.lang.String category()

Returns the target entity category The entity category is always lower case.

Returns:

the target entity category

category

public <U extends Template<T>> U category(java.lang.String value)

Sets the target entity category The entity category is always lower case.

Type Parameters:

U - the template type

Parameters:

value - the target entity category

Returns:

this

category

public <U extends Template<T>> U category(java.lang.Class<? extends Item<? super T>> value)

Sets the target entity category The entity category is always lower case.

Type Parameters:

U - the template type

Parameters:

value - the target entity category

Returns:

this

type

public java.lang.Class<? extends Item<? super T>> type()

Returns the target entity type The entity type is always lower case.

Returns:

the target entity type

type

public <U extends Template<T>> U type(java.lang.Class<? extends Item<? super T>> value)

Sets the target entity type The entity type is always lower case.

Type Parameters:

U - the template type

Parameters:

value - the target entity type

Returns:

this

name

public java.lang.String name()

Returns the target entity name which is the StringUtils.toLowerCase(Class) of the target class.

Specified by:

name in interface Documented

Returns:

the target entity name

See Also:

target()

summary

public java.lang.String summary()

Returns the target entity summary

Specified by:

summary in interface Documented

Returns:

the target entity summary

summary

public <U extends Template<T>> U summary(java.lang.String value)

Sets the target entity summary

Type Parameters:

U - the template type

Parameters:

value - the summary

Returns:

this

description

public java.lang.String description()

Returns the target entity description

Specified by:

description in interface Documented

Returns:

the target entity description

description

public <U extends Template<T>> U description(java.lang.String value)

Sets the target entity description

Type Parameters:

U - the template type

Parameters:

value - the description

Returns:

this

enforceParameterValidation

public boolean enforceParameterValidation()

Returns whether or not parameter validation is enforced

Returns:

whether or not parameter validation is enforced

enforceParameterValidation

public <U extends Template<T>> U enforceParameterValidation(boolean value)

Sets whether or not parameter validation is enforced

Type Parameters:

U - the template type

Parameters:

value - whether or not parameter validation is enforced

Returns:

this

onCreate

public <U extends Template<T>> U onCreate(Functions.BiConsumer<Data,T> handler)

Sets a generic callback handler that will be called for every instance created by this template.

Type Parameters:

U - the template type

Parameters:

handler - the generic handler

Returns:

this

create

public T create()

Creates a new entity instance and sets the basic properties and relationships. If a custom builder is set, it is then called.

Returns:

an instance of the target entity

Throws:

java.lang.RuntimeException - if an error happens during initialization

create

public T create(Data data)

Creates a new entity instance and sets the basic properties and relationships. If a custom builder is set, it is then called.

Parameters:

data - the user input data

Returns:

an instance of the target entity

Throws:

java.lang.RuntimeException - if an error happens during initialization

onUpdate

public <U extends Template<T>> U onUpdate(Functions.BiConsumer<Data,T> handler)

Sets a generic callback handler that will be called for every instance updated by this template.

Type Parameters:

U - the template type

Parameters:

handler - the generic handler

Returns:

this

update

public T update(Data data,
                T instance)

Updates an existing entity given new parameters. By default, all parameter values and relationships are updated. Although, the entity might need to be notified about the change if necessary. If a custom modifier is set, it is called after updating the parameters and relationships. If the entity cannot be updated, override this method and throw an exception instead.

Parameters:

data - the new user input data

instance - the existing instance to modify

Returns:

the modified instance

Throws:

java.lang.RuntimeException - if an error happens during the update

export

public Data export()

Description copied from interface: Exportable

Renders this class instance to a simple data structure for rendering client-side.

Specified by:

export in interface Documented

Specified by:

export in interface Exportable

Returns:

a public data representation of this class instance