hudson.util

Class XStream2

java.lang.Object

com.thoughtworks.xstream.XStream

hudson.util.XStream2

public class XStream2
extends com.thoughtworks.xstream.XStream

XStream enhanced for additional Java5 support and improved robustness.

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	XStream2.PassthruConverter<T> Create a nested ConverterImpl subclass that extends this class to run some callback code just after a type is unmarshalled by RobustReflectionConverter.

Nested classes/interfaces inherited from class com.thoughtworks.xstream.XStream

com.thoughtworks.xstream.XStream.InitializationException

Field Summary

Fields inherited from class com.thoughtworks.xstream.XStream

ID_REFERENCES, NO_REFERENCES, PRIORITY_LOW, PRIORITY_NORMAL, PRIORITY_VERY_HIGH, PRIORITY_VERY_LOW, SINGLE_NODE_XPATH_ABSOLUTE_REFERENCES, SINGLE_NODE_XPATH_RELATIVE_REFERENCES, XPATH_ABSOLUTE_REFERENCES, XPATH_RELATIVE_REFERENCES

Constructor Summary

Constructors

Constructor and Description
XStream2()
XStream2(com.thoughtworks.xstream.io.HierarchicalStreamDriver hierarchicalStreamDriver)

Method Summary

Modifier and Type	Method and Description
void	addCompatibilityAlias(String oldClassName, Class newClass) Adds an alias in case class names change.
void	addCriticalField(Class<?> clazz, String field) Specifies that a given field of a given class should not be treated with laxity by RobustCollectionConverter.
protected com.thoughtworks.xstream.converters.Converter	createDefaultConverter()
static com.thoughtworks.xstream.io.HierarchicalStreamDriver	getDefaultDriver() Convenience method so we only have to change the driver in one place if we switch to something new in the future
com.thoughtworks.xstream.mapper.Mapper	getMapperInjectionPoint()
void	setMapper(com.thoughtworks.xstream.mapper.Mapper m) This method allows one to insert additional mappers after XStream2 was created, but because of the way XStream works internally, this needs to be done carefully.
void	toXML(Object obj, OutputStream out) Deprecated. Uses default encoding yet fails to write an encoding header. Prefer toXMLUTF8(java.lang.Object, java.io.OutputStream).
void	toXMLUTF8(Object obj, OutputStream out) Serializes to a byte stream.
Object	unmarshal(com.thoughtworks.xstream.io.HierarchicalStreamReader reader, Object root, com.thoughtworks.xstream.converters.DataHolder dataHolder)
Object	unmarshal(com.thoughtworks.xstream.io.HierarchicalStreamReader reader, Object root, com.thoughtworks.xstream.converters.DataHolder dataHolder, boolean nullOut) Variant of unmarshal(HierarchicalStreamReader, Object, DataHolder) that nulls out non-transient instance fields not defined in the source when unmarshaling into an existing object.
protected com.thoughtworks.xstream.mapper.MapperWrapper	wrapMapper(com.thoughtworks.xstream.mapper.MapperWrapper next)

Methods inherited from class com.thoughtworks.xstream.XStream

addDefaultImplementation, addImmutableType, addImplicitArray, addImplicitArray, addImplicitArray, addImplicitCollection, addImplicitCollection, addImplicitCollection, addImplicitMap, addImplicitMap, addPermission, alias, alias, aliasAttribute, aliasAttribute, aliasField, aliasPackage, aliasSystemAttribute, aliasType, allowTypeHierarchy, allowTypes, allowTypes, allowTypesByRegExp, allowTypesByRegExp, allowTypesByWildcard, autodetectAnnotations, createObjectInputStream, createObjectInputStream, createObjectInputStream, createObjectOutputStream, createObjectOutputStream, createObjectOutputStream, createObjectOutputStream, createObjectOutputStream, createObjectOutputStream, denyPermission, denyTypeHierarchy, denyTypes, denyTypes, denyTypesByRegExp, denyTypesByRegExp, denyTypesByWildcard, fromXML, fromXML, fromXML, fromXML, fromXML, fromXML, fromXML, fromXML, fromXML, fromXML, getClassLoader, getClassLoaderReference, getConverterLookup, getConverterRegistry, getJvm, getMapper, getReflectionProvider, ignoreUnknownElements, ignoreUnknownElements, marshal, marshal, newDataHolder, omitField, processAnnotations, processAnnotations, registerConverter, registerConverter, registerConverter, registerConverter, registerLocalConverter, registerLocalConverter, setClassLoader, setMarshallingStrategy, setMode, setupAliases, setupConverters, setupDefaultImplementations, setupImmutableTypes, setupSecurity, toXML, toXML, unmarshal, unmarshal, useAttributeFor, useAttributeFor, useAttributeFor, useXStream11XmlFriendlyMapper

Methods inherited from class java.lang.Object

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

Constructor Detail

XStream2

public XStream2()

XStream2

public XStream2(com.thoughtworks.xstream.io.HierarchicalStreamDriver hierarchicalStreamDriver)

Method Detail

getDefaultDriver

public static com.thoughtworks.xstream.io.HierarchicalStreamDriver getDefaultDriver()

Convenience method so we only have to change the driver in one place if we switch to something new in the future

Returns:

a new instance of the HierarchicalStreamDriver we want to use

unmarshal

public Object unmarshal(com.thoughtworks.xstream.io.HierarchicalStreamReader reader,
                        Object root,
                        com.thoughtworks.xstream.converters.DataHolder dataHolder)

Overrides:

unmarshal in class com.thoughtworks.xstream.XStream

unmarshal

public Object unmarshal(com.thoughtworks.xstream.io.HierarchicalStreamReader reader,
                        Object root,
                        com.thoughtworks.xstream.converters.DataHolder dataHolder,
                        boolean nullOut)

Variant of unmarshal(HierarchicalStreamReader, Object, DataHolder) that nulls out non-transient instance fields not defined in the source when unmarshaling into an existing object.

Typically useful when loading user-supplied XML files in place (non-null root) where some reference-valued fields of the root object may have legitimate reasons for being null. Without this mode, it is impossible to clear such fields in an existing instance, since XStream has no notation for a null field value. Even for primitive-valued fields, it is useful to guarantee that unmarshaling will produce the same result as creating a new instance.

Do not use in cases where the root objects defines fields (typically final) which it expects to be NonNull unless you are prepared to restore default values for those fields.

Parameters:

nullOut - whether to perform this special behavior; false to use the stock XStream behavior of leaving unmentioned root fields untouched

Since:

2.99

See Also:

XmlFile.unmarshalNullingOut(java.lang.Object), JENKINS-21017

createDefaultConverter

protected com.thoughtworks.xstream.converters.Converter createDefaultConverter()

Overrides:

createDefaultConverter in class com.thoughtworks.xstream.XStream

addCriticalField

public void addCriticalField(Class<?> clazz,
                             String field)

Specifies that a given field of a given class should not be treated with laxity by RobustCollectionConverter.

Parameters:

clazz - a class which we expect to hold a non-transient field

field - a field name in that class

Since:

2.85 this method can be used from outside core, before then it was restricted since initially added in 1.551 / 1.532.2

wrapMapper

protected com.thoughtworks.xstream.mapper.MapperWrapper wrapMapper(com.thoughtworks.xstream.mapper.MapperWrapper next)

Overrides:

wrapMapper in class com.thoughtworks.xstream.XStream

getMapperInjectionPoint

public com.thoughtworks.xstream.mapper.Mapper getMapperInjectionPoint()

toXML

@Deprecated
public void toXML(Object obj,
                              OutputStream out)

Deprecated. Uses default encoding yet fails to write an encoding header. Prefer toXMLUTF8(java.lang.Object, java.io.OutputStream).

Overrides:

toXML in class com.thoughtworks.xstream.XStream

toXMLUTF8

public void toXMLUTF8(Object obj,
                      OutputStream out)
               throws IOException

Serializes to a byte stream. Uses UTF-8 encoding and specifies that in the XML encoding declaration.

Throws:

IOException

Since:

1.504

setMapper

public void setMapper(com.thoughtworks.xstream.mapper.Mapper m)

This method allows one to insert additional mappers after XStream2 was created, but because of the way XStream works internally, this needs to be done carefully. Namely,

1. You need to getMapperInjectionPoint() wrap it, then put that back into setMapper(Mapper).
2. The whole sequence needs to be synchronized against this object to avoid a concurrency issue.

addCompatibilityAlias

public void addCompatibilityAlias(String oldClassName,
                                  Class newClass)

Adds an alias in case class names change. Unlike XStream.alias(String, Class), which uses the registered alias name for writing XML, this method registers an alias to be used only for the sake of reading from XML. This makes this method usable for the situation when class names change.

Parameters:

oldClassName - Fully qualified name of the old class name.

newClass - New class that's field-compatible with the given old class name.

Since:

1.416