Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.thoughtworks.xstream
Class XStream

    java.lang.Object
      com.thoughtworks.xstream.XStream

    public class XStream

extends Object

Simple facade to XStream library, a Java-XML serialization tool.

Example

>      XStream xstream = new XStream();
>      String xml = xstream.toXML(myObject); // serialize to XML
>      Object myObject2 = xstream.fromXML(xml); // deserialize from XML

### Aliasing classes

To create shorter XML, you can specify aliases for classes using the `alias()` method. For example, you can shorten all occurrences of element `<com.blah.MyThing>` to `<my-thing>` by registering an alias for the class.

>      xstream.alias("my-thing", MyThing.class);

### Converters

XStream contains a map of `Converter` instances, each of which acts as a strategy for converting a particular type of class to XML and back again. Out of the box, XStream contains converters for most basic types (String, Date, int, boolean, etc) and collections (Map, List, Set, Properties, etc). For other objects reflection is used to serialize each field recursively.

Extra converters can be registered using the `registerConverter()` method. Some non-standard converters are supplied in the `com.thoughtworks.xstream.converters.extended` package and you can create your own by implementing the `Converter` interface.

Example

>      xstream.registerConverter(new SqlTimestampConverter());
>      xstream.registerConverter(new DynamicProxyConverter());

The converters can be registered with an explicit priority. By default they are registered with XStream.PRIORITY_NORMAL. Converters of same priority will be used in the reverse sequence they have been registered. The default converter, i.e. the converter which will be used if no other registered converter is suitable, can be registered with priority XStream.PRIORITY_VERY_LOW. XStream uses by default the `ReflectionConverter` as the fallback converter.

Example

>      xstream.registerConverter(new CustomDefaultConverter(), XStream.PRIORITY_VERY_LOW);

### Object graphs

XStream has support for object graphs; a deserialized object graph will keep references intact, including circular references.

XStream can signify references in XML using either relative/absolute XPath or IDs. The mode can be changed using `setMode()`:

`xstream.setMode(XStream.XPATH_RELATIVE_REFERENCES);` | (Default) Uses XPath relative references to signify duplicate references. This produces XML with the least clutter.
`xstream.setMode(XStream.XPATH_ABSOLUTE_REFERENCES);` | Uses XPath absolute references to signify duplicate references. This produces XML with the least clutter.
`xstream.setMode(XStream.ID_REFERENCES);` | Uses ID references to signify duplicate references. In some scenarios, such as when using hand-written XML, this is easier to work with.
`xstream.setMode(XStream.NO_REFERENCES);` | This disables object graph support and treats the object structure like a tree. Duplicate references are treated as two separate objects and circular references cause an exception. This is slightly faster and uses less memory than the other two modes.

### Thread safety

The XStream instance is thread-safe. That is, once the XStream instance has been created and configured, it may be shared across multiple threads allowing objects to be serialized/deserialized concurrently. Note, that this only applies if annotations are not auto-detected on -the-fly.

### Implicit collections

To avoid the need for special tags for collections, you can define implicit collections using one of the `addImplicitCollection` methods.

Author:
  Joe Walnes, Jörg Schaible, Mauro Talevi, Guilherme Silveira

Nested Class Summary
`static class` | `XStream.InitializationException` Deprecated. since 1.3, use `InitializationException` instead

Field Summary
`static int` | `ID_REFERENCES`
`static int` | `NO_REFERENCES`
`static int` | `PRIORITY_LOW`
`static int` | `PRIORITY_NORMAL`
`static int` | `PRIORITY_VERY_HIGH`
`static int` | `PRIORITY_VERY_LOW`
`static int` | `XPATH_ABSOLUTE_REFERENCES`
`static int` | `XPATH_REFERENCES` Deprecated. since 1.2, use `XPATH_RELATIVE_REFERENCES` or `XPATH_ABSOLUTE_REFERENCES` instead.
`static int` | `XPATH_RELATIVE_REFERENCES`

Constructor Summary
`XStream()` Constructs a default XStream.
`XStream(HierarchicalStreamDriver hierarchicalStreamDriver)` Constructs an XStream with a special `HierarchicalStreamDriver`.
`XStream(ReflectionProvider reflectionProvider)` Constructs an XStream with a special `ReflectionProvider`.
`XStream(ReflectionProvider reflectionProvider, ClassMapper classMapper, HierarchicalStreamDriver driver)` Deprecated. As of 1.2, use `XStream(ReflectionProvider, Mapper, HierarchicalStreamDriver)`
`XStream(ReflectionProvider reflectionProvider, ClassMapper classMapper, HierarchicalStreamDriver driver, String classAttributeIdentifier)` Deprecated. As of 1.2, use `XStream(ReflectionProvider, Mapper, HierarchicalStreamDriver)` and register classAttributeIdentifier as alias
`XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver hierarchicalStreamDriver)` Constructs an XStream with a special `HierarchicalStreamDriver` and `ReflectionProvider`.
`XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver driver, ClassLoader classLoader)` Constructs an XStream with a special `HierarchicalStreamDriver` and `ReflectionProvider` and additionally with a prepared `ClassLoader` to use.
`XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver driver, ClassLoader classLoader, Mapper mapper)` Constructs an XStream with a special `HierarchicalStreamDriver` and `ReflectionProvider` and additionally with a prepared `Mapper` and the `ClassLoader` in use.
`XStream(ReflectionProvider reflectionProvider, HierarchicalStreamDriver driver, ClassLoader classLoader, Mapper mapper, ConverterLookup converterLookup, ConverterRegistry converterRegistry)` Constructs an XStream with a special `HierarchicalStreamDriver`, `ReflectionProvider`, a prepared `Mapper` and the `ClassLoader` in use and an own `ConverterRegistry`.
`XStream(ReflectionProvider reflectionProvider, Mapper mapper, HierarchicalStreamDriver driver)` Deprecated. since 1.3, use `#XStream(ReflectionProvider, HierarchicalStreamDriver, Mapper, ClassLoader)` instead

Method Summary
`void` | `addDefaultImplementation(Class defaultImplementation, Class ofType)` Associate a default implementation of a class with an object.
`void` | `addImmutableType(Class type)` Add immutable types.
`void` | `addImplicitCollection(Class ownerType, String fieldName)` Adds a default implicit collection which is used for any unmapped XML tag.
`void` | `addImplicitCollection(Class ownerType, String fieldName, Class itemType)` Adds implicit collection which is used for all items of the given itemType.
`void` | `addImplicitCollection(Class ownerType, String fieldName, String itemFieldName, Class itemType)` Adds implicit collection which is used for all items of the given element name defined by itemFieldName.
`void` | `alias(String name, Class type)` Alias a Class to a shorter name to be used in XML elements.
`void` | `alias(String name, Class type, Class defaultImplementation)` Alias a Class to a shorter name to be used in XML elements.
`void` | `aliasAttribute(Class definedIn, String attributeName, String alias)` Create an alias for an attribute.
`void` | `aliasAttribute(String alias, String attributeName)` Create an alias for an attribute
`void` | `aliasField(String alias, Class definedIn, String fieldName)` Create an alias for a field name.
`void` | `aliasPackage(String name, String pkgName)` Alias a package to a shorter name to be used in XML elements.
`void` | `aliasSystemAttribute(String alias, String systemAttributeName)` Create an alias for a system attribute.
`void` | `aliasType(String name, Class type)` Alias a type to a shorter name to be used in XML elements.
`void` | `autodetectAnnotations(boolean mode)` Set the auto-detection mode of the AnnotationMapper.
`ObjectInputStream` | `createObjectInputStream(HierarchicalStreamReader reader)` Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream.
`ObjectInputStream` | `createObjectInputStream(InputStream in)` Creates an ObjectInputStream that deserializes a stream of objects from an InputStream using XStream.
`ObjectInputStream` | `createObjectInputStream(Reader xmlReader)` Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream.
`ObjectOutputStream` | `createObjectOutputStream(HierarchicalStreamWriter writer)` Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
`ObjectOutputStream` | `createObjectOutputStream(HierarchicalStreamWriter writer, String rootNodeName)` Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
`ObjectOutputStream` | `createObjectOutputStream(OutputStream out)` Creates an ObjectOutputStream that serializes a stream of objects to the OutputStream using XStream.
`ObjectOutputStream` | `createObjectOutputStream(OutputStream out, String rootNodeName)` Creates an ObjectOutputStream that serializes a stream of objects to the OutputStream using XStream.
`ObjectOutputStream` | `createObjectOutputStream(Writer writer)` Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
`ObjectOutputStream` | `createObjectOutputStream(Writer writer, String rootNodeName)` Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.
`Object` | `fromXML(InputStream input)` Deserialize an object from an XML InputStream.
`Object` | `fromXML(InputStream xml, Object root)` Deserialize an object from an XML InputStream, populating the fields of the given root object instead of instantiating a new one.
`Object` | `fromXML(Reader xml)` Deserialize an object from an XML Reader.
`Object` | `fromXML(Reader xml, Object root)` Deserialize an object from an XML Reader, populating the fields of the given root object instead of instantiating a new one.
`Object` | `fromXML(String xml)` Deserialize an object from an XML String.
`Object` | `fromXML(String xml, Object root)` Deserialize an object from an XML String, populating the fields of the given root object instead of instantiating a new one.
`ClassLoader` | `getClassLoader()` Retrieve the ClassLoader XStream uses to load classes.
`ClassMapper` | `getClassMapper()` Deprecated. As of 1.2, use `getMapper()`
`ConverterLookup` | `getConverterLookup()`
`Mapper` | `getMapper()` Retrieve the `Mapper`.
`ReflectionProvider` | `getReflectionProvider()` Retrieve the `ReflectionProvider` in use.
`void` | `marshal(Object obj, HierarchicalStreamWriter writer)` Serialize and object to a hierarchical data structure (such as XML).
`void` | `marshal(Object obj, HierarchicalStreamWriter writer, DataHolder dataHolder)` Serialize and object to a hierarchical data structure (such as XML).
`DataHolder` | `newDataHolder()` Create a DataHolder that can be used to pass data to the converters.
`void` | `omitField(Class definedIn, String fieldName)` Prevents a field from being serialized.
`void` | `processAnnotations(Class type)` Process the annotations of the given type and configure the XStream.
`void` | `processAnnotations(Class[] types)` Process the annotations of the given types and configure the XStream.
`void` | `registerConverter(Converter converter)`
`void` | `registerConverter(Converter converter, int priority)`
`void` | `registerConverter(SingleValueConverter converter)`
`void` | `registerConverter(SingleValueConverter converter, int priority)`
`void` | `registerLocalConverter(Class definedIn, String fieldName, Converter converter)` Register a local `Converter` for a field.
`void` | `registerLocalConverter(Class definedIn, String fieldName, SingleValueConverter converter)` Register a local `SingleValueConverter` for a field.
`void` | `setClassLoader(ClassLoader classLoader)` Change the ClassLoader XStream uses to load classes.
`void` | `setMarshallingStrategy(MarshallingStrategy marshallingStrategy)`
`void` | `setMode(int mode)` Change mode for dealing with duplicate references.
`protected void` | `setupAliases()`
`protected void` | `setupConverters()`
`protected void` | `setupDefaultImplementations()`
`protected void` | `setupImmutableTypes()`
`String` | `toXML(Object obj)` Serialize an object to a pretty-printed XML String.
`void` | `toXML(Object obj, OutputStream out)` Serialize an object to the given OutputStream as pretty-printed XML.
`void` | `toXML(Object obj, Writer out)` Serialize an object to the given Writer as pretty-printed XML.
`Object` | `unmarshal(HierarchicalStreamReader reader)` Deserialize an object from a hierarchical data structure (such as XML).
`Object` | `unmarshal(HierarchicalStreamReader reader, Object root)` Deserialize an object from a hierarchical data structure (such as XML), populating the fields of the given root object instead of instantiating a new one.
`Object` | `unmarshal(HierarchicalStreamReader reader, Object root, DataHolder dataHolder)` Deserialize an object from a hierarchical data structure (such as XML).
`void` | `useAttributeFor(Class type)` Use an attribute for an arbitrary type.
`void` | `useAttributeFor(Class definedIn, String fieldName)` Use an attribute for a field declared in a specific type.
`void` | `useAttributeFor(String fieldName, Class type)` Use an attribute for a field or a specific type.
`protected boolean` | `useXStream11XmlFriendlyMapper()`
`protected MapperWrapper` | `wrapMapper(MapperWrapper next)`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### NO_REFERENCES

    public static final int NO_REFERENCES

See Also:
  Constant Field Values

### ID_REFERENCES

    public static final int ID_REFERENCES

See Also:
  Constant Field Values

### XPATH_RELATIVE_REFERENCES

    public static final int XPATH_RELATIVE_REFERENCES

See Also:
  Constant Field Values

### XPATH_ABSOLUTE_REFERENCES

    public static final int XPATH_ABSOLUTE_REFERENCES

See Also:
  Constant Field Values

### XPATH_REFERENCES

    public static final int XPATH_REFERENCES

  Deprecated. since 1.2, use `XPATH_RELATIVE_REFERENCES` or `XPATH_ABSOLUTE_REFERENCES` instead.
  See Also:
    Constant Field Values

### PRIORITY_VERY_HIGH

    public static final int PRIORITY_VERY_HIGH

See Also:
  Constant Field Values

### PRIORITY_NORMAL

    public static final int PRIORITY_NORMAL

See Also:
  Constant Field Values

### PRIORITY_LOW

    public static final int PRIORITY_LOW

See Also:
  Constant Field Values

### PRIORITY_VERY_LOW

    public static final int PRIORITY_VERY_LOW

See Also:
  Constant Field Values

Constructor Detail

### XStream

    public XStream()

  Constructs a default XStream. The instance will use the `XppDriver` as default and tries to determine the best match for the `ReflectionProvider` on its own.

  Throws:
    `XStream.InitializationException` - in case of an initialization problem

### XStream

    public XStream(ReflectionProvider reflectionProvider)

  Constructs an XStream with a special `ReflectionProvider`. The instance will use the `XppDriver` as default.

  Throws:
    `XStream.InitializationException` - in case of an initialization problem

### XStream

    public XStream(HierarchicalStreamDriver hierarchicalStreamDriver)

  Constructs an XStream with a special `HierarchicalStreamDriver`. The instance will tries to determine the best match for the `ReflectionProvider` on its own.

  Throws:
    `XStream.InitializationException` - in case of an initialization problem

### XStream

    public XStream(ReflectionProvider reflectionProvider,
                   HierarchicalStreamDriver hierarchicalStreamDriver)

  Constructs an XStream with a special `HierarchicalStreamDriver` and `ReflectionProvider`.

  Throws:
    `XStream.InitializationException` - in case of an initialization problem

### XStream

    public XStream(ReflectionProvider reflectionProvider,
                   ClassMapper classMapper,
                   HierarchicalStreamDriver driver)

  Deprecated. As of 1.2, use `XStream(ReflectionProvider, Mapper, HierarchicalStreamDriver)`

### XStream

    public XStream(ReflectionProvider reflectionProvider,
                   ClassMapper classMapper,
                   HierarchicalStreamDriver driver,
                   String classAttributeIdentifier)

  Deprecated. As of 1.2, use `XStream(ReflectionProvider, Mapper, HierarchicalStreamDriver)` and register classAttributeIdentifier as alias

### XStream

    public XStream(ReflectionProvider reflectionProvider,
                   Mapper mapper,
                   HierarchicalStreamDriver driver)

  Deprecated. since 1.3, use `#XStream(ReflectionProvider, HierarchicalStreamDriver, Mapper, ClassLoader)` instead

  Constructs an XStream with a special `HierarchicalStreamDriver` and `ReflectionProvider` and additionally with a prepared `Mapper`.

  Throws:
    `XStream.InitializationException` - in case of an initialization problem

### XStream

    public XStream(ReflectionProvider reflectionProvider,
                   HierarchicalStreamDriver driver,
                   ClassLoader classLoader)

  Constructs an XStream with a special `HierarchicalStreamDriver` and `ReflectionProvider` and additionally with a prepared `ClassLoader` to use.

  Throws:
    `XStream.InitializationException` - in case of an initialization problem
  Since:
    1.3

### XStream

    public XStream(ReflectionProvider reflectionProvider,
                   HierarchicalStreamDriver driver,
                   ClassLoader classLoader,
                   Mapper mapper)

  Constructs an XStream with a special `HierarchicalStreamDriver` and `ReflectionProvider` and additionally with a prepared `Mapper` and the `ClassLoader` in use.

  Note, if the class loader should be changed later again, you should provide a `ClassLoaderReference` as `ClassLoader` that is also use in the `Mapper` chain.

  Throws:
    `XStream.InitializationException` - in case of an initialization problem
  Since:
    1.3

### XStream

    public XStream(ReflectionProvider reflectionProvider,
                   HierarchicalStreamDriver driver,
                   ClassLoader classLoader,
                   Mapper mapper,
                   ConverterLookup converterLookup,
                   ConverterRegistry converterRegistry)

  Constructs an XStream with a special `HierarchicalStreamDriver`, `ReflectionProvider`, a prepared `Mapper` and the `ClassLoader` in use and an own `ConverterRegistry`.

  Note, if the class loader should be changed later again, you should provide a `ClassLoaderReference` as `ClassLoader` that is also use in the `Mapper` chain.

  Throws:
    `XStream.InitializationException` - in case of an initialization problem
  Since:
    1.3

Method Detail

### wrapMapper

    protected MapperWrapper wrapMapper(MapperWrapper next)

### useXStream11XmlFriendlyMapper

    protected boolean useXStream11XmlFriendlyMapper()

### setupAliases

    protected void setupAliases()

### setupDefaultImplementations

    protected void setupDefaultImplementations()

### setupConverters

    protected void setupConverters()

### setupImmutableTypes

    protected void setupImmutableTypes()

### setMarshallingStrategy

    public void setMarshallingStrategy(MarshallingStrategy marshallingStrategy)

### toXML

    public String toXML(Object obj)

  Serialize an object to a pretty-printed XML String.

  Throws:
    `XStreamException` - if the object cannot be serialized

### toXML

    public void toXML(Object obj,
                      Writer out)

  Serialize an object to the given Writer as pretty-printed XML. The Writer will be flushed afterwards and in case of an exception.

  Throws:
    `XStreamException` - if the object cannot be serialized

### toXML

    public void toXML(Object obj,
                      OutputStream out)

  Serialize an object to the given OutputStream as pretty-printed XML. The OutputStream will be flushed afterwards and in case of an exception.

  Throws:
    `XStreamException` - if the object cannot be serialized

### marshal

    public void marshal(Object obj,
                        HierarchicalStreamWriter writer)

  Serialize and object to a hierarchical data structure (such as XML).

  Throws:
    `XStreamException` - if the object cannot be serialized

### marshal

    public void marshal(Object obj,
                        HierarchicalStreamWriter writer,
                        DataHolder dataHolder)

  Serialize and object to a hierarchical data structure (such as XML).

  Parameters:
    `dataHolder` - Extra data you can use to pass to your converters. Use this as you want. If not present, XStream shall create one lazily as needed.
  Throws:
    `XStreamException` - if the object cannot be serialized

### fromXML

    public Object fromXML(String xml)

  Deserialize an object from an XML String.

  Throws:
    `XStreamException` - if the object cannot be deserialized

### fromXML

    public Object fromXML(Reader xml)

  Deserialize an object from an XML Reader.

  Throws:
    `XStreamException` - if the object cannot be deserialized

### fromXML

    public Object fromXML(InputStream input)

  Deserialize an object from an XML InputStream.

  Throws:
    `XStreamException` - if the object cannot be deserialized

### fromXML

    public Object fromXML(String xml,
                          Object root)

  Deserialize an object from an XML String, populating the fields of the given root object instead of instantiating a new one. Note, that this is a special use case! With the ReflectionConverter XStream will write directly into the raw memory area of the existing object. Use with care!

  Throws:
    `XStreamException` - if the object cannot be deserialized

### fromXML

    public Object fromXML(Reader xml,
                          Object root)

  Deserialize an object from an XML Reader, populating the fields of the given root object instead of instantiating a new one. Note, that this is a special use case! With the ReflectionConverter XStream will write directly into the raw memory area of the existing object. Use with care!

  Throws:
    `XStreamException` - if the object cannot be deserialized

### fromXML

    public Object fromXML(InputStream xml,
                          Object root)

  Deserialize an object from an XML InputStream, populating the fields of the given root object instead of instantiating a new one. Note, that this is a special use case! With the ReflectionConverter XStream will write directly into the raw memory area of the existing object. Use with care!

  Throws:
    `XStreamException` - if the object cannot be deserialized

### unmarshal

    public Object unmarshal(HierarchicalStreamReader reader)

  Deserialize an object from a hierarchical data structure (such as XML).

  Throws:
    `XStreamException` - if the object cannot be deserialized

### unmarshal

    public Object unmarshal(HierarchicalStreamReader reader,
                            Object root)

  Deserialize an object from a hierarchical data structure (such as XML), populating the fields of the given root object instead of instantiating a new one. Note, that this is a special use case! With the ReflectionConverter XStream will write directly into the raw memory area of the existing object. Use with care!

  Throws:
    `XStreamException` - if the object cannot be deserialized

### unmarshal

    public Object unmarshal(HierarchicalStreamReader reader,
                            Object root,
                            DataHolder dataHolder)

  Deserialize an object from a hierarchical data structure (such as XML).

  Parameters:
    `root` - If present, the passed in object will have its fields populated, as opposed to XStream creating a new instance. Note, that this is a special use case! With the ReflectionConverter XStream will write directly into the raw memory area of the existing object. Use with care!
    `dataHolder` - Extra data you can use to pass to your converters. Use this as you want. If not present, XStream shall create one lazily as needed.
  Throws:
    `XStreamException` - if the object cannot be deserialized

### alias

    public void alias(String name,
                      Class type)

  Alias a Class to a shorter name to be used in XML elements.

  Parameters:
    `name` - Short name
    `type` - Type to be aliased
  Throws:
    `XStream.InitializationException` - if no `ClassAliasingMapper` is available

### aliasType

    public void aliasType(String name,
                          Class type)

  Alias a type to a shorter name to be used in XML elements. Any class that is assignable to this type will be aliased to the same name.

  Parameters:
    `name` - Short name
    `type` - Type to be aliased
  Throws:
    `XStream.InitializationException` - if no `ClassAliasingMapper` is available
  Since:
    1.2

### alias

    public void alias(String name,
                      Class type,
                      Class defaultImplementation)

  Alias a Class to a shorter name to be used in XML elements.

  Parameters:
    `name` - Short name
    `type` - Type to be aliased
    `defaultImplementation` - Default implementation of type to use if no other specified.
  Throws:
    `XStream.InitializationException` - if no `DefaultImplementationsMapper` or no `ClassAliasingMapper` is available

### aliasPackage

    public void aliasPackage(String name,
                             String pkgName)

  Alias a package to a shorter name to be used in XML elements.

  Parameters:
    `name` - Short name
    `pkgName` - package to be aliased
  Throws:
    `XStream.InitializationException` - if no `DefaultImplementationsMapper` or no `PackageAliasingMapper` is available
  Since:
    1.3.1

### aliasField

    public void aliasField(String alias,
                           Class definedIn,
                           String fieldName)

  Create an alias for a field name.

  Parameters:
    `alias` - the alias itself
    `definedIn` - the type that declares the field
    `fieldName` - the name of the field
  Throws:
    `XStream.InitializationException` - if no `FieldAliasingMapper` is available

### aliasAttribute

    public void aliasAttribute(String alias,
                               String attributeName)

  Create an alias for an attribute

  Parameters:
    `alias` - the alias itself
    `attributeName` - the name of the attribute
  Throws:
    `XStream.InitializationException` - if no `AttributeAliasingMapper` is available

### aliasSystemAttribute

    public void aliasSystemAttribute(String alias,
                                     String systemAttributeName)

  Create an alias for a system attribute. XStream will not write a system attribute if its alias is set to `null`. However, this is not reversible, i.e. deserialization of the result is likely to fail afterwards and will not produce an object equal to the originally written one.

  Parameters:
    `alias` - the alias itself (may be `null`)
    `systemAttributeName` - the name of the system attribute
  Throws:
    `XStream.InitializationException` - if no `SystemAttributeAliasingMapper` is available
  Since:
    1.3.1

### aliasAttribute

    public void aliasAttribute(Class definedIn,
                               String attributeName,
                               String alias)

  Create an alias for an attribute.

  Parameters:
    `definedIn` - the type where the attribute is defined
    `attributeName` - the name of the attribute
    `alias` - the alias itself
  Throws:
    `XStream.InitializationException` - if no `AttributeAliasingMapper` is available
  Since:
    1.2.2

### useAttributeFor

    public void useAttributeFor(String fieldName,
                                Class type)

  Use an attribute for a field or a specific type.

  Parameters:
    `fieldName` - the name of the field
    `type` - the Class of the type to be rendered as XML attribute
  Throws:
    `XStream.InitializationException` - if no `AttributeMapper` is available
  Since:
    1.2

### useAttributeFor

    public void useAttributeFor(Class definedIn,
                                String fieldName)

  Use an attribute for a field declared in a specific type.

  Parameters:
    `fieldName` - the name of the field
    `definedIn` - the Class containing such field
  Throws:
    `XStream.InitializationException` - if no `AttributeMapper` is available
  Since:
    1.2.2

### useAttributeFor

    public void useAttributeFor(Class type)

  Use an attribute for an arbitrary type.

  Parameters:
    `type` - the Class of the type to be rendered as XML attribute
  Throws:
    `XStream.InitializationException` - if no `AttributeMapper` is available
  Since:
    1.2

### addDefaultImplementation

    public void addDefaultImplementation(Class defaultImplementation,
                                         Class ofType)

  Associate a default implementation of a class with an object. Whenever XStream encounters an instance of this type, it will use the default implementation instead. For example, java.util.ArrayList is the default implementation of java.util.List.

  Parameters:
    `defaultImplementation` -
    `ofType` -
  Throws:
    `XStream.InitializationException` - if no `DefaultImplementationsMapper` is available

### addImmutableType

    public void addImmutableType(Class type)

  Add immutable types. The value of the instances of these types will always be written into the stream even if they appear multiple times.

  Throws:
    `XStream.InitializationException` - if no `ImmutableTypesMapper` is available

### registerConverter

    public void registerConverter(Converter converter)

### registerConverter

    public void registerConverter(Converter converter,
                                  int priority)

### registerConverter

    public void registerConverter(SingleValueConverter converter)

### registerConverter

    public void registerConverter(SingleValueConverter converter,
                                  int priority)

### registerLocalConverter

    public void registerLocalConverter(Class definedIn,
                                       String fieldName,
                                       Converter converter)

  Register a local `Converter` for a field.

  Parameters:
    `definedIn` - the class type the field is defined in
    `fieldName` - the field name
    `converter` - the converter to use
  Since:
    1.3

### registerLocalConverter

    public void registerLocalConverter(Class definedIn,
                                       String fieldName,
                                       SingleValueConverter converter)

  Register a local `SingleValueConverter` for a field.

  Parameters:
    `definedIn` - the class type the field is defined in
    `fieldName` - the field name
    `converter` - the converter to use
  Since:
    1.3

### getClassMapper

    public ClassMapper getClassMapper()

  Deprecated. As of 1.2, use `getMapper()`

  Throws:
    `ClassCastException` - if mapper is not really a deprecated `ClassMapper` instance

### getMapper

    public Mapper getMapper()

  Retrieve the `Mapper`. This is by default a chain of `MapperWrappers`.

  Returns:
    the mapper
  Since:
    1.2

### getReflectionProvider

    public ReflectionProvider getReflectionProvider()

  Retrieve the `ReflectionProvider` in use.

  Returns:
    the mapper
  Since:
    1.2.1

### getConverterLookup

    public ConverterLookup getConverterLookup()

### setMode

    public void setMode(int mode)

  Change mode for dealing with duplicate references. Valid values are `XPATH_ABSOLUTE_REFERENCES`, `XPATH_RELATIVE_REFERENCES`, `XStream.ID_REFERENCES` and `XStream.NO_REFERENCES`.

  Throws:
    `IllegalArgumentException` - if the mode is not one of the declared types
  See Also:
    `XPATH_ABSOLUTE_REFERENCES`, `XPATH_RELATIVE_REFERENCES`, `ID_REFERENCES`, `NO_REFERENCES`

### addImplicitCollection

    public void addImplicitCollection(Class ownerType,
                                      String fieldName)

  Adds a default implicit collection which is used for any unmapped XML tag.

  Parameters:
    `ownerType` - class owning the implicit collection
    `fieldName` - name of the field in the ownerType. This field must be a concrete collection type or matching the default implementation type of the collection type.

### addImplicitCollection

    public void addImplicitCollection(Class ownerType,
                                      String fieldName,
                                      Class itemType)

  Adds implicit collection which is used for all items of the given itemType.

  Parameters:
    `ownerType` - class owning the implicit collection
    `fieldName` - name of the field in the ownerType. This field must be a concrete collection type or matching the default implementation type of the collection type.
    `itemType` - type of the items to be part of this collection.
  Throws:
    `XStream.InitializationException` - if no `ImplicitCollectionMapper` is available

### addImplicitCollection

    public void addImplicitCollection(Class ownerType,
                                      String fieldName,
                                      String itemFieldName,
                                      Class itemType)

  Adds implicit collection which is used for all items of the given element name defined by itemFieldName.

  Parameters:
    `ownerType` - class owning the implicit collection
    `fieldName` - name of the field in the ownerType. This field must be a concrete collection type or matching the default implementation type of the collection type.
    `itemFieldName` - element name of the implicit collection
    `itemType` - item type to be aliases be the itemFieldName
  Throws:
    `XStream.InitializationException` - if no `ImplicitCollectionMapper` is available

### newDataHolder

    public DataHolder newDataHolder()

  Create a DataHolder that can be used to pass data to the converters. The DataHolder is provided with a call to `marshal(Object, HierarchicalStreamWriter, DataHolder)` or `unmarshal(HierarchicalStreamReader, Object, DataHolder)`.

  Returns:
    a new `DataHolder`

### createObjectOutputStream

    public ObjectOutputStream createObjectOutputStream(Writer writer)
                                                throws IOException

  Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.

  To change the name of the root element (from <object-stream>), use `createObjectOutputStream(java.io.Writer, String)`.

  Throws:
    `IOException`
  Since:
    1.0.3
  See Also:
    `createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)`, `createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)`

### createObjectOutputStream

    public ObjectOutputStream createObjectOutputStream(HierarchicalStreamWriter writer)
                                                throws IOException

  Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.

  To change the name of the root element (from <object-stream>), use `createObjectOutputStream(java.io.Writer, String)`.

  Throws:
    `IOException`
  Since:
    1.0.3
  See Also:
    `createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)`, `createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)`

### createObjectOutputStream

    public ObjectOutputStream createObjectOutputStream(Writer writer,
                                                       String rootNodeName)
                                                throws IOException

  Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.

  Throws:
    `IOException`
  Since:
    1.0.3
  See Also:
    `createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)`, `createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)`

### createObjectOutputStream

    public ObjectOutputStream createObjectOutputStream(OutputStream out)
                                                throws IOException

  Creates an ObjectOutputStream that serializes a stream of objects to the OutputStream using XStream.

  To change the name of the root element (from <object-stream>), use `createObjectOutputStream(java.io.Writer, String)`.

  Throws:
    `IOException`
  Since:
    1.3
  See Also:
    `createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)`, `createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)`

### createObjectOutputStream

    public ObjectOutputStream createObjectOutputStream(OutputStream out,
                                                       String rootNodeName)
                                                throws IOException

  Creates an ObjectOutputStream that serializes a stream of objects to the OutputStream using XStream.

  Throws:
    `IOException`
  Since:
    1.3
  See Also:
    `createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)`, `createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)`

### createObjectOutputStream

    public ObjectOutputStream createObjectOutputStream(HierarchicalStreamWriter writer,
                                                       String rootNodeName)
                                                throws IOException

  Creates an ObjectOutputStream that serializes a stream of objects to the writer using XStream.

  Because an ObjectOutputStream can contain multiple items and XML only allows a single root node, the stream must be written inside an enclosing node.

  It is necessary to call ObjectOutputStream.close() when done, otherwise the stream will be incomplete.

  ### Example

        ObjectOutputStream out = xstream.createObjectOutputStream(aWriter, "things");
         out.writeInt(123);
         out.writeObject("Hello");
         out.writeObject(someObject)
         out.close();

  Parameters:
    `writer` - The writer to serialize the objects to.
    `rootNodeName` - The name of the root node enclosing the stream of objects.
  Throws:
    `IOException`
  Since:
    1.0.3
  See Also:
    `createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)`

### createObjectInputStream

    public ObjectInputStream createObjectInputStream(Reader xmlReader)
                                              throws IOException

  Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream.

  Throws:
    `IOException`
  Since:
    1.0.3
  See Also:
    `createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)`, `createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)`

### createObjectInputStream

    public ObjectInputStream createObjectInputStream(InputStream in)
                                              throws IOException

  Creates an ObjectInputStream that deserializes a stream of objects from an InputStream using XStream.

  Throws:
    `IOException`
  Since:
    1.3
  See Also:
    `createObjectInputStream(com.thoughtworks.xstream.io.HierarchicalStreamReader)`, `createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)`

### createObjectInputStream

    public ObjectInputStream createObjectInputStream(HierarchicalStreamReader reader)
                                              throws IOException

  Creates an ObjectInputStream that deserializes a stream of objects from a reader using XStream.

  ### Example

       ObjectInputStream in = xstream.createObjectOutputStream(aReader);
       int a = out.readInt();
       Object b = out.readObject();
       Object c = out.readObject();

  Throws:
    `IOException`
  Since:
    1.0.3
  See Also:
    `createObjectOutputStream(com.thoughtworks.xstream.io.HierarchicalStreamWriter, String)`

### setClassLoader

    public void setClassLoader(ClassLoader classLoader)

  Change the ClassLoader XStream uses to load classes. Creating an XStream instance it will register for all kind of classes and types of the current JDK, but not for any 3rd party type. To ensure that all other types are loaded with your classloader, you should call this method as early as possible - or consider to provide the classloader directly in the constructor.

  Since:
    1.1.1

### getClassLoader

    public ClassLoader getClassLoader()

  Retrieve the ClassLoader XStream uses to load classes.

  Since:
    1.1.1

### omitField

    public void omitField(Class definedIn,
                          String fieldName)

  Prevents a field from being serialized. To omit a field you must always provide the declaring type and not necessarily the type that is converted.

  Throws:
    `XStream.InitializationException` - if no `FieldAliasingMapper` is available
  Since:
    1.1.3

### processAnnotations

    public void processAnnotations(Class[] types)

  Process the annotations of the given types and configure the XStream.

  Parameters:
    `types` - the types with XStream annotations
  Since:
    1.3

### processAnnotations

    public void processAnnotations(Class type)

  Process the annotations of the given type and configure the XStream. A call of this method will automatically turn the auto-detection mode for annotations off.

  Parameters:
    `type` - the type with XStream annotations
  Since:
    1.3

### autodetectAnnotations

    public void autodetectAnnotations(boolean mode)

  Set the auto-detection mode of the AnnotationMapper. Note that auto-detection implies that the XStream is configured while it is processing the XML steams. This is a potential concurrency problem. Also is it technically not possible to detect all class aliases at deserialization. You have been warned!

  Parameters:
    `mode` - `true` if annotations are auto-detected
  Since:
    1.3

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004-2008 XStream. All Rights Reserved.