public final class XmlFile extends ObjectRepresents 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
newand then its value filled by XStream, such as
Removing a field requires that you actually leave the field with
transientkeyword. 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
saveoperation 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
XStream2.PassthruConverterin an override of
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
Converterfor XStream, or
registering an alias.
- Kohsuke Kawaguchi
- See Also:
- Architecture » Persistence
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description
asString()Returns the XML file read as a string.
read()Loads the contents of this file into a new object.
Readerthat loads XML.
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.
sniffEncoding()Parses the beginning of the file and determines the encoding.
unmarshal(Object o)Loads the contents of this file into an existing object.
writeRawTo(Writer w)Writes the raw XML to the given
public XmlFile(File file)
public XmlFile(com.thoughtworks.xstream.XStream xs, File file)
public XmlFile(com.thoughtworks.xstream.XStream xs, File file, boolean force)
force- Whether or not to flush the page cache to the storage device with
FlushFileBuffers) before this method returns. If you set this to
false, you will lose data integrity.
public File getFile()
public com.thoughtworks.xstream.XStream getXStream()
public Object read() throws IOExceptionLoads the contents of this file into a new object.
public Object unmarshal(Object o) throws IOExceptionLoads the contents of this file into an existing object.
- The unmarshalled object. Usually the same as
o, but would be different if the XML representation is completely new.
public Object unmarshalNullingOut(Object o) throws IOExceptionVariant of
XStream2.unmarshal(HierarchicalStreamReader, Object, DataHolder, boolean).
replaceIfNotAtTopLevelProvides 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
onLoadhook): implement a
writeReplacemethod delegating to this method. The replacement need not be
Serializablesince it is only necessary for use from XStream.
o- an object (
replacement- a supplier of a safely serializable replacement object with a
write(java.lang.Object)is being called on it, else the replacement
public boolean exists()
public Reader readRaw() throws IOExceptionOpens a
Readerthat loads XML. This method uses
the right encoding, not just the system default encoding.
- Reader for the file. should be close externally once read.
IOException- Encoding issues
public String asString() throws IOExceptionReturns the XML file read as a string.
public void writeRawTo(Writer w) throws IOExceptionWrites the raw XML to the given
Writer. Writer will not be closed by the implementation.