Package jenkins.util.xstream

Class 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 Detail

      • REPLACER

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

    • Method Detail

      • 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)

      • getAttribute

        public String getAttribute​(String name)

      • getAttributeCount

        public int getAttributeCount()

      • getAttribute

        public String getAttribute​(int index)

      • getValue

        public String getValue()

      • newReader

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

      • 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​(com.thoughtworks.xstream.io.HierarchicalStreamReader in)