WRITING XML FILES

The XmlFile class in the FileHandling library can be used to write or modify XML files:

Writing a new file

In order to create an XML file, the following calling sequence should be followed:

• Create XmlFile object with the empty constructors:
     XmlFile myXml()
Note that the FileHandling library may handle in parallel up to XFCFI_MAX_FILES_NUMBER files.

• Create the XML tree in memory with XmlFile::create:
     myXml.create()


• Create the root element:
     myXml.createRoot("RootNodeName")


• Add elements to the file.

• Write the XML file to disk:
     myXml.write(output_file_name)

• Clean memory. The in-memory representation of an XML file normally takes a significant amount of memory space, typically between 7 and 10 times the size of the file on disk. For this reason it is important to provide the means for releasing the memory allocated after being used. This can be done using the XmlFile::clean, or it is done when the object XmlFile is destroyed.

Modifying an existing file

It is possible to modify an existing XML file and save to disk with the same name or a different one. The following calling sequence should be followed:

• Create XmlFile object. There are two options to create the object:

  1. Using the constructor with the input file name:
        XmlFile myXml(input_file_name)
     

  2. With the empty constructor and loading the file in memory with XmlFile::read method:
        XmlFile myXml()
   myXml.read(input_file_name)

  Note that the FileHandling library may handle in parallel up to XFCFI_MAX_FILES_NUMBER files.

• Add and or modify elements to the file.

• Write the XML file to disk:
  

  • Save the file with the same name (overwrite file):    myXml.write()
  • Save the file with a different name:    myXml.write(output_file_name)

• Clean memory. The in-memory representation of an XML file normally takes a significant amount of memory space, typically between 7 and 10 times the size of the file on disk. For this reason it is important to provide the means for releasing the memory allocated after being used. This can be done using the XmlFile::clean, or it is done when the object XmlFile is destroyed.

---

Adding elements in an XML file

Elements may be added using as input:

• a reference element to which they are attached:referenced using an XPath expression
• the created element name

The following possibilities are available:

• Add a child to the reference element with XmlFile::addChild. If the reference element already has children, the new element will be appended at the end of the children list.
• Add a sibling after the reference element using XmlFile::addNext. This will insert the new element just after the reference one.
• Add a sibling before the reference element using XmlFile::addPrevious. This will insert the new element just before the reference one.
• Attributes are added with XmlFile::addAttribute function using the name of the element that contains them as the reference element.

After a new element has been added to the in-memory representation of the XML file, the iterator is pointing to the last added element. Therefore, relative XPath expressions used just after an element insertion are relative to the inserted element.

Removing elements in an XML file

Existing elements are removed using XmlFile::removeNode with an XPath expression addressing them. If the requested element has children, all of them will be removed recursively.

Setting and/or modifying element values

When elements and attributes are created, they have no value. Element and attribute values may be set and/or modified with XmlFile::setValue (overcharged methods using an XPath expression for addressing the requested element or attribute).

---

Example

// ------------------------------------------------------------------------
//
//                           JAVA Example Program.
//                           WRITING XML FILES: Random reading
//
// ------------------------------------------------------------------------

import EECFI.*;

import java.util.Vector;
import java.lang.String;
import java.lang.Long;

// Main program
public class Example
{
  public static void main(String[] args)
  {
    //-------------------------------------------------
    // Put all the code inside try-catch statements
    // so, if something fails, an exception is thrown
    //-------------------------------------------------
    
    try
    {
      XmlFile myXml = new XmlFile();
      String writtenXmlFile = new String("output_file.xml");
      
      
      //The name to the file is given when we write it to disk
      myXml.create();
      myXml.createRoot("Earth_Explorer_File");
      
      // Creating a child after another 
      myXml.addChild( ".", "Data_Block");
      myXml.addChild( ".", "List_of_Orbit_Changes");
      myXml.addChild( ".", "Orbit_Change");
      myXml.addChild( ".", "Orbit");
      myXml.addChild( ".", "Absolute_Orbit");
      
      // Adding a value to the current node 
      myXml.setValue( ".", "10", "%s");
      
      // Adding a sibling next to the current node, and then its value 
      // Creating and setting value can be done in 2 steps...
      myXml.addNext( ".", "Relative_Orbit");
      myXml.setValue( ".", "15", "%s");
      
      //... or only in one
      myXml.addChild( "..", "Phase_Number", "1", "%s");
      
      // Adding a sibling before the current node, and then its value 
      myXml.addPrevious( ".", "Cycle_Number", "1", "%s");
      
      // Another child, with a different path 
      myXml.addChild( "/Earth_Explorer_File/Data_Block/List_of_Orbit_Changes/Orbit_Change[1]", "Cycle");
      
      myXml.addChild( ".", "Repeat_Cycle", "3", "%s");
      myXml.addAttribute( ".", "units", "day", "%s");
      myXml.addNext( ".", "Cycle_Length");
      
      // Adding an attribute to the current node, and then its value 
      myXml.addAttribute( ".", "unit");
      myXml.setValue( "@unit", "orbit", "%s");
      
      myXml.setValue ( ".", "43" , "%s");
      myXml.addNext( ".", "ANX_Longitude");
      
      // Adding a value as double. Please, pay attention to the format
      myXml.setValue( ".", 0.1335, "%06.4lf" );
      myXml.addAttribute( ".", "unit", "deg", "%s");
      
      // Removing an attribute, and then the current node 
      myXml.removeNode( "@unit" );
      myXml.removeNode( "../Repeat_Cycle" );
      
      myXml.addPrevious( "Cycle_Length", "Repeat_Cycle");
      
      // Adding a value as long. Please, pay attention to the format
      myXml.setValue( ".", 5L, "%ld" );
      myXml.setValue( "@unit", "day", "%s");
      myXml.setValue( "../Cycle_Length", "57", "%s");
      myXml.addChild( "..",  "MLST", "22:00:00.45545", "%s");
      myXml.addNext( ".", "MLST_Drift", "011.010101", "%s" );
      myXml.addChild( "../..", "Time_of_ANX");
      myXml.addChild( ".", "TAI_of_ANX", "TAI=2002-03-01T03:01:09.01345", "%s" );
      myXml.addNext( ".", "UTC_of_ANX", "UTC=2002-03-01T03:01:10.01345", "%s" );
      myXml.addNext( ".", "UT1_of_ANX", "UT1=2002-03-01T03:01:11.01345", "%s"); 
      
      //Write XML file to disk
      myXml.write( writtenXmlFile );
      
    } //end try
    catch (CfiError cfiError)
    {
      //If an exception is thrown, there have been errors during execution
      Vector<String> errorMessages = new Vector<String>();
      
      // Get error messages
      errorMessages = cfiError.getMsg(errorMessages);
      
      // Pring Error messages
      for (int i = 0; i < errorMessages.size(); i++)
      {
        System.out.println( errorMessages.elementAt(i) );
      }
    }
  }
  
}