Class XMap


  • public class XMap
    extends Object
    XMap maps an XML file to a java object.

    The mapping is described by annotations on java objects.

    The following annotations are supported:

    • XObject Mark the object as being mappable to an XML node
    • XNode Map an XML node to a field of a mappable object
    • XNodeList Map an list of XML nodes to a field of a mappable object
    • XNodeMap Map an map of XML nodes to a field of a mappable object
    • XContent Map an XML node content to a field of a mappable object
    • XParent Map a field of the current mappable object to the parent object if any exists The parent object is the mappable object containing the current object as a field
    The mapping is done in 2 steps:
    • The XML file is loaded as a DOM document
    • The DOM document is parsed and the nodes mapping is resolved
    Author:
    Bogdan Stefanescu
    • Constructor Detail

      • XMap

        public XMap()
        Creates a new XMap object.
    • Method Detail

      • getValueFactory

        public XValueFactory getValueFactory​(Class<?> type)
        Gets the value factory used for objects of the given class.

        Value factories are used to decode values from XML strings.

        Parameters:
        type - the object type
        Returns:
        the value factory if any, null otherwise
      • setValueFactory

        public void setValueFactory​(Class<?> type,
                                    XValueFactory factory)
        Sets a custom value factory for the given class.

        Value factories are used to decode values from XML strings.

        Parameters:
        type - the object type
        factory - the value factory to use for the given type
      • getScannedObjects

        public Collection<XAnnotatedObject> getScannedObjects()
        Gets a list of scanned objects.

        Scanned objects are annotated objects that were registered by this XMap instance.

      • getRootObjects

        public Collection<XAnnotatedObject> getRootObjects()
        Gets the root objects.

        Root objects are scanned objects that can be mapped to XML elements that are not part from other objects.

        Returns:
        the root objects
      • register

        public XAnnotatedObject register​(Class<?> klass)
        Registers a mappable object class.

        The class will be scanned for XMap annotations and a mapping description is created.

        Parameters:
        klass - the object class
        Returns:
        the mapping description
      • load

        public Object load​(URL url)
                    throws IOException
        Processes the XML file at the given URL using a default context.
        Parameters:
        url - the XML file url
        Returns:
        the first registered top level object that is found in the file, or null if no objects are found.
        Throws:
        IOException
      • load

        public Object load​(Context ctx,
                           URL url)
                    throws IOException
        Processes the XML file at the given URL and using the given contexts.
        Parameters:
        ctx - the context to use
        url - the XML file url
        Returns:
        the first registered top level object that is found in the file.
        Throws:
        IOException
      • load

        public Object load​(InputStream in)
                    throws IOException
        Processes the XML content from the given input stream using a default context.
        Parameters:
        in - the XML input source
        Returns:
        the first registered top level object that is found in the file.
        Throws:
        IOException
      • load

        public Object load​(Context ctx,
                           InputStream in)
                    throws IOException
        Processes the XML content from the given input stream using the given context.
        Parameters:
        ctx - the context to use
        in - the input stream
        Returns:
        the first registered top level object that is found in the file.
        Throws:
        IOException
      • loadAll

        public Object[] loadAll​(URL url)
                         throws IOException
        Processes the XML file at the given URL using a default context.

        Returns a list with all registered top level objects that are found in the file.

        If not objects are found, an empty list is returned.

        Parameters:
        url - the XML file url
        Returns:
        a list with all registered top level objects that are found in the file
        Throws:
        IOException
      • loadAll

        public Object[] loadAll​(Context ctx,
                                URL url)
                         throws IOException
        Processes the XML file at the given URL using the given context

        Return a list with all registered top level objects that are found in the file.

        If not objects are found an empty list is retoruned.

        Parameters:
        ctx - the context to use
        url - the XML file url
        Returns:
        a list with all registered top level objects that are found in the file
        Throws:
        IOException
      • loadAll

        public Object[] loadAll​(InputStream in)
                         throws IOException
        Processes the XML from the given input stream using the given context.

        Returns a list with all registered top level objects that are found in the file.

        If not objects are found, an empty list is returned.

        Parameters:
        in - the XML input stream
        Returns:
        a list with all registered top level objects that are found in the file
        Throws:
        IOException
      • loadAll

        public Object[] loadAll​(Context ctx,
                                InputStream in)
                         throws IOException
        Processes the XML from the given input stream using the given context.

        Returns a list with all registered top level objects that are found in the file.

        If not objects are found, an empty list is returned.

        Parameters:
        ctx - the context to use
        in - the XML input stream
        Returns:
        a list with all registered top level objects that are found in the file
        Throws:
        IOException
      • load

        public Object load​(Element root)
        Processes the given DOM element and return the first mappable object found in the element.

        A default context is used.

        Parameters:
        root - the element to process
        Returns:
        the first object found in this element or null if none
      • load

        public Object load​(Context ctx,
                           Element root)
        Processes the given DOM element and return the first mappable object found in the element.

        The given context is used.

        Parameters:
        ctx - the context to use
        root - the element to process
        Returns:
        the first object found in this element or null if none
      • loadAll

        public Object[] loadAll​(Context ctx,
                                Element root)
        Processes the given DOM element and return a list with all top-level mappable objects found in the element.

        The given context is used.

        Parameters:
        ctx - the context to use
        root - the element to process
        Returns:
        the list of all top level objects found
      • loadAll

        public Object[] loadAll​(Element root)
        Processes the given DOM element and return a list with all top-level mappable objects found in the element.

        The default context is used.

        Parameters:
        root - the element to process
        Returns:
        the list of all top level objects found
      • loadAll

        public void loadAll​(Element root,
                            Collection<Object> result)
        Same as loadAll(Element) but put collected objects in the given collection.
        Parameters:
        root - the element to process
        result - the collection where to collect objects
      • loadAll

        public void loadAll​(Context ctx,
                            Element root,
                            Collection<Object> result)
        Same as loadAll(Context, Element) but put collected objects in the given collection.
        Parameters:
        ctx - the context to use
        root - the element to process
        result - the collection where to collect objects