Package jenkins.util.xstream

Class XStreamDOM

java.lang.Object
jenkins.util.xstream.XStreamDOM
public class XStreamDOM extends Object
XML DOM like structure to preserve a portion of XStream data as-is, so that you can process it later in a separate XStream call.

This object captures a subset of XML infoset that XStream understands. Namely, no XML namespace, no mixed content.

You use it as a field in your class (that itself participates in an XStream persistence), and have it receive the portion of that XML. Then later you can use unmarshal(XStream) to convert this sub-tree to an object with a possibly separate XStream instance.

The reverse operation is from(XStream, Object) method, which marshals an object into XStreamDOM.

You can also use this class to parse an entire XML document into a DOM like tree with from(HierarchicalStreamReader) and writeTo(HierarchicalStreamWriter). These two methods support variants that accept other forms.

Whereas the above methods read from and write to HierarchicalStreamReader and, HierarchicalStreamWriter, we can also create HierarchicalStreamReader that read from DOM and HierarchicalStreamWriter that writes to DOM. See newReader() and newWriter() for those operations.

XStreamDOM as a field of another XStream-enabled class: XStreamDOM can be used as a type of a field of another class that's itself XStream-enabled, such as this: 

 class Foo {
     XStreamDOM bar;
 }
With the following XML: 

 <foo>
   <bar>
     <payload>
       ...
     </payload>
   </bar>
 </foo>

The XStreamDOM object in the bar field will have the "payload" element in its tag name (which means the bar element cannot have multiple children.)

XStream and name escaping: Because XStream wants to use letters like '$' that's not legal as a name char in XML, the XML data model that it thinks of (unescaped) is actually translated into the actual XML-compliant infoset via XmlFriendlyReplacer. This translation is done by HierarchicalStreamReader and HierarchicalStreamWriter, transparently from Converters. In XStreamDOM, we'd like to hold the XML infoset (escaped form, in XStream speak), so in our XStreamDOM.ConverterImpl we go out of the way to cancel out this effect.

Since:
1.473
Author:
Kohsuke Kawaguchi

  • Field Details

    • REPLACER

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) @RestrictedSince("2.301") public static final com.thoughtworks.xstream.io.xml.XmlFriendlyReplacer REPLACER

  • Constructor Details

  • Method Details

    • getTagName

      public String getTagName()

    • unmarshal

      public <T> T unmarshal(com.thoughtworks.xstream.XStream xs)
      Unmarshals this DOM into an object via the given XStream.

    • unmarshal

      public <T> T unmarshal(com.thoughtworks.xstream.XStream xs, T root)

    • expandMacro

      public XStreamDOM expandMacro(VariableResolver<String> vars)
      Recursively expands the variables in text and attribute values and return the new DOM. The expansion uses Util.replaceMacro(String, VariableResolver), so any unresolved references will be left as-is.

    • getAttribute

      public String getAttribute(String name)

    • getAttributeCount

      public int getAttributeCount()

    • getAttribute

      public String getAttribute(int index)

    • getValue

      public String getValue()

    • getChildren

      public List<XStreamDOM> getChildren()

    • newReader

      public com.thoughtworks.xstream.io.HierarchicalStreamReader newReader()
      Returns a new HierarchicalStreamReader that reads a sub-tree rooted at this node.

    • newWriter

      public static XStreamDOM.WriterImpl newWriter()
      Returns a new HierarchicalStreamWriter for marshalling objects into XStreamDOM. After the writer receives the calls, call XStreamDOM.WriterImpl.getOutput() to obtain the populated tree.

    • writeTo

      public void writeTo(OutputStream os)
      Writes this XStreamDOM into OutputStream.

    • writeTo

      public void writeTo(Writer w)

    • writeTo

      public void writeTo(com.thoughtworks.xstream.io.HierarchicalStreamWriter w)

    • from

      public static XStreamDOM from(com.thoughtworks.xstream.XStream xs, Object obj)
      Marshals the given object with the given XStream into XStreamDOM and return it.

    • from

      public static XStreamDOM from(InputStream in)

    • from

      public static XStreamDOM from(Reader in)

    • from

      public static XStreamDOM from(com.thoughtworks.xstream.io.HierarchicalStreamReader in)

    • getAttributeMap

      public Map<String,String> getAttributeMap()