Module aeonics.core
Package aeonics.template

Class Item<T extends Entity>

  • Type Parameters:
    T - the supertype of entity this Item extends
    Direct Known Subclasses:
    Action, Database, Destination, Endpoint, Filter, Group, Manager, Origin, Policy, Probe, Provider, Queue, Role, Rule, Scheduler.Cron, Storage, Topic, User
    public abstract class Item<T extends Entity>
extends java.lang.Object
    Represents a cohesive unit combining an Entity and its associated Template.

    The Item interface acts as a blueprint for defining entities and their creation templates. It encapsulates the relationship and context between an entity and its builder, ensuring a structured and consistent approach to entity creation.

    Implementing this interface typically involves defining static inner classes for both the entity and its template. These inner classes should be either public, for allowing external access and subclassing, or private, to encapsulate the entity's construction within the Item itself. This structure promotes a clean separation between the entity's definition and its construction logic, while also providing flexibility in how entities and their templates are extended and used.

    Best Practices:

    • Implement the entity and template as static inner classes within the implementing class of Item.
    • Use public inner classes when you intend to allow subclassing.
    • Use private inner classes to restrict subclassing.
    • The template returned by template() should create entities of the type returned by target().

    Example:

     public class MyItem extends Item<MyEntity> {
     public static class MyEntity extends Entity { }
     
     protected Class<? extends MyEntity> defaultTarget() { return MyEntity.class; }
     protected Supplier<? extends MyEntity> defaultCreator() { return MyEntity::new; }
     protected Class<? extends MyItem> category() { return MyItem.class; }
 }

    Normally, the template should be immutable and should only be called once when registering in the Factory. Although, it allows also to provide a partial template that should be complemented by subclasses if need be.

    Example with a final template:

     private static Template<MyEntity> template = new Template<MyEntity>();
 public Template<MyEntity> template() { return template; }
    In this case, the template is constructed only once.

    Example with a partial template:

     public Template<MyEntity> template() { return new MyTemplate(); }
    In this case, a new instance of the template is provided every time, this allows subclasses to complement it as such: 
     public Template<MyEntity> template() { return super.template().summary("This is the sub-template"); }

    The static method from(Class, Class, Supplier) allows to declare an Item with a default template based on the entity class. This is a way to provide an Item from within an Entity definition (reversed pattern).

     public class MyEntity extends Entity {
     public static Item<MyEntity> item() {
         return Item.from(MyItemCategory.class, MyEntity.class, MyEntity::new);
     }
 }

    • Constructor Summary

      Constructors 
      Constructor Description
      Item()  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected abstract java.lang.Class<? extends Item<? super T>> category()
      Returns the target entity category.
      java.util.function.Supplier<? extends T> creator()
      Returns the target entity creator
      Item<T> creator​(java.util.function.Supplier<? extends T> creator)
      Sets the final entity creator type that shall be used by the template.
      protected abstract java.util.function.Supplier<? extends T> defaultCreator()
      Returns the default target entity creator.
      protected abstract java.lang.Class<? extends T> defaultTarget()
      Returns the default target entity type.
      protected java.lang.Class<? extends Item<? super T>> defaultType()
      Returns the default entity supertype.
      static <X extends Entity>
      Item<X>      		 from​(java.lang.Class<? extends Item<? super X>> category, java.lang.Class<X> target, java.util.function.Supplier<X> creator)
      Returns an anonymous inline item based on the target entity implementation.
      java.lang.Class<? extends T> target()
      Returns the target entity type
      Item<T> target​(java.lang.Class<? extends T> type)
      Sets the final target entity type that shall be returned by the template.
      Template<? extends T> template()
      Returns the template to build the target entity.
      java.lang.Class<? extends Item<? super T>> type()
      Returns the entity supertype
      Item<T> type​(java.lang.Class<? extends Item<? super T>> type)
      Sets the entity supertype that shall be returned by the template.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • Item

        public Item()

    • Method Detail

      • template

        public Template<? extends T> template()
        Returns the template to build the target entity.

        This method should ultimately be used to provide the final entity template. Although, it may also provide a partial template that subclassed may complement.

        Returns:
        the matching entity template

      • target

        public java.lang.Class<? extends T> target()
        Returns the target entity type
        Returns:
        the target entity type

      • target

        public Item<T> target​(java.lang.Class<? extends T> type)
        Sets the final target entity type that shall be returned by the template.
        Parameters:
        type - the target entity type
        Returns:
        this

      • defaultTarget

        protected abstract java.lang.Class<? extends T> defaultTarget()
        Returns the default target entity type. This method should be implemented by subclasses to specify the target entity type.
        Returns:
        the default target entity type

      • type

        public java.lang.Class<? extends Item<? super T>> type()
        Returns the entity supertype
        Returns:
        the entity supertype

      • type

        public Item<T> type​(java.lang.Class<? extends Item<? super T>> type)
        Sets the entity supertype that shall be returned by the template.
        Parameters:
        type - the entity supertype
        Returns:
        this

      • defaultType

        protected java.lang.Class<? extends Item<? super T>> defaultType()
        Returns the default entity supertype. By default, this method returns the current class. This method may be implemented by subclasses to specify the entity supertype.
        Returns:
        the default entity supertype

      • creator

        public java.util.function.Supplier<? extends T> creator()
        Returns the target entity creator
        Returns:
        the target entity creator

      • creator

        public Item<T> creator​(java.util.function.Supplier<? extends T> creator)
        Sets the final entity creator type that shall be used by the template.
        Parameters:
        creator - the entity creator
        Returns:
        this

      • defaultCreator

        protected abstract java.util.function.Supplier<? extends T> defaultCreator()
        Returns the default target entity creator. This method should be implemented by subclasses to specify the entity creator.
        Returns:
        the default target entity creator

      • category

        protected abstract java.lang.Class<? extends Item<? super T>> category()
        Returns the target entity category. This method should be implemented by subclasses to specify the entity category.
        Returns:
        the target entity category

      • from

        public static <X extends Entity> Item<X> from​(java.lang.Class<? extends Item<? super X>> category,
                                              java.lang.Class<X> target,
                                              java.util.function.Supplier<X> creator)
        Returns an anonymous inline item based on the target entity implementation.
        Type Parameters:
        X - the entity target type
        Parameters:
        category - the entity category. It is the entity category as registered in the Factory and Registry. See Factory.of(String) and Registry.of(String).
        target - the target entity type. It is the entity instance to create and it will be used as the entity type. See Factory.get(String).
        creator - the custom instance creator that provides new instance of the target entity.
        Returns:
        a new anonymous item instance