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:

Architecture » Persistence

Constructor Summary

XmlFile(File file)

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

Method Summary

String	asString() Returns the XML file read as a string.
void	delete()
boolean	exists()
File	getFile()
com.thoughtworks.xstream.XStream	getXStream()
void	mkdirs()
Object	read() Loads the contents of this file into a new object.
Reader	readRaw() Opens a Reader that loads XML.
String	sniffEncoding() Parses the beginning of the file and determines the encoding.
String	toString()
Object	unmarshal(Object o) Loads the contents of this file into an existing object.
void	write(Object o)
void	writeRawTo(Writer w) Writes the raw XML to the given Writer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XmlFile

public XmlFile(File file)

XmlFile

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

Method Detail

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

write

public void write(Object o)
           throws IOException

Throws:

IOException

exists

public boolean exists()

delete

public void delete()

mkdirs

public void mkdirs()

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.

Throws:

IOException

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.