Xml model and basic usage

XMLField uses annotated interfaces to define the xml model.

Define model to read an xml file

We use the following xml file :

<database name="xmlfield-demo-db">
  <tables>
    <table tableType="system">
      <name>users</name>
      <fields>
        <field>
          <name>uid</name>
          <type>long</type>
        </field>
        <field>
          <name>uname</name>
          <type>java.lang.String</type>
        </field>
        <field>
          <name>firstName</name>
          <type>java.lang.String</type>
        </field>
        <field>
          <name>lastName</name>
          <type>java.lang.String</type>
        </field>
        <field>
          <name>email</name>
          <type>java.lang.String</type>
        </field>
      </fields>
    </table>
  </tables>
</database>
    
        

First, create an interface for the root object, and add the XmlField annotation :

import org.xmlfield.annotations.ResourceXPath;


@ResourceXPath("/database")
public interface IDatabase {

}
    

Then add some getters :

import org.xmlfield.annotations.ResourceXPath;


@ResourceXPath("/database")
public interface IDatabase {

    @FieldXPath("@name")
    String getName();

    @FieldXPath("tables/table")
    ITable[] getTables();

}
    

This time, we add FieldXPath annotations to map getters to xml tags. Please note that we don't use getter on 'tables' tag. Since this is only an enclosing tag, we let XmlField handle it for us.

Then we create the ITable and IField interfaces :

import org.xmlfield.annotations.ResourceXPath;


@ResourceXPath("/table")
public interface ITable {

    @FieldXPath("name")
    String getName();

    @FieldXPath("@tableType")
    String getTableType;

    @FieldXPath("fields/field")
    IField[] getFields()
}

@ResourceXPath("/field")
public interface IField {

    @FieldXPath("name")
    String getName();

    @FieldXPath("type")
    String getType();
}
    

Now, you're ready to read the field using XmlField

String xmlContent="<database>(...)</database";
XmlField xf = new XmlField();
IDatabase db = xf.xmlToObject( xmlContent, IDatabase.class );

System.out.println( db.getName() );
ITable tables = db.getTables();
System.out.println( tables[0].getName() );
    

Add support for writing

To update the xml content, you just have to add a few methods to the interface. This time no need to add annotations, XmlField will automatically find the XPath according to method names.

For single objects, we just add a setter.

For arrays, XmlField needs an additional addTo method. This method is used to create a new tag (since xmlField objects are just interfaces, you cannot create a new object using new IField()). The new tag is added to the xml document as soon as the method returns. The set method can be used to empty the document using setXXX(null), remove one or several tags or simply to reorder tags.

import org.xmlfield.annotations.ResourceXPath;


@ResourceXPath("/database")
public interface IDatabase {

    @FieldXPath("@name")
    String getName();
    
    void setName( String name);

    @FieldXPath("tables/table")
    ITable[] getTables();
    
    ITable addToTables();
    
    void setTables(ITable[] tables);

}

@ResourceXPath("/table")
public interface ITable {

    @FieldXPath("name")
    String getName();
    
    void setName(String name) ;

    @FieldXPath("@tableType")
    String getTableType();
    
    void setTableType();

    @FieldXPath("fields/field")
    IField[] getFields()
   
    IField addToFields();
    
    void setFields(IField[] fields);
    
}

@ResourceXPath("/field")
public interface IField {

    @FieldXPath("name")
    String getName();

    void setName(String name);
    
    @FieldXPath("type")
    String getType;
    
    void setType(String type);
}
    

Now you can update and save the document

String xmlContent="<database>(...)</database";
XmlField xf = new XmlField();
IDatabase db = xf.xmlToObject( xmlContent, IDatabase.class );

db.setName( "New db name" );

ITable newTable = db.addToTables();
newTable.setName("My new table");


String result = xf.objectToXml(db);

    

Supported types and additional methods

XmlField support most Java basic types (and corresponding objects types). When using these types in arrays, it is recommended to use XmlXXXX types instead : they are required to ensure no data loss will happen when moving tags in the array.

XmlField also support DateTime from JodaTime

  • boolean / Boolean
  • String / XmlString
  • int / Integer / XmlInt
  • long / Long
  • DateTime

XmlField also recognizes additional methods to ease development.

  • isXXX : for booleans
  • sizeOfXXX : for arrays
  • removeFromXXXX : for arrays
comments powered by Disqus