T
- This should always be parameterized with the exact same
class that is extending the MarkupBuilder
to support fluent style.public abstract class MarkupBuilder<T> extends Object
Writer
.
Writer
.
The Builder part of the name is somewhat misleading as
this class does not store or keep track of all the markup objects created but rather
writes using the writer as soon as it can.
Thus the order of operations performed on this class is very important and should
follow the order that you would write the markup.
MarkupBuilder
or MarkupWriter
.
Markup builders write immediately to a writer where as a markup writer
writes when told to. But again in both cases you generally define the markup with an anonymous class.
For examples of use its best to see Html
for an XHTML builder which will write XHTML
markup immediatly or HtmlWriter
which allows you to define XHTML markup then write it later.
Markup writers
are more useful for MVC frameworks and builders
are more for convenience.
The custom builder should be parameterized to itself to support fluent style.
Example:
public class MyMarkup extends MarkupBuilder<MyMarkup> { public MyMarkup(Writer builder) { super(builder); } protected MyMarkup getSelf() { return this; } public MyMarkup myTag() { return start("myTag"); } }
MarkupWriter
. start(String)
and end()
for writing tags.
See attr(String...)
for writting attributes.
${...}notation. See
bind(String, Object)
, and text(String)
.
Indenter
. For most cases you can use SimpleIndenter
start("prefix:tagName")
.
Or you can use the namespace methods: ns()
, ns(String)
, xmlns(String, String)
The following Nested builders are very helpful for working with multiple XML schemas.
Example:
new Xslt(writer) {{ ns("xsl"); template().match("stuff"); new Html(writer) {{ html().body().done(); }} done(); }}See
MarkupBuilder(MarkupBuilder)
.
synchronize(writer) { new SomeBuilder(writer) {{ }}; }
Text
will be escaped appropriately.
For those seriously concerned with performance an appropriate implementation of
Writer
should be given to the builder.
For example: In a single threaded environment where you are writing to memory
Commons IO StringBuilderWriter
is a good choice over StringWriter
.
On the other hand if you are writing very large XML document to a file
or network socket PrintWriter
is probably a better choice.
MarkupBuilder.TagClosingPolicy
,
start(String, TagClosingPolicy)
,
attr(String...)
,
end()
,
done()
Modifier and Type | Class and Description |
---|---|
static class |
MarkupBuilder.TagClosingPolicy
Policy for how tags should be closed.
|
Modifier and Type | Field and Description |
---|---|
protected static Indenter |
indentOff
An indenter that turns off indenting.
|
protected static Indenter |
indentOn
A default indenter that uses tabs.
|
protected static Indenter |
indentSameLine
Indents by keeping a tag pair on the same line.
|
Modifier | Constructor and Description |
---|---|
protected |
MarkupBuilder()
Use for deferred writer.
|
|
MarkupBuilder(MarkupBuilder<?> builder)
Create a nested builder from given builder.
|
|
MarkupBuilder(MarkupBuilder<?> builder,
boolean nested)
Create a nested builder from a builder or resume from a builder.
|
|
MarkupBuilder(Writer writer)
Create a builder using the given writer.
|
Modifier and Type | Method and Description |
---|---|
T |
attr(String... attrs)
Adds attributes to the last
start tag . |
T |
bind(Collection<Map.Entry<String,Object>> nvps)
Convenience for
bind(String, Object) |
T |
bind(String name,
Object value)
Binds a named variables to be used for expansion in
attributes
and text . |
void |
done()
Call when completely done with the builder.
|
T |
end()
Closes the last
start tag . |
T |
end(int i)
Closes the inputed number of open tags.
|
T |
endAll()
Closes all open tags.
|
protected String |
escapeAttributeMarkup(String raw)
The strategy for escaping attribute markup.
|
protected String |
escapeElementMarkup(String raw)
The strategy for escaping element markup.
|
protected String |
escapeMarkup(String raw)
Deprecated.
Please use
escapeElementMarkup(String) and escapeAttributeMarkup(String) |
protected abstract T |
getSelf()
Needed for fluent style and Java parameterization limitations.
|
T |
indent(Indenter indenter)
Sets the indenter.
|
T |
ns()
Restores the current namespace prefix
to whatever the surrounding tags prefix is.
|
T |
ns(String prefix)
Sets the current namespace prefix.
|
T |
raw(String text)
Write text with out escaping or variable expansion.
|
T |
raw(String text,
boolean expand)
Writes text with out escaping.
|
void |
setDepth(int depth)
Sets the indent depth after the builder has been created.
|
void |
setWriter(Writer writer)
Sets the writer after the builder has been created.
|
T |
start(String tag)
Starts a tag using the default closing policy
MarkupBuilder.TagClosingPolicy.NORMAL . |
T |
start(String tag,
MarkupBuilder.TagClosingPolicy policy)
Starts a tag but does not immediately write it till the next
tag is started.
|
T |
text(String text)
Writes variable expanded escaped text inside a tag.
|
T |
unbind(String name)
Removes a binding.
|
T |
write(MarkupWriter... writers)
Writes immediately by passing the writer to each
MarkupWriter
in the order passed in. |
T |
xmlns(String uri)
Sets the default namespace on the last started tag.
|
T |
xmlns(String uri,
String prefix)
Sets an XML namespace.
|
protected static Indenter indentOn
protected static Indenter indentOff
protected static Indenter indentSameLine
public MarkupBuilder(Writer writer)
writer
- never null
.public MarkupBuilder(MarkupBuilder<?> builder)
done()
is called when finished with the
nested builder so that the parent builder can resume using the writer.builder
- parent builder, never null
.done()
protected MarkupBuilder()
set
before
the builder is used.setWriter(Writer)
,
MarkupWriter
public MarkupBuilder(MarkupBuilder<?> builder, boolean nested)
builder
- never null
.nested
- true
means nested, false
means resuming.protected abstract T getSelf()
Most implementations only have to do:
return this;
this
object.public final T ns()
ns(null);
null
.ns(String)
public final T ns(String prefix)
Example:
ns("html").div().end();Result:
<html:div></html:div>
prefix
- maybe null
null
.public final void setWriter(Writer writer)
writer
- never null
IllegalArgumentException
- if the writer has already been set or the given writer is null.public final void setDepth(int depth)
depth
- should greater than or equal 0
public T indent(Indenter indenter)
indenter
- if null
reverts to the previous builder.indentOn
,
indentOff
,
indentSameLine
public final T text(String text)
text
- the text will be escaped and variables will be expanded.null
.raw(String)
,
bind(String, Object)
public final T raw(String text)
text
- null
.raw(String, boolean)
public final T raw(String text, boolean expand)
text
- expand
- true
does variable expansion.null
.public final T bind(String name, Object value)
attributes
and text
. Variables are represented with by ${...}
.
Example
bind("name", "Ferris"); text("${name}");
Variables are expanded in order and can be referred in a later binding.
bind("firstName", "Adam"); bind("lastName", "Gent"); bind("fullName", "${firstName} ${lastName}");
name
- never null
or empty.value
- maybe null
.null
.public final T unbind(String name)
name
- maybe null
.null
.bind(String, Object)
public final T bind(Collection<Map.Entry<String,Object>> nvps)
bind(String, Object)
nvps
- never null
.null
.public final T start(String tag)
MarkupBuilder.TagClosingPolicy.NORMAL
.
Equivalent to: start("tag", TagClosingPolicy.NORMAL)
.
tag
- null
.start(String, TagClosingPolicy)
public final T start(String tag, MarkupBuilder.TagClosingPolicy policy)
MarkupBuilder.TagClosingPolicy
dictates whether or not the tag
needs to be closed
. Thus end()
does not need to be called
for all tags.tag
- never null
or empty.policy
- never null
.null
.end()
public final T attr(String... attrs)
attrs
- name value pairs. Its invalid for an odd number of arguments.null
.IllegalArgumentException
- odd number of arguments.public final T xmlns(String uri)
uri
- if null
nothing will happen.null
.xmlns(String, String)
public final T xmlns(String uri, String prefix)
uri
- if null
nothing will happen.prefix
- if null
or blank will act
like the default namespace and no prefix.null
.public final T end(int i)
i
- less than zero will do nothing.null
.end()
public final T end()
start tag
.
This is equivalent to </tag> or <tag/> depending
on the MarkupBuilder.TagClosingPolicy
.
null
.start(String, TagClosingPolicy)
,
endAll()
,
done()
public final void done()
If a builder is used again after done()
is called
an exception (usually IllegalArgumentException
) will be thrown.
public final T write(MarkupWriter... writers)
MarkupWriter
in the order passed in.writers
- never null
, null elements passed in are ignored.null
.protected String escapeMarkup(String raw)
escapeElementMarkup(String)
and escapeAttributeMarkup(String)
raw
- maybe null
.null
if null for input.text(String)
protected String escapeElementMarkup(String raw)
raw
- maybe null
.null
if null for input.text(String)
,
escapeAttributeMarkup(String)
protected String escapeAttributeMarkup(String raw)
#xD, #xA, #x9
CR, newline, and tab, respectively.
raw
- maybe null
.null
if null for input.Copyright © 2010–2016 JATL. All rights reserved.