Package hudson

Class XmlFile

java.lang.Object
hudson.XmlFile
public final class XmlFile extends Object
Represents an XML data file that Jenkins uses as a data file.

Evolving data format

Changing data format requires a particular care so that users with the old data format can migrate to the newer data format smoothly.

Adding a field is the easiest. When you read an old XML that does not have any data, the newly added field is left to the VM-default value (if you let XStream create the object, such as read() — which is the majority), or to the value initialized by the constructor (if the object is created via new and then its value filled by XStream, such as unmarshal(Object).)

Removing a field requires that you actually leave the field with transient keyword. When you read the old XML, XStream will set the value to this field. But when the data is saved, the field will no longer will be written back to XML. (It might be possible to tweak XStream so that we can simply remove fields from the class. Any help appreciated.)

Changing the data structure is usually a combination of the two above. You'd leave the old data store with transient, and then add the new data. When you are reading the old XML, only the old field will be set. When you are reading the new XML, only the new field will be set. You'll then need to alter the code so that it will be able to correctly handle both situations, and that as soon as you see data in the old field, you'll have to convert that into the new data structure, so that the next save operation will write the new data (otherwise you'll end up losing the data, because old fields will be never written back.)

You may also want to call OldDataMonitor.report(UnmarshallingContext, String). This can be done within a nested class ConverterImpl extending XStream2.PassthruConverter in an override of XStream2.PassthruConverter.callback(T, com.thoughtworks.xstream.converters.UnmarshallingContext).

In some limited cases (specifically when the class is the root object to be read from XML, such as Descriptor), it is possible to completely and drastically change the data format. See Descriptor.load() for more about this technique.

There's a few other possibilities, such as implementing a custom Converter for XStream, or registering an alias.

Author:
Kohsuke Kawaguchi
See Also:

  • Constructor Details

    • XmlFile

      public XmlFile(File file)

    • XmlFile

      public XmlFile(com.thoughtworks.xstream.XStream xs, File file)

    • XmlFile

      public XmlFile(com.thoughtworks.xstream.XStream xs, File file, boolean force)
      Parameters:
      force - Whether or not to flush the page cache to the storage device with FileChannel.force(boolean) (i.e., fsync} or FlushFileBuffers) before this method returns. If you set this to false, you will lose data integrity.
      Since:
      2.304

  • Method Details

    • getFile

      public File getFile()

    • getXStream

      public com.thoughtworks.xstream.XStream getXStream()

    • read

      public Object read() throws IOException
      Loads the contents of this file into a new object.
      Throws:
      IOException

    • unmarshal

      public Object unmarshal(Object o) throws IOException
      Loads the contents of this file into an existing object.
      Returns:
      The unmarshalled object. Usually the same as o, but would be different if the XML representation is completely new.
      Throws:
      IOException

    • unmarshalNullingOut

      public Object unmarshalNullingOut(Object o) throws IOException
      Variant of unmarshal(Object) applying XStream2.unmarshal(HierarchicalStreamReader, Object, DataHolder, boolean).
      Throws:
      IOException
      Since:
      2.99

    • write

      public void write(Object o) throws IOException
      Throws:
      IOException

    • replaceIfNotAtTopLevel

      public static Object replaceIfNotAtTopLevel(Object o, Supplier<Object> replacement)
      Provides an XStream replacement for an object unless a call to write(java.lang.Object) is currently in progress. As per JENKINS-45892 this may be used by any class which expects to be written at top level to an XML file but which cannot safely be serialized as a nested object (for example, because it expects some onLoad hook): implement a writeReplace method delegating to this method. The replacement need not be Serializable since it is only necessary for use from XStream.
      Parameters:
      o - an object (this from writeReplace)
      replacement - a supplier of a safely serializable replacement object with a readResolve method
      Returns:
      o, if write(java.lang.Object) is being called on it, else the replacement
      Since:
      2.74

    • exists

      public boolean exists()

    • delete

      public void delete() throws IOException
      Throws:
      IOException

    • mkdirs

      public void mkdirs() throws IOException
      Throws:
      IOException

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • readRaw

      public Reader readRaw() throws IOException
      Opens a Reader that loads XML. This method uses the right encoding, not just the system default encoding.
      Returns:
      Reader for the file. should be close externally once read.
      Throws:
      IOException - Encoding issues

    • asString

      public String asString() throws IOException
      Returns the XML file read as a string.
      Throws:
      IOException

    • writeRawTo

      public void writeRawTo(Writer w) throws IOException
      Writes the raw XML to the given Writer. Writer will not be closed by the implementation.
      Throws:
      IOException

    • sniffEncoding

      public String sniffEncoding() throws IOException
      Parses the beginning of the file and determines the encoding.
      Returns:
      always non-null.
      Throws:
      IOException - if failed to detect encoding.