Package io.kojan.xml

Class Entity<Type,Bean>

java.lang.Object
io.kojan.xml.Entity<Type,Bean>
Type Parameters:
Type - data type of entity
Bean - type of bean associated with the entity

public class Entity<Type,Bean> extends Object
An entity type. Type of things about which the data should be stored.

When stored in XML form, an entity is represented by an XML element with a specified tag. Nested child elements represent entity attributes, entity relationships and possibly other custom entity properties.

An entity has an associated base data type, which may be immutable or mutable - the library code makes no assumptions about the mutability of the base type.

In addition to its main type, an entity also has a bean type, which is always mutable. Conversion from beans to the base data type is done by supplied converter method, or by implementing the Builder interface. In the case where the main type is mutable, it is acceptable for the main type and the bean type to be the same type.

Author:
Mikolaj Izdebski
  • Constructor Details

    • Entity

      public Entity(String tag, Factory<Bean> beanFactory, Converter<Bean,Type> converter, List<Property<Type,Bean,?>> properties)
      Creates an entity.
      Parameters:
      tag - XML element tag name used to serialize the property in XML form (see getTag())
      beanFactory - factory used to create initial entity bean
      converter - converter function that converts entity bean to entity object
      properties - one or more entity properties
  • Method Details

    • of

      @SafeVarargs public static <Type, Bean> Entity<Type,Bean> of(String tag, Factory<Bean> beanFactory, Converter<Bean,Type> converter, Property<Type,Bean,?>... properties)
      Creates an entity using a converter method for converting entity beans to entity objects.
      Type Parameters:
      Type - data type of entity
      Bean - type of bean associated with the entity
      Parameters:
      tag - XML element tag name used to serialize the property in XML form (see getTag())
      beanFactory - factory used to create initial entity bean
      converter - converter function that converts entity bean to entity object
      properties - one or more entity properties
      Returns:
      created entity
    • of

      @SafeVarargs public static <Type, Bean extends Builder<Type>> Entity<Type,Bean> of(String tag, Factory<Bean> beanFactory, Property<Type,Bean,?>... properties)
      Creates an entity using a bean class implementing the Builder interface.
      Type Parameters:
      Type - data type of entity
      Bean - type of bean associated with the entity
      Parameters:
      tag - XML element tag name used to serialize the property in XML form (see getTag())
      beanFactory - factory used to create initial entity bean
      properties - one or more entity properties
      Returns:
      created entity
    • ofMutable

      @SafeVarargs public static <Type> Entity<Type,Type> ofMutable(String tag, Factory<Type> factory, Property<Type,Type,?>... properties)
      Creates an entity over a mutable data type that does not need conversion from bean type.
      Type Parameters:
      Type - mutable data type of entity
      Parameters:
      tag - XML element tag name used to serialize the property in XML form (see getTag())
      factory - factory used to create initial entity object
      properties - one or more entity properties
      Returns:
      created entity
    • getTag

      public String getTag()
      Determines XML element tag name used to serialize the entity in XML form.
      Returns:
      XML element tag name
    • getBeanFactory

      public Factory<Bean> getBeanFactory()
      Obtains a factory used to create initial entity bean.
      Returns:
      factory used to create initial entity bean
    • getBeanConverter

      public Converter<Bean,Type> getBeanConverter()
      Obtains a converter function that converts entity bean to entity object.
      Returns:
      converter converter function that converts entity bean to entity object
    • getProperties

      public List<Property<Type,Bean,?>> getProperties()
      Get entity properties, such as attributes, relationships and other custom properties.
      Returns:
      unmodifiable list of properties
    • readFromXML

      public Type readFromXML(Reader reader) throws XMLException
      Deserializes entity from XML format, reading XML data from given Reader.
      Parameters:
      reader - the source to read XML data from
      Returns:
      deserialized entity object
      Throws:
      XMLException - in case exception occurs during XML deserialization
    • readFromXML

      public Type readFromXML(Path path) throws IOException, XMLException
      Deserializes entity from XML format, reading XML data from file at given Path.
      Parameters:
      path - path to the source file from which XML data is read
      Returns:
      deserialized entity object
      Throws:
      IOException - in case I/O exception occurs when reading form the file
      XMLException - in case exception occurs during XML deserialization
    • fromXML

      public Type fromXML(String xml) throws XMLException
      Deserializes entity from XML format.
      Parameters:
      xml - serialized entity in XML format
      Returns:
      deserialized entity object
      Throws:
      XMLException - in case exception occurs during XML deserialization
    • writeToXML

      public void writeToXML(Writer writer, Type object) throws XMLException
      Serializes entity into XML format, writing XML data to given Writer.
      Parameters:
      writer - the sink to write XML data to
      object - entity object to serialize
      Throws:
      XMLException - in case exception occurs during XML serialization
    • writeToXML

      public void writeToXML(Path path, Type object) throws IOException, XMLException
      Serializes entity into XML format, writing XML data to file at given Path.
      Parameters:
      path - path to the sink file to write XML data to
      object - entity object to serialize
      Throws:
      IOException - in case I/O exception occurs when writing to the file
      XMLException - in case exception occurs during XML serialization
    • toXML

      public String toXML(Type object) throws XMLException
      Serializes entity into XML format.
      Parameters:
      object - entity object to serialize
      Returns:
      serialized entity in XML format
      Throws:
      XMLException - in case exception occurs during XML serialization