Package io.kojan.xml

Class Entity<Type,​Bean>

  • Type Parameters:
    Type - data type of entity
    Bean - type of bean associated with the entity

    public class Entity<Type,​Bean>
    extends java.lang.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
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Type fromXML​(java.lang.String xml)
      Deserializes entity from XML format.
      Converter<Bean,​Type> getBeanConverter()
      Obtains a converter function that converts entity bean to entity object.
      Factory<Bean> getBeanFactory()
      Obtains a factory used to create initial entity bean.
      java.util.List<Property<Type,​Bean,​?>> getProperties()
      Get entity properties, such as attributes, relationships and other custom properties.
      java.lang.String getTag()
      Determines XML element tag name used to serialize the entity in XML form.
      static <Type,​Bean>
      Entity<Type,​Bean>
      of​(java.lang.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.
      static <Type,​Bean extends Builder<Type>>
      Entity<Type,​Bean>
      of​(java.lang.String tag, Factory<Bean> beanFactory, Property<Type,​Bean,​?>... properties)
      Creates an entity using a bean class implementing the Builder interface.
      static <Type> Entity<Type,​Type> ofMutable​(java.lang.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 readFromXML​(java.io.Reader reader)
      Deserializes entity from XML format, reading XML data from given Reader.
      Type readFromXML​(java.nio.file.Path path)
      Deserializes entity from XML format, reading XML data from file at given Path.
      java.lang.String toXML​(Type object)
      Serializes entity into XML format.
      void writeToXML​(java.io.Writer writer, Type object)
      Serializes entity into XML format, writing XML data to given Writer.
      void writeToXML​(java.nio.file.Path path, Type object)
      Serializes entity into XML format, writing XML data to file at given Path.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Entity

        public Entity​(java.lang.String tag,
                      Factory<Bean> beanFactory,
                      Converter<Bean,​Type> converter,
                      java.util.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 Detail

      • of

        @SafeVarargs
        public static <Type,​Bean> Entity<Type,​Bean> of​(java.lang.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​(java.lang.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​(java.lang.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 java.lang.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 java.util.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​(java.io.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​(java.nio.file.Path path)
                         throws java.io.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:
        java.io.IOException - in case I/O exception occurs when reading form the file
        XMLException - in case exception occurs during XML deserialization
      • fromXML

        public Type fromXML​(java.lang.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​(java.io.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​(java.nio.file.Path path,
                               Type object)
                        throws java.io.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:
        java.io.IOException - in case I/O exception occurs when writing to the file
        XMLException - in case exception occurs during XML serialization
      • toXML

        public java.lang.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