com.marringtons.object
Class ObjectXML

java.lang.Object
  com.marringtons.object.ObjectXML

public class ObjectXML

extends Object

This is a Helper class of static methods for working with XML/object conversions.

 String xml = ObjectXML.toXML(object);
 to = (ObjectToTest) ObjectXML.fromXML(new StringReader(xml));
 

Objects are recorded in XML in the following format:

 
  <com.marringtons.object.ObjectsTest$ObjectToTest>
    <aString>a string</aString>
    <anInteger>19582003</anInteger>
    <innerObject>
      <anotherString>inner string</anotherString>
      <anotherInteger>12345678</anotherInteger>
      <anotherLongInteger>-9223372036854775808</anotherLongInteger>
    </innerObject>
    <longInteger>9223372036854775807</longInteger>
    <aMap>
      <java.lang.String>1of2</java.lang.String>
      <java.lang.String>one</java.lang.String>
      <java.lang.String>2of2</java.lang.String>
      <com.marringtons.object.ObjectsTest$InnerObject>
        <anotherString>innerObject in map</anotherString>
        <anotherInteger>222</anotherInteger>
        <anotherLongInteger>22222222</anotherLongInteger>
      </com.marringtons.object.ObjectsTest$InnerObject>
    </aMap>
    <aCollection>
      <java.lang.String>1of3</java.lang.String>
      <java.lang.String>2of3</java.lang.String>
      <java.lang.String>3of3</java.lang.String>
    </aCollection>
    <bytes length='4'>0,1,2,3</bytes>
    <innerObjects length='2'>
      <com.marringtons.object.ObjectsTest$InnerObject>
        <anotherString>1of2</anotherString>
        <anotherInteger>102</anotherInteger>
        <anotherLongInteger>11111111</anotherLongInteger>
      </com.marringtons.object.ObjectsTest$InnerObject>
      <com.marringtons.object.ObjectsTest$InnerObject>
        <anotherString>2of2</anotherString>
        <anotherInteger>202</anotherInteger>
        <anotherLongInteger>22222222</anotherLongInteger>
      </com.marringtons.object.ObjectsTest$InnerObject>
    </innerObjects>
  </com.marringtons.object.ObjectsTest$ObjectToTest>
  
 

There are times when the objects need to be saved externally, transmitted or represented in an (almost) human readable form. To this end, there are a number of classes that create a XML representation. There are methods to export/import all objects pointed to by an Index (one class) or all objects in a database (all persistent classes). Reader and Writer classes are used for I/O. There are both buffered and unbuffered signatures, so there is no need to buffer the writer before use.

 String xmlRepresentation = ObjectXML.toXML(dao);
 MyDAO dao2 = (MyDAO) ObjectXML.fromXML(xmlRepresentation);
 assertTrue(dao.compareTo(dao2) == 0);
 
 // write all of the objects in the database index to a Writer output stream.
 // Outer tag will be name of the database.
 Writer writer = new FileWriter("MyDAO.xml");
 ObjectXML.toXML(writer, dao); // only the MyDAO objects
 writer.close();
 
 // write all of the objects in the default database to a Writer output stream.
 // Outer tag will be name of the database.
 Writer writer = new FileWriter("MyDB.xml");
 ObjectXML.allToXML(writer); // all objects in the database (except generated indexes)
 writer.close();
 
 // read in an XML stream and save to the current database (ignoring database name in stream)
 // Set unique to true if it is possible that the data already exists. This is much slower,
 // so any time you can be confident that the data is unique, use false.
 Reader reader = new FileReader("MyDB.xml");
 ObjectXML.fromXML(reader, true);
 
 // Either stream (index or database) can be used to load object back into a persistent store.
 // If this is known to be a fresh load or all new items, set the unique flag to false as this
 // is much faster. Inner DAOs are always tested for uniqueness since the stream will load them
 // independantly as well as part of the outer DAO. If you provide an unbuffered reader, it will
 // wrapped before processing.
 ObjectXML.fromXML(uniqueObjectReader, false, null);
 Reader restoreObjectsReader = new FileReader("MyDB.xml");
 ObjectXML.fromXML(restoreObjectsReader, true, null);
 
 // Ordinarily where the same library created an XML object representation the default
 // translator will do. In special circumstances, or for XML data from external sources, it
 // may be necessary to translate specific fields in a special way (roman numerals to integer,
 // for example). In these cases, provide a custom translator.
 static class customTranslator extends Translator
 	{
 		int anotherInteger( String from)
 			{
 				return convertFromRomanNumerals(from);
 			}
 	}
 ObjectXML.fromXML(restoreObjectsReader, true, new customTranslator());
 

It is possible to translate a DTO directly from or to an XML stream using the static ObjectXML class methods.

Author:

Paul Marrington

Constructor Summary

ObjectXML()

Method Summary

static void	allToXML(BufferedWriter writer) Scan default database and convert all contained objects to XML.
static void	allToXML(BufferedWriter writer, String database) Scan a database and convert all contained objects to XML.
static void	allToXML(Writer writer) Scan default database and convert all contained objects to XML.
static void	allToXML(Writer writer, String database) Scan a database and convert all contained objects to XML.
static Object	fromXML(BufferedReader xml, Translator translator) Convert an XML stream into a POJO - using a static class directory for the purpose.
static DAO	fromXML(Database db, BufferedReader reader, boolean unique, Translator translator) Given a stream of XML, extract the objects and save them into the current database.
static void	fromXML(Database db, Reader reader, boolean unique, Translator translator) Given a stream of XML, extract the objects and save them into the current database.
static Object	fromXML(String xml, Translator translator) Given an XML string created by toXML(), create an instance of the DAO or POJO.
static void	toXML(BufferedWriter writer, DAO dao) Create an XML stream of all objects pointed to by a single index in a single related database.
static String	toXML(DAO dao) Convert a DAO to an XML representation.
static String	toXML(Object object) Convert a POJO to an XML representation.
static void	toXML(Writer writer, DAO dao) Create an XML stream of all objects pointed to by a single index in a single related database.

Methods inherited from class java.lang.Object

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

Constructor Detail

ObjectXML

public ObjectXML()

Method Detail

toXML

public static String toXML(DAO dao)
                    throws IOException

Convert a DAO to an XML representation.

Parameters:

dao - DAO to create an XML representation from.

Returns:

string representation of the object as XML

Throws:

IOException

IllegalArgumentException

toXML

public static void toXML(Writer writer,
                         DAO dao)
                  throws IOException

Create an XML stream of all objects pointed to by a single index in a single related database. Send it to an unbuffered writer.

Parameters:

writer - stream to write XML to

dao - to write all occurrences of to the output stream

Throws:

IllegalArgumentException

IOException

See Also:

ObjectXML

toXML

public static void toXML(BufferedWriter writer,
                         DAO dao)
                  throws IOException

Create an XML stream of all objects pointed to by a single index in a single related database.

Parameters:

writer - stream to write XML to

dao - to write all occurrences of to the output stream

Throws:

IllegalArgumentException

IOException

See Also:

ObjectXML

allToXML

public static void allToXML(Writer writer,
                            String database)
                     throws IllegalArgumentException,
                            IOException,
                            IllegalAccessException,
                            InstantiationException

Scan a database and convert all contained objects to XML.

Parameters:

writer - stream to recieve XML text.

database - to scan for objects.

Throws:

InstantiationException

IllegalAccessException

IOException

IllegalArgumentException

See Also:

ObjectXML

allToXML

public static void allToXML(BufferedWriter writer,
                            String database)
                     throws IllegalArgumentException,
                            IOException,
                            IllegalAccessException,
                            InstantiationException

Scan a database and convert all contained objects to XML.

Parameters:

writer - stream to recieve XML text.

database - to scan for objects.

Throws:

InstantiationException

IllegalAccessException

IOException

IllegalArgumentException

See Also:

ObjectXML

allToXML

public static void allToXML(Writer writer)
                     throws IllegalArgumentException,
                            IOException,
                            IllegalAccessException,
                            InstantiationException

Scan default database and convert all contained objects to XML.

Parameters:

writer - stream to recieve XML text.

Throws:

InstantiationException

IllegalAccessException

IOException

IllegalArgumentException

See Also:

ObjectXML

allToXML

public static void allToXML(BufferedWriter writer)
                     throws IllegalArgumentException,
                            IOException,
                            IllegalAccessException,
                            InstantiationException

Scan default database and convert all contained objects to XML.

Parameters:

writer - stream to recieve XML text.

Throws:

InstantiationException

IllegalAccessException

IOException

IllegalArgumentException

See Also:

ObjectXML

toXML

public static String toXML(Object object)
                    throws IOException

Convert a POJO to an XML representation. It uses a private common class directory not associated with any database.

Parameters:

object - POJO to create an XML representation from.

Returns:

string representation of the object as XML

Throws:

IOException

IllegalArgumentException

fromXML

public static Object fromXML(String xml,
                             Translator translator)
                      throws XMLexception

Given an XML string created by toXML(), create an instance of the DAO or POJO. Use this when you have a string containing a single XML rendered object. In most cases use the database load method fromXML( Reader).

Parameters:

xml - string containing valid XML representing an instance of an object descended from DAO.

translator - used to translate individual tags - null for standard translation.

Returns:

DAO (cast as necessary to specific object class).

Throws:

XMLexception

See Also:

ObjectXML, Translator

fromXML

public static Object fromXML(BufferedReader xml,
                             Translator translator)
                      throws XMLexception

Convert an XML stream into a POJO - using a static class directory for the purpose.

Parameters:

xml - stream of object representations in XML

translator - used to translate individual tags - null for standard translation.

Returns:

One object converted from the stream.

Throws:

XMLexception - if anything goes wrong.

See Also:

Translator

fromXML

public static void fromXML(Database db,
                           Reader reader,
                           boolean unique,
                           Translator translator)
                    throws XMLexception,
                           IOException

Given a stream of XML, extract the objects and save them into the current database.

Parameters:

db - Database to hold the XML items read and processed.

reader - stream of XML objects.

unique - true to stop duplicates from being saved (much slower).

translator - used to translate individual tags - null for standard translation.

Throws:

XMLexception

IOException

See Also:

Translator

fromXML

public static DAO fromXML(Database db,
                          BufferedReader reader,
                          boolean unique,
                          Translator translator)
                   throws XMLexception,
                          IOException

Given a stream of XML, extract the objects and save them into the current database.

Parameters:

db - Database to hold the XML items read and processed.

reader - stream of XML objects.

unique - true to stop duplicates from being saved (much slower).

translator - used to translate individual tags - null for standard translation.

Returns:

Last dao processed. Only useful when processing 1 dao (as in String reader).

Throws:

XMLexception

IOException

See Also:

Translator