com.healthmarketscience.common.util
Class AppendableExt

java.lang.Object
  com.healthmarketscience.common.util.AppendableExt

All Implemented Interfaces:

Appendable

Direct Known Subclasses:

StringAppendableExt

public class AppendableExt
extends Object
implements Appendable

Wrapper for an Appendable which adds the ability for objects to append themselves directly to the given Appendable instead of creating intermediate CharSequence objects (Strings, etc). This can make appends of deep object hierarchies much more efficient. An object can take advantage of this facility by implementing the Appendee interface.

All methods will use the Appendee.appendTo(com.healthmarketscience.common.util.AppendableExt) method if passed an Appendee.

Additionally, this wrapper adds two convenience methods:

• append(Object) - a method to append Objects by calling String.valueOf(obj) on the object and appending the result to the AppendableExt (unless the object is an Appendee or CharSequence)
• append(Iterable,Object) - a method to append an iteration (collection, etc) of objects separated by a delimiter

This class acts like the Formatter/Formattable facility without the extra overhead of parsing the format strings. If complicated formatting is needed for the generated strings, Formatter should be used instead.

Examples:

 //
 // *Without* using this interface.
 //
 public class Foo {
   private Bar b;
   public String toString() {
     return "Foo " + b;
   }
 }
 public class Bar {
   public String toString() {
     return "Bar";
   }
 }

 Foo f = new Foo();
 StringBuilder sb = new StringBuilder();

 // this will involve copying multiple strings before actual append!!!
 sb.append(f);

 
 //
 // *With* using this interface.
 //
 public class Foo implements Appendee {
   private Bar b;
   public void appendTo(AppendableExt app) throws IOException {
     app.append("Foo").append(b);
   }
 }
 public class Bar implements Appendee {
   public void appendTo(AppendableExt app) throws IOException {
     app.append("Bar");
   }
 }

 Foo f = new Foo();
 AppendableExt ae = new AppendableExt(new StringBuilder());

 // this will involve no extra copies, both strings ("Foo", "Bar") will be
 // written directly to the Appender
 ae.append(f);

 

Author:

James Ahlborn

Constructor Summary

AppendableExt(Appendable app)
Initialize a new AppendableExt based on the given Appendable.

AppendableExt(Appendable app, Object context)
Initialize a new AppendableExt based on the given Appendable and context.

Method Summary

AppendableExt	append(Appendee a) Will call the appendTo() method on the given object.
AppendableExt	append(char c)
AppendableExt	append(CharSequence s)
AppendableExt	append(CharSequence s, int start, int end)
AppendableExt	append(Iterable<?> iable, Object delimiter) Will iterate the given Iterable and append each object separated by the given delimiter.
AppendableExt	append(Object o) Will call append(String.valueOf(o)) with the given object (unless the object is an Appendee or CharSequence in which case it will be passed to the appropriate method).
Appendable	getAppendable() Get the underlying Appendable.
Object	getContext()
void	setContext(Object newContext) Sets the "context" that will be returned from subsequent getContext() calls.
String	toString() Get the result of calling toString() on the underlying Appendable.

Methods inherited from class java.lang.Object

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

Constructor Detail

AppendableExt

public AppendableExt(Appendable app)

Initialize a new AppendableExt based on the given Appendable.

Parameters:

app - initial underlying Appendable

AppendableExt

public AppendableExt(Appendable app,
                     Object context)

Initialize a new AppendableExt based on the given Appendable and context.

Parameters:

app - initial underlying Appendable

context - initial append context

Method Detail

append

public AppendableExt append(char c)
                     throws IOException

Specified by:

append in interface Appendable

Throws:

IOException

append

public AppendableExt append(CharSequence s)
                     throws IOException

Note that if the given CharSequence is also an Appendee, it will be handled as an Appendee instead.

Specified by:

append in interface Appendable

Throws:

IOException

append

public AppendableExt append(CharSequence s,
                            int start,
                            int end)
                     throws IOException

Note that if the given CharSequence is also an Appendee, it will be handled as an Appendee instead (but the range will still be respected).

Specified by:

append in interface Appendable

Throws:

IOException

append

public AppendableExt append(Appendee a)
                     throws IOException

Will call the appendTo() method on the given object.

Parameters:

a - object to append to this AppendableExt

Returns:

this AppendableExt object

Throws:

IOException - if the append fails

append

public AppendableExt append(Object o)
                     throws IOException

Will call append(String.valueOf(o)) with the given object (unless the object is an Appendee or CharSequence in which case it will be passed to the appropriate method).

Parameters:

o - object to append to this AppendableExt

Returns:

this AppendableExt object

Throws:

IOException - if the append fails

append

public AppendableExt append(Iterable<?> iable,
                            Object delimiter)
                     throws IOException

Will iterate the given Iterable and append each object separated by the given delimiter.

Parameters:

iable - an Iterable object

delimiter - delimiter to append between each object in the iable

Returns:

this AppendableExt object

Throws:

IOException - if the append fails

getAppendable

public Appendable getAppendable()

Get the underlying Appendable.

Returns:

the underlying Appendable

toString

public String toString()

Get the result of calling toString() on the underlying Appendable.

Overrides:

toString in class Object

Returns:

the result of calling toString() on the underlying Appendable.

getContext

public Object getContext()

Returns:

the current "context" as set through setContext(java.lang.Object), if any.

setContext

public void setContext(Object newContext)

Sets the "context" that will be returned from subsequent getContext() calls. Useful for Appendee implementations that want to change the behavior of nested, context-aware Appendee objects.

Parameters:

newContext - the new context for any subsequent append calls