groovy.xml
Class MarkupBuilder

java.lang.Object
  groovy.lang.GroovyObjectSupport
      groovy.util.BuilderSupport
          groovy.xml.MarkupBuilder

All Implemented Interfaces:

GroovyObject

public class MarkupBuilder
extends BuilderSupport

A helper class for creating XML or HTML markup. The builder supports various 'pretty printed' formats.

Example:

new MarkupBuilder().root {
   a( a1:'one' ) {
     b { mkp.yield( '3 < 5' ) }
     c( a2:'two', 'blah' )
   }
 }

Will print the following to System.out:

<root>
   <a a1='one'>
     <b>3 &lt; 5</b>
     <c a2='two'>blah</c>
   </a>
 </root>

Note that mkp is a special namespace used to escape away from the normal building mode of the builder and get access to helper markup methods such as 'yield' and 'yieldUnescaped'. See the javadoc for getMkp() for further details.

Version:

$Revision: 18226 $

Author:

James Strachan, Stefan Matthias Aust, Scott Stirling, Paul King

Constructor Summary

MarkupBuilder()
Prints markup to System.out

MarkupBuilder(IndentPrinter out)
Sends markup to the given IndentPrinter.

MarkupBuilder(PrintWriter pw)
Sends markup to the given PrintWriter

MarkupBuilder(Writer writer)
Sends markup to the given Writer but first wrapping it in a PrintWriter

Method Summary

protected Object	createNode(Object name)
protected Object	createNode(Object name, Map attributes)
protected Object	createNode(Object name, Map attributes, Object value)
protected Object	createNode(Object name, Object value)
boolean	getDoubleQuotes() Returns true if attribute values are output with double quotes; false if single quotes are used.
Object	getMkp() Property that may be called from within your builder closure to access helper methods, namely MarkupBuilderHelper.yield(String), MarkupBuilderHelper.yieldUnescaped(String), MarkupBuilderHelper.pi(Map), MarkupBuilderHelper.xmlDeclaration(Map) and MarkupBuilderHelper.comment(String).
protected Object	getName(String methodName) A hook to allow names to be converted into some other object such as a QName in XML or ObjectName in JMX.
protected IndentPrinter	getPrinter()
boolean	isOmitEmptyAttributes() Determine whether empty attributes will appear in the produced markup.
boolean	isOmitNullAttributes() Determine whether null attributes will appear in the produced markup.
protected void	nodeCompleted(Object parent, Object node) A hook to allow nodes to be processed once they have had all of their children applied.
protected void	print(Object node)
void	setDoubleQuotes(boolean useDoubleQuotes) Sets whether the builder outputs attribute values in double quotes or single quotes.
void	setOmitEmptyAttributes(boolean omitEmptyAttributes) Allows empty attributes to be removed from the generated markup.
void	setOmitNullAttributes(boolean omitNullAttributes) Allows null attributes to be removed from the generated markup.
protected void	setParent(Object parent, Object child)
protected String	transformValue(String value) Deprecated.

Methods inherited from class groovy.util.BuilderSupport

doInvokeMethod, getCurrent, invokeMethod, invokeMethod, postNodeCompletion, setClosureDelegate, setCurrent

Methods inherited from class groovy.lang.GroovyObjectSupport

getMetaClass, getProperty, setMetaClass, setProperty

Methods inherited from class java.lang.Object

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

Constructor Detail

MarkupBuilder

public MarkupBuilder()

Prints markup to System.out

See Also:

IndentPrinter.IndentPrinter()

MarkupBuilder

public MarkupBuilder(PrintWriter pw)

Sends markup to the given PrintWriter

Parameters:

pw - the PrintWriter to use

See Also:

IndentPrinter.IndentPrinter(PrintWriter)

MarkupBuilder

public MarkupBuilder(Writer writer)

Sends markup to the given Writer but first wrapping it in a PrintWriter

Parameters:

writer - the writer to use

See Also:

IndentPrinter.IndentPrinter(PrintWriter)

MarkupBuilder

public MarkupBuilder(IndentPrinter out)

Sends markup to the given IndentPrinter. Use this option if you want to customize the indent used.

Parameters:

out - the IndentPrinter to use

Method Detail

getDoubleQuotes

public boolean getDoubleQuotes()

Returns true if attribute values are output with double quotes; false if single quotes are used. By default, single quotes are used.

Returns:

true if double quotes are used for attributes

setDoubleQuotes

public void setDoubleQuotes(boolean useDoubleQuotes)

Sets whether the builder outputs attribute values in double quotes or single quotes.

Parameters:

useDoubleQuotes - If this parameter is true, double quotes are used; otherwise, single quotes are.

isOmitNullAttributes

public boolean isOmitNullAttributes()

Determine whether null attributes will appear in the produced markup.

Returns:

true, if null attributes will be removed from the resulting markup.

setOmitNullAttributes

public void setOmitNullAttributes(boolean omitNullAttributes)

Allows null attributes to be removed from the generated markup.

Parameters:

omitNullAttributes - if true, null attributes will not be included in the resulting markup. If false null attributes will be included in the markup as empty strings regardless of the omitEmptyAttribute setting. Defaults to false.

isOmitEmptyAttributes

public boolean isOmitEmptyAttributes()

Determine whether empty attributes will appear in the produced markup.

Returns:

true, if empty attributes will be removed from the resulting markup.

setOmitEmptyAttributes

public void setOmitEmptyAttributes(boolean omitEmptyAttributes)

Allows empty attributes to be removed from the generated markup.

Parameters:

omitEmptyAttributes - if true, empty attributes will not be included in the resulting markup. Defaults to false.

getPrinter

protected IndentPrinter getPrinter()

setParent

protected void setParent(Object parent,
                         Object child)

Specified by:

setParent in class BuilderSupport

getMkp

public Object getMkp()

Property that may be called from within your builder closure to access helper methods, namely MarkupBuilderHelper.yield(String), MarkupBuilderHelper.yieldUnescaped(String), MarkupBuilderHelper.pi(Map), MarkupBuilderHelper.xmlDeclaration(Map) and MarkupBuilderHelper.comment(String).

Returns:

this MarkupBuilder

createNode

protected Object createNode(Object name)

Specified by:

createNode in class BuilderSupport

createNode

protected Object createNode(Object name,
                            Object value)

Specified by:

createNode in class BuilderSupport

createNode

protected Object createNode(Object name,
                            Map attributes,
                            Object value)

Specified by:

createNode in class BuilderSupport

createNode

protected Object createNode(Object name,
                            Map attributes)

Specified by:

createNode in class BuilderSupport

nodeCompleted

protected void nodeCompleted(Object parent,
                             Object node)

Description copied from class: BuilderSupport

A hook to allow nodes to be processed once they have had all of their children applied.

Overrides:

nodeCompleted in class BuilderSupport

Parameters:

parent - the parent of the node being processed

node - the current node being processed

print

protected void print(Object node)

getName

protected Object getName(String methodName)

Description copied from class: BuilderSupport

A hook to allow names to be converted into some other object such as a QName in XML or ObjectName in JMX.

Overrides:

getName in class BuilderSupport

Parameters:

methodName - the name of the desired method

Returns:

the object representing the name

transformValue

protected String transformValue(String value)

Deprecated.

Returns a String with special XML characters escaped as entities so that output XML is valid. Escapes the following characters as corresponding entities:

• \' as '
• & as &
• < as &lt;
• > as &gt;

Parameters:

value - to be searched and replaced for XML special characters.

Returns:

value with XML characters escaped

See Also:

escapeXmlValue(String, boolean)