Module aeonics.core

Package aeonics.entity

Class Entity

java.lang.Object

aeonics.entity.Entity

All Implemented Interfaces:

Exportable, Snapshotable

Direct Known Subclasses:

Action.Type, Database.Type, Destination.Type, Endpoint.Type, Filter.Type, Flow.Type, Group.Type, Manager.Type, Origin.Type, Policy.Type, Probe.Type, Provider.Type, Queue.Type, Role.Type, Rule.Type, Scheduler.Cron.Type, Storage.Type, Topic.Type, User.Type

public class Entity
extends java.lang.Object
implements Exportable, Snapshotable

An Entity is the basic building block that composes the system. It is the definition of a class that can be instanciated at runtime from a Template.

An entity has a category() which allows to group entities together. It also has a type() which is the intended item type regardless of the actual implementation. There should not be more than one class definition for each category-type couple.

Most of the time, the entity category will be enforced using a final override. The type will less likely be enforced to allow subclasses to extend an existing type.

Constructor Summary

Constructors

Constructor	Description
Entity()	Default constructor that checks if the entity has been created using a Template.

Method Summary

Modifier and Type	Method	Description
Entity	addRelation(java.lang.String relationship, Entity entity)	Adds a relation to the provided entity
Entity	addRelation(java.lang.String relationship, Entity entity, Data parameters)	Adds a relation to the provided entity
Entity	addRelation(java.lang.String relationship, java.lang.String entity)	Adds a relation to the provided entity
<T extends Entity> T	cast()	Performs an unsafe cast to the specified subtype.
java.lang.String	category()	Returns the category of this entity.
void	clearRelation(java.lang.String relationship)	Clears all related entities for the specified relationship
void	config(java.lang.String key, Data value)	This method is a callback function that will be called by the Config manager when the configured value changes.
void	defineRelation(Relationship value)	Defines a new relationship for this entity.
boolean	equals(java.lang.Object other)	Checks if two entities are equal.
Data	export()	The default entity export implementation includes informational metadata fields as well as all declared parameters() and all declared relationships().
<R extends Entity> R	firstRelation(java.lang.String name)	Fetches the first relation entity.
int	hashCode()
boolean	hasRelation(java.lang.String relationship, Entity entity)	Returns whether or not this entity is related to the specified one
java.lang.String	id()	Returns the unique entity id.
boolean	internal()	Returns whether or not this entity is considered internal to the system.
java.lang.String	name()	Returns this entity name
<T extends Entity> T	name(java.lang.String value)	Sets this entity name.
Callback<Data,Entity>	onCreate()	Event callback called when the entity has been created by the template.
Callback<java.lang.Void,Entity>	onRemove()	Event callback called when the entity is removed from the registry.
Callback<Data,Entity>	onUpdate()	Event callback called when the entity has been updated by the template.
<T extends Entity> T	parameter(java.lang.String parameter, java.lang.Object value)	Sets the value of the specified parameter.
<R extends Entity> java.lang.Iterable<Tuples.Tuple<R,Data>>	relations(java.lang.String name)	Fetches all related entities from the registry along with the relation properties.
java.util.Set<java.lang.String>	relationships()	Returns the list of relationships of this entity instance.
void	removeRelation(java.lang.String relationship, Entity entity)	Removes a relation with the specified entity
Data	snapshot()	The default entity snapshot implementation includes the required metadata fields to be used by the Template to restore it.
java.lang.String	type()	Returns the type of this entity.
Data	valueOf(java.lang.String parameter)	Returns the value of the specified parameter without any contextual information.
Data	valueOf(java.lang.String parameter, Data context)	Returns the value of the specified parameter with the specified contextual information.

Methods inherited from class java.lang.Object

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

Constructor Detail

Entity

public Entity()

Default constructor that checks if the entity has been created using a Template.

Throws:

java.lang.IllegalCallerException - if the constructor has not been called through a Template

Method Detail

cast

public <T extends Entity> T cast()

Performs an unsafe cast to the specified subtype.

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

 new Item().template().create() // <-- returns a generic Entity
     .<MySubclass>cast() // <-- unsafe cast
     .foo();
 

Type Parameters:

T - the return type

Returns:

this

id

public java.lang.String id()

Returns the unique entity id. The id is initialized when the entity is created.

Returns:

the entity id

category

public java.lang.String category()

Returns the category of this entity. This property should be the StringUtils.toLowerCase(Class) of the entity's category type. It is used to register instances in the proper registry category. The category should always be lower case.

Returns:

the entity category

See Also:

Registry.of(String)

type

public java.lang.String type()

Returns the type of this entity. This property should be the StringUtils.toLowerCase(Class) of the entity's supertype. It is used by the snapshot system to find the proper factory to build instances of this class. The type should always be lower case.

Returns:

the entity category

See Also:

Factory.get(Class)

internal

public boolean internal()

Returns whether or not this entity is considered internal to the system. Internal entities are not serialized in case of a snapshot.

Returns:

whether or not this entity is internal

name

public java.lang.String name()

Returns this entity name

Returns:

this entity name

name

public <T extends Entity> T name(java.lang.String value)

Sets this entity name.

Type Parameters:

T - this

Parameters:

value - this entity name

Returns:

this

equals

public boolean equals(java.lang.Object other)

Checks if two entities are equal.

Entities are considered equal if their category and id() match.

Overrides:

equals in class java.lang.Object

Parameters:

other - the entity to compare

Returns:

true if the entities are equal

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

valueOf

public Data valueOf(java.lang.String parameter)

Returns the value of the specified parameter without any contextual information.

Parameters:

parameter - the parameter name

Returns:

the parameter value or an empty data if the parameter value is not set or the parameter does not exist for this entity.

valueOf

public Data valueOf(java.lang.String parameter,
                    Data context)

Returns the value of the specified parameter with the specified contextual information.

Parameters:

parameter - the parameter name

context - the context used for binding

Returns:

the parameter value or an empty data if the parameter value is not set or the parameter does not exist for this entity.

parameter

public <T extends Entity> T parameter(java.lang.String parameter,
                                      java.lang.Object value)

Sets the value of the specified parameter.

Caution: using this method manually will bypass the Template.update(Data, Entity) and will ignore the potential onUpdate handlers.

Type Parameters:

T - this entity type

Parameters:

parameter - the parameter name

value - the new value

Returns:

this

Throws:

java.lang.IllegalArgumentException - if the provided value does not pass parameter validation

See Also:

Parameter.validate(Data)

relationships

public java.util.Set<java.lang.String> relationships()

Returns the list of relationships of this entity instance.

Returns:

the list of relationships

defineRelation

public void defineRelation(Relationship value)

Defines a new relationship for this entity.

Parameters:

value - the relationship

Throws:

java.lang.IllegalArgumentException - if the relationship already exists

relations

public <R extends Entity> java.lang.Iterable<Tuples.Tuple<R,Data>> relations(java.lang.String name)

Fetches all related entities from the registry along with the relation properties. The returned iteratory may include null entity component.

Type Parameters:

R - The related entity type

Parameters:

name - the name of the relationship

Returns:

an iterable list of all related entities and the relation properties

firstRelation

public <R extends Entity> R firstRelation(java.lang.String name)

Fetches the first relation entity.

Type Parameters:

R - The related entity type

Parameters:

name - the name of the relationship

Returns:

the first entity found for that relation, or null if none are found

addRelation

public Entity addRelation(java.lang.String relationship,
                          Entity entity)

Adds a relation to the provided entity

Parameters:

relationship - the relationship name

entity - the related entity

Returns:

this for chaining

Throws:

java.lang.IllegalArgumentException - if the relationship does not exist, or the provided entity does not match the relation type, or the relationship requires some parameters

java.lang.RuntimeException - if the maximum number of relations is reached

addRelation

public Entity addRelation(java.lang.String relationship,
                          java.lang.String entity)

Adds a relation to the provided entity

Parameters:

relationship - the relationship name

entity - the related entity name or id

Returns:

this for chaining

Throws:

java.lang.IllegalArgumentException - if the relationship does not exist, or the provided entity does not match the relation type, or the relationship requires some parameters

java.lang.RuntimeException - if the maximum number of relations is reached

addRelation

public Entity addRelation(java.lang.String relationship,
                          Entity entity,
                          Data parameters)

Adds a relation to the provided entity

Parameters:

relationship - the relationship name

entity - the related entity

parameters - the relationship parameters as a data object

Returns:

this for chaining

Throws:

java.lang.IllegalArgumentException - if the relationship does not exist, or the provided entity does not match the relation type, or the parameters do not pass validation

java.lang.RuntimeException - if the maximum number of relations is reached

hasRelation

public boolean hasRelation(java.lang.String relationship,
                           Entity entity)

Returns whether or not this entity is related to the specified one

Parameters:

relationship - the relationship name

entity - the related entity

Returns:

true if this entity is related to the target one, false otherwise

Throws:

java.lang.IllegalArgumentException - if the relationship does not exist

java.lang.RuntimeException - if the minimum number of relations is reached

removeRelation

public void removeRelation(java.lang.String relationship,
                           Entity entity)

Removes a relation with the specified entity

Parameters:

relationship - the relationship name

entity - the related entity

Throws:

java.lang.IllegalArgumentException - if the relationship does not exist

java.lang.RuntimeException - if the minimum number of relations is reached

clearRelation

public void clearRelation(java.lang.String relationship)

Clears all related entities for the specified relationship

Parameters:

relationship - the relationship name

config

public void config(java.lang.String key,
                   Data value)

This method is a callback function that will be called by the Config manager when the configured value changes. The registration is usually performed by the Template that creates new instance of entities, but it can also be done manually using the Config.watch(String, aeonics.entity.security.Functions.BiConsumer) method. The default implementation of this method does nothing and shall be overridden to add support for dynamic changes.

Parameters:

key - the config key

value - the new value

onRemove

public Callback<java.lang.Void,Entity> onRemove()

Event callback called when the entity is removed from the registry. This is supposed to happen only once. You should Callback.then(aeonics.util.Functions.BiConsumer) this event handler to subscribe to events.

Returns:

the onRemove event handler

onUpdate

public Callback<Data,Entity> onUpdate()

Event callback called when the entity has been updated by the template. You should Callback.then(aeonics.util.Functions.BiConsumer) this event handler to subscribe to events.

Returns:

the onUpdate event handler

onCreate

public Callback<Data,Entity> onCreate()

Event callback called when the entity has been created by the template. This is supposed to happen only once. You should Callback.then(aeonics.util.Functions.BiConsumer) this event handler to subscribe to events.

Returns:

the onCreate event handler

export

public Data export()

The default entity export implementation includes informational metadata fields as well as all declared parameters() and all declared relationships().

If there are potentially private or confidential data returned by the default implementation, you should override it and modify the result before returning it.

Note that you may provide your own custom implementation although it may introduce inconsistencies with the frontent application in case of unexpected format or missing information. Therefore, it is always prefeable to call super.export() and manipulate the result instead.

Specified by:

export in interface Exportable

Returns:

a public data representation of this class instance

snapshot

public Data snapshot()

The default entity snapshot implementation includes the required metadata fields to be used by the Template to restore it. It also includes all declared parameters() and all declared relationships().

If this behavior is sufficient, you do not need to override this method. If there is additionnal data to be included in (or removed from) the output, then you should override this method, call the super.snapshot() and work on the returned data.

You may provide your own custom implementation although it may introduce inconsistencies with the rest of the system.

In order to safeguard the potentially private or confidential data returned by this method out of necessity, a check on the caller is performed to allow only the current Snapshot implementation.

Specified by:

snapshot in interface Snapshotable

Returns:

a snapshot data representation of this class instance