org.kohsuke.maven.rewrite

Class XmlPatcher

java.lang.Object

org.kohsuke.maven.rewrite.XmlPatcher

All Implemented Interfaces:

Iterator, javax.xml.stream.XMLEventReader

public class XmlPatcher
extends Object
implements javax.xml.stream.XMLEventReader

High-fidelity XML patch editor.

XmlPatcher uses StAX API and provides an API for micro-patching XML file (such as changing text, adding/removing a tag, etc.) without altering the original XML file unnecessarily as much as possible. For example, comments, whitespaces between attributes, indentation, and so on are kept intact.

The patching of XML file is primarily done via Mark, which represents a range of text in XML. Mark can be created from mark(), or by combining existing marks (such as Mark.to(Mark). The caller can retrieve the text inside Mark and replace them.

Active Marks are tracked by XmlPatcher so that when one mark changes its content, the positions of the other marks are updated to stick to the text they are supposed to be pointing. Because of this, the caller should stick to a bounded number of marks, or use Mark.clear() to throw away unneeded marks.

While this class intends to provide high-fidelity and preserves as much of the original XML as possible, the StAX API (JSR-173) has inherent limitation. For example, the StAX API specifies that CR characters will be stripped. Current implementations do not keep " and ' characters consistent.

Author:

Stephen Connolly, Kohsuke Kawaguchi

Constructor Summary

Constructors

Constructor and Description
XmlPatcher(File f)
XmlPatcher(InputStream in)
XmlPatcher(StringBuilder xml)

Method Summary

Methods

Modifier and Type	Method and Description
StringBuilder	asStringBuilder() Returns a copy of the backing string buffer.
void	close()
String	getBetween(Mark a, Mark b)
String	getElementText()
Mark	getLast() Returns a mark that points to the last returned XMLEvent
XmlPath	getPath() Gets the current location in the XML document.
String	getPeekVerbatim() Returns the verbatim text of the element returned by peek().
Object	getProperty(String name)
boolean	hasNext()
boolean	isModified() Getter for property 'modified'.
Mark	mark() Creates a new mark.
Object	next()
javax.xml.stream.events.XMLEvent	nextEvent()
javax.xml.stream.events.XMLEvent	nextTag()
javax.xml.stream.events.XMLEvent	peek()
void	remove()
void	replace(String replacement) Replaces the current element with the replacement text.
void	replaceBetween(Mark a, Mark b, String replacement) Replaces all content between two marks with the replacement text.
void	rewind() Rewind to the start so we can run through again.
boolean	scan(XmlVisitor v)
void	setFactory(javax.xml.stream.XMLInputFactory factory)
void	writeTo(File f)

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlPatcher

public XmlPatcher(StringBuilder xml)

XmlPatcher

public XmlPatcher(File f)
           throws IOException

Throws:

IOException

XmlPatcher

public XmlPatcher(InputStream in)
           throws IOException

Throws:

IOException

Method Detail

setFactory

public void setFactory(javax.xml.stream.XMLInputFactory factory)

rewind

public void rewind()
            throws javax.xml.stream.XMLStreamException

Rewind to the start so we can run through again.

Throws:

javax.xml.stream.XMLStreamException - when things go wrong.

getPath

public XmlPath getPath()

Gets the current location in the XML document.

scan

public boolean scan(XmlVisitor v)
             throws javax.xml.stream.XMLStreamException

Throws:

javax.xml.stream.XMLStreamException

isModified

public boolean isModified()

Getter for property 'modified'.

Returns:

Value for property 'modified'.

next

public Object next()

Specified by:

next in interface Iterator

remove

public void remove()

Specified by:

remove in interface Iterator

nextEvent

public javax.xml.stream.events.XMLEvent nextEvent()
                                           throws javax.xml.stream.XMLStreamException

Specified by:

nextEvent in interface javax.xml.stream.XMLEventReader

Throws:

javax.xml.stream.XMLStreamException

peek

public javax.xml.stream.events.XMLEvent peek()
                                      throws javax.xml.stream.XMLStreamException

Specified by:

peek in interface javax.xml.stream.XMLEventReader

Throws:

javax.xml.stream.XMLStreamException

getElementText

public String getElementText()
                      throws javax.xml.stream.XMLStreamException

Specified by:

getElementText in interface javax.xml.stream.XMLEventReader

Throws:

javax.xml.stream.XMLStreamException

nextTag

public javax.xml.stream.events.XMLEvent nextTag()
                                         throws javax.xml.stream.XMLStreamException

Specified by:

nextTag in interface javax.xml.stream.XMLEventReader

Throws:

javax.xml.stream.XMLStreamException

getProperty

public Object getProperty(String name)

Specified by:

getProperty in interface javax.xml.stream.XMLEventReader

close

public void close()
           throws javax.xml.stream.XMLStreamException

Specified by:

close in interface javax.xml.stream.XMLEventReader

Throws:

javax.xml.stream.XMLStreamException

asStringBuilder

public StringBuilder asStringBuilder()

Returns a copy of the backing string buffer.

Returns:

a copy of the backing string buffer.

getPeekVerbatim

public String getPeekVerbatim()

Returns the verbatim text of the element returned by peek().

Returns:

the verbatim text of the element returned by peek().

hasNext

public boolean hasNext()

Specified by:

hasNext in interface Iterator

Specified by:

hasNext in interface javax.xml.stream.XMLEventReader

getLast

public Mark getLast()

Returns a mark that points to the last returned XMLEvent

mark

public Mark mark()

Creates a new mark.

replace

public void replace(String replacement)

Replaces the current element with the replacement text.

Parameters:

replacement - The replacement.

getBetween

public String getBetween(Mark a,
                Mark b)

replaceBetween

public void replaceBetween(Mark a,
                  Mark b,
                  String replacement)

Replaces all content between two marks with the replacement text.

Parameters:

replacement - The replacement.

writeTo

public void writeTo(File f)
             throws IOException

Throws:

IOException