Module com.aoapps.lang

Package com.aoapps.lang

Class Coercion

java.lang.Object

com.aoapps.lang.Coercion

public final class Coercion
extends Object

Coerces objects to String compatible with JSP Expression Language (JSP EL) and the Java Standard Taglib (JSTL). Also adds support for seamless output of XML DOM nodes.

Author:

AO Industries, Inc.

Method Summary

Modifier and Type	Method	Description
static void	append(Object value, Encoder encoder, Appendable out)	Encodes an object's String representation, supporting streaming for specialized types.
static void	append(Object value, Encoder encoder, Appendable out, boolean outOptimized)	Encodes an object's String representation, supporting streaming for specialized types.
static void	append(Object value, Appendable out)	Appends an object's String representation, supporting streaming for specialized types.
static void	append(Object value, Appendable out, boolean outOptimized)	Appends an object's String representation, supporting streaming for specialized types.
static boolean	isEmpty(Object value)	Checks if a value is null or empty.
static Object	nullIfEmpty(Object value)	Returns the provided value (possibly converted to a different form, like String) or null if the value is empty.
static Writer	optimize(Writer out, Encoder encoder)	Optimizes the given writer by passing through CoercionOptimizer.optimize(java.io.Writer, com.aoapps.lang.io.Encoder) on all registered coercion optimizers until there are no replacements.
static Appendable	optimize(Appendable out, Encoder encoder)	Optimizes the given appendable by dispatching to optimize(java.io.Writer, com.aoapps.lang.io.Encoder) when it is a Writer.
static void	registerOptimizer(CoercionOptimizer optimizer)	Registers a new coercion optimizer.
static String	toString(Object value)	Converts an object to a string.
static Object	trim(Object value)	Returns the provided value trimmed, as per rules of Strings.isWhitespace(int).
static Object	trimNullIfEmpty(Object value)	Returns the provided value trimmed, as per rules of Strings.isWhitespace(int), or null if the value is empty after trimming.
static void	write(Object value, Encoder encoder, Writer out)	Encodes an object's String representation, supporting streaming for specialized types.
static void	write(Object value, Encoder encoder, Writer out, boolean outOptimized)	Encodes an object's String representation, supporting streaming for specialized types.
static void	write(Object value, Writer out)	Writes an object's String representation, supporting streaming for specialized types.
static void	write(Object value, Writer out, boolean outOptimized)	Writes an object's String representation, supporting streaming for specialized types.

Methods inherited from class java.lang.Object

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

Method Details

toString

public static String toString(Object value)

Converts an object to a string.

1. Any Optional is unwrapped (supporting any levels of nesting).
2. When null return "".
3. When String return directly.
4. When Writable return Writable.toString().
5. When Segment or CharSequence return CharSequence.toString().
6. When char[] return "" when empty or String(char[]).
7. When Node serialize the output as StandardCharsets.UTF_8.
8. Otherwise return value.toString().

registerOptimizer

public static void registerOptimizer(CoercionOptimizer optimizer)

Registers a new coercion optimizer.

optimize

public static Writer optimize(Writer out,
 Encoder encoder)

Optimizes the given writer by passing through CoercionOptimizer.optimize(java.io.Writer, com.aoapps.lang.io.Encoder) on all registered coercion optimizers until there are no replacements.

optimize

public static Appendable optimize(Appendable out,
 Encoder encoder)

Optimizes the given appendable by dispatching to optimize(java.io.Writer, com.aoapps.lang.io.Encoder) when it is a Writer.

There is currently no implementation of appendable-specific unwrapping, but this is here for consistency with the writer unwrapping.

See Also:

• optimize(java.io.Writer, com.aoapps.lang.io.Encoder)

write

public static void write(Object value,
 Writer out)
                  throws IOException

Writes an object's String representation, supporting streaming for specialized types.

1. Any Optional is unwrapped (supporting any levels of nesting).
2. When null do not write.
3. When EncoderWriter unwrap and dispatch to write(java.lang.Object, com.aoapps.lang.io.Encoder, java.io.Writer).
4. When String write directly.
5. When Writable write Writable.toString() when Writable.isFastToString() or dispatch to Writable.writeTo(java.io.Writer).
6. When Segment write Segment.array.
7. When CharSequence append directly.
8. When char[] write directly.
9. When Node serialize the output as StandardCharsets.UTF_8.
10. Otherwise write value.toString().

Throws:

IOException

write

public static void write(Object value,
 Writer out,
 boolean outOptimized)
                  throws IOException

Writes an object's String representation, supporting streaming for specialized types.

1. Any Optional is unwrapped (supporting any levels of nesting).
2. When null do not write.
3. When EncoderWriter unwrap and dispatch to write(java.lang.Object, com.aoapps.lang.io.Encoder, java.io.Writer, boolean).
4. When String write directly.
5. When Writable write Writable.toString() when Writable.isFastToString() or dispatch to Writable.writeTo(java.io.Writer).
6. When Segment write Segment.array.
7. When CharSequence append directly.
8. When char[] write directly.
9. When Node serialize the output as StandardCharsets.UTF_8.
10. Otherwise write value.toString().

Parameters:

outOptimized - Is out already known to have been passed through optimize(java.io.Writer, com.aoapps.lang.io.Encoder) (with encoder = null)?

Throws:

IOException

write

public static void write(Object value,
 Encoder encoder,
 Writer out)
                  throws IOException

Encodes an object's String representation, supporting streaming for specialized types.

1. When encoder == null dispatch to write(java.lang.Object, java.io.Writer).
2. Any Optional is unwrapped (supporting any levels of nesting).
3. When null do not encode.
4. When String encode directly.
5. When Writable encode Writable.toString() when Writable.isFastToString() or dispatch to Writable.writeTo(com.aoapps.lang.io.Encoder, java.io.Writer).
6. When Segment encode Segment.array.
7. When CharSequence encode directly.
8. When char[] encode directly.
9. When Node serialize the output as StandardCharsets.UTF_8 while encoding through EncoderWriter.
10. Otherwise encode value.toString().

Parameters:

encoder - if null, no encoding is performed - write through

Throws:

IOException

write

public static void write(Object value,
 Encoder encoder,
 Writer out,
 boolean outOptimized)
                  throws IOException

Encodes an object's String representation, supporting streaming for specialized types.

1. When encoder == null dispatch to write(java.lang.Object, java.io.Writer, boolean).
2. Any Optional is unwrapped (supporting any levels of nesting).
3. When null do not encode.
4. When String encode directly.
5. When Writable encode Writable.toString() when Writable.isFastToString() or dispatch to Writable.writeTo(com.aoapps.lang.io.Encoder, java.io.Writer).
6. When Segment encode Segment.array.
7. When CharSequence encode directly.
8. When char[] encode directly.
9. When Node serialize the output as StandardCharsets.UTF_8 while encoding through EncoderWriter.
10. Otherwise encode value.toString().

Parameters:

encoder - if null, no encoding is performed - write through

outOptimized - Is out already known to have been passed through optimize(java.io.Writer, com.aoapps.lang.io.Encoder)?

Throws:

IOException

append

public static void append(Object value,
 Appendable out)
                   throws IOException

Appends an object's String representation, supporting streaming for specialized types.

1. When out is a Writer dispatch to write(java.lang.Object, java.io.Writer).
2. Any Optional is unwrapped (supporting any levels of nesting).
3. When null do not append.
4. When String append directly.
5. When Writable append Writable.toString() when Writable.isFastToString() or dispatch to Writable.appendTo(java.lang.Appendable).
6. When Segment or CharSequence append directly.
7. When char[] append wrapped in new Segment.
8. When Node serialize the output as StandardCharsets.UTF_8.
9. Otherwise append value.toString().

Throws:

IOException

append

public static void append(Object value,
 Appendable out,
 boolean outOptimized)
                   throws IOException

Appends an object's String representation, supporting streaming for specialized types.

1. When out is a Writer dispatch to write(java.lang.Object, java.io.Writer, boolean).
2. Any Optional is unwrapped (supporting any levels of nesting).
3. When null do not append.
4. When String append directly.
5. When Writable append Writable.toString() when Writable.isFastToString() or dispatch to Writable.appendTo(java.lang.Appendable).
6. When Segment or CharSequence append directly.
7. When char[] append wrapped in new Segment.
8. When Node serialize the output as StandardCharsets.UTF_8.
9. Otherwise append value.toString().

Parameters:

outOptimized - Is out already known to have been passed through optimize(java.io.Writer, com.aoapps.lang.io.Encoder) (with encoder = null)?

Throws:

IOException

append

public static void append(Object value,
 Encoder encoder,
 Appendable out)
                   throws IOException

Encodes an object's String representation, supporting streaming for specialized types.

1. When encoder == null dispatch to append(java.lang.Object, java.lang.Appendable).
2. When out is a Writer dispatch to write(java.lang.Object, com.aoapps.lang.io.Encoder, java.io.Writer).
3. Any Optional is unwrapped (supporting any levels of nesting).
4. When null do not encode.
5. When String encode directly.
6. When Writable encode Writable.toString() when Writable.isFastToString() or dispatch to Writable.appendTo(com.aoapps.lang.io.Encoder, java.lang.Appendable).
7. When Segment or CharSequence encode directly.
8. When char[] encode wrapped in new Segment.
9. When Node serialize the output as StandardCharsets.UTF_8 while encoding through EncoderWriter and AppendableWriter.
10. Otherwise encode value.toString().

Parameters:

encoder - if null, no encoding is performed - write through

Throws:

IOException

append

public static void append(Object value,
 Encoder encoder,
 Appendable out,
 boolean outOptimized)
                   throws IOException

Encodes an object's String representation, supporting streaming for specialized types.

1. When encoder == null dispatch to append(java.lang.Object, java.lang.Appendable, boolean).
2. When out is a Writer dispatch to write(java.lang.Object, com.aoapps.lang.io.Encoder, java.io.Writer, boolean).
3. Any Optional is unwrapped (supporting any levels of nesting).
4. When null do not encode.
5. When String encode directly.
6. When Writable encode Writable.toString() when Writable.isFastToString() or dispatch to Writable.appendTo(com.aoapps.lang.io.Encoder, java.lang.Appendable).
7. When Segment or CharSequence encode directly.
8. When char[] encode wrapped in new Segment.
9. When Node serialize the output as StandardCharsets.UTF_8 while encoding through EncoderWriter and AppendableWriter.
10. Otherwise encode value.toString().

Parameters:

encoder - if null, no encoding is performed - write through

outOptimized - Is out already known to have been passed through optimize(java.io.Writer, com.aoapps.lang.io.Encoder)?

Throws:

IOException

isEmpty

public static boolean isEmpty(Object value)

Checks if a value is null or empty.

1. Any Optional is unwrapped (supporting any levels of nesting).
2. When null return true.
3. When String return String.isEmpty().
4. When Writable return Writable.getLength() == 0.
5. When Segment or CharSequence return CharSequence.length() == 0.
6. When char[] return value.length == 0.
7. When Node return false.
8. Otherwise return value.toString().isEmpty().

Throws:

UncheckedIOException - on any underlying IOException.

nullIfEmpty

public static Object nullIfEmpty(Object value)

Returns the provided value (possibly converted to a different form, like String) or null if the value is empty.

1. Any Optional is unwrapped (supporting any levels of nesting).
2. When null return null.
3. When String return null when String.isEmpty().
4. When Writable return null when Writable.getLength() == 0.
5. When Segment or CharSequence return null when CharSequence.length() == 0.
6. When char[] return null when value.length == 0.
7. When Node return value.
8. Otherwise return Strings.nullIfEmpty(value.toString()).

Throws:

UncheckedIOException - on any underlying IOException.

See Also:

• isEmpty(java.lang.Object)

trim

public static Object trim(Object value)

Returns the provided value trimmed, as per rules of Strings.isWhitespace(int).

1. Any Optional is unwrapped (supporting any levels of nesting).
2. When null return null.
3. When String return Strings.trim(java.lang.String).
4. When Writable return Strings.trim(java.lang.String) when Writable.isFastToString() otherwise Writable.trim().
5. When Segment or CharSequence return Strings.trim(java.lang.CharSequence).
6. When char[] return "" when value.length == 0 or Strings.trim(new Segment(value, 0, value.length)) then value if nothing trimmed.
7. When Node return value.
8. Otherwise return Strings.trim(value.toString()).

Returns:

The original value (possibly of a different type even when nothing to trim), a trimmed version of the value (possibly of a different type), a trimmed String representation of the object, or null when the value is null.

Throws:

UncheckedIOException - on any underlying IOException.

trimNullIfEmpty

public static Object trimNullIfEmpty(Object value)

Returns the provided value trimmed, as per rules of Strings.isWhitespace(int), or null if the value is empty after trimming.

1. Any Optional is unwrapped (supporting any levels of nesting).
2. When null return null.
3. When String return Strings.trimNullIfEmpty(java.lang.String).
4. When Writable return Strings.trimNullIfEmpty(java.lang.String) when Writable.isFastToString() otherwise Writable.trim() then null if empty after trimming.
5. When Segment or CharSequence return Strings.trimNullIfEmpty(java.lang.CharSequence).
6. When char[] return null when value.length == 0 or Strings.trimNullIfEmpty(new Segment(value, 0, value.length)) then value if nothing trimmed.
7. When Node return value.
8. Otherwise return Strings.trimNullIfEmpty(value.toString()).

Returns:

The original value (possibly of a different type even when nothing to trim), a trimmed version of the value (possibly of a different type), a trimmed String representation of the object, or null when the value is null or empty after trimming.

Throws:

UncheckedIOException - on any underlying IOException.