Module org.eclipse.jetty.util

Package org.eclipse.jetty.util

Class Utf8StringBuilder

java.lang.Object

org.eclipse.jetty.util.Utf8StringBuilder

All Implemented Interfaces:

CharsetStringBuilder

public class Utf8StringBuilder
extends Object
implements CharsetStringBuilder

This class wraps a standard StringBuilder and provides methods to append UTF-8 encoded bytes, that are converted into characters.

This class is stateful and up to 4 calls to append(byte) may be needed before state a character is appended to the string buffer.

The UTF-8 decoding is done by this class and no additional buffers or Readers are used. The algorithm is fast fail, in that errors are detected as the bytes are appended. However, no exceptions are thrown and only the hasCodingErrors() method indicates the fast failure, otherwise the coding errors are replaced and may be returned, unless the build() method is used, which may throw CharacterCodingException. Already decoded characters may also be appended (e.g. append(char) making this class suitable for decoding % encoded strings of already decoded characters.

See Also:

• for decoding of arbitrary java.nio.charset.Charsets.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Utf8StringBuilder.Utf8CharacterCodingException
static class	Utf8StringBuilder.Utf8IllegalArgumentException

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.CharsetStringBuilder

CharsetStringBuilder.DecoderStringBuilder, CharsetStringBuilder.Iso88591StringBuilder, CharsetStringBuilder.UsAsciiStringBuilder

Field Summary

Fields

Modifier and Type	Field	Description
protected int	_state
static final char	REPLACEMENT

Constructor Summary

Constructors

Modifier	Constructor	Description
	Utf8StringBuilder()
	Utf8StringBuilder(int capacity)
protected	Utf8StringBuilder(StringBuilder buffer)
protected	Utf8StringBuilder(StringBuilder buffer, CodingErrorAction onMalformedInput, CodingErrorAction onUnmappableCharacter)
	Utf8StringBuilder(CodingErrorAction onMalformedInput, CodingErrorAction onUnmappableCharacter)

Method Summary

Modifier and Type	Method	Description
void	append(byte b)
void	append(byte[] b)
void	append(byte[] b, int offset, int length)
boolean	append(byte[] b, int offset, int length, int maxChars)
void	append(char c)
void	append(String s)
void	append(String s, int offset, int length)
void	append(ByteBuffer buf)
void	appendByte(byte b)
protected void	bufferAppend(char c)
protected void	bufferReset()
String	build()	Build the completed string and reset the buffer.
String	build(boolean allowPartialString)	Attempt to build the completed string and reset the buffer, returning a partial string if there are encoding errors
protected void	checkCharAppend()
void	complete()	Complete the appendable, adding a replacement character and coding error if the sequence is not currently complete.
boolean	hasCodingErrors()	Test for if there are and detected encoding errors
boolean	isComplete()
int	length()
void	partialReset()	Partially reset the appendable: clear the buffer and clear any errors, but retain the decoding state of any partially decoded sequences.
boolean	replaceIncomplete()	If there is an incomplete sequence, replace it with the encoding specific replacement character.
void	reset()	Reset the appendable, clearing the buffer, resetting decoding state and clearing any errors.
<X extends Throwable> String	takeCompleteString(Supplier<X> onCodingError)	Take the completely decoded string.
<X extends Throwable> String	takePartialString(Supplier<X> onCodingError)	Take the partially decoded string.
String	toCompleteString()	Get the completely decoded string, which is equivalent to calling complete() then toString().
String	toPartialString()
String	toString()

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.eclipse.jetty.util.CharsetStringBuilder

append

Field Details

REPLACEMENT

public static final char REPLACEMENT

See Also:

• Constant Field Values

_state

protected int _state

Constructor Details

Utf8StringBuilder

public Utf8StringBuilder()

Utf8StringBuilder

public Utf8StringBuilder(CodingErrorAction onMalformedInput,
 CodingErrorAction onUnmappableCharacter)

Utf8StringBuilder

public Utf8StringBuilder(int capacity)

Utf8StringBuilder

protected Utf8StringBuilder(StringBuilder buffer)

Utf8StringBuilder

protected Utf8StringBuilder(StringBuilder buffer,
 CodingErrorAction onMalformedInput,
 CodingErrorAction onUnmappableCharacter)

Method Details

length

public int length()

Specified by:

length in interface CharsetStringBuilder

Returns:

the length in characters

hasCodingErrors

public boolean hasCodingErrors()

Description copied from interface: CharsetStringBuilder

Test for if there are and detected encoding errors

Specified by:

hasCodingErrors in interface CharsetStringBuilder

Returns:

True if the characters decoded have contained UTF8 coding errors.

reset

public void reset()

Reset the appendable, clearing the buffer, resetting decoding state and clearing any errors.

Specified by:

reset in interface CharsetStringBuilder

partialReset

public void partialReset()

Partially reset the appendable: clear the buffer and clear any errors, but retain the decoding state of any partially decoded sequences.

checkCharAppend

protected void checkCharAppend()

replaceIncomplete

public boolean replaceIncomplete()

Description copied from interface: CharsetStringBuilder

If there is an incomplete sequence, replace it with the encoding specific replacement character.

Will set the encoding errors to true for CharsetStringBuilder.hasCodingErrors()

Specified by:

replaceIncomplete in interface CharsetStringBuilder

Returns:

true if replacement occurred, false if there was no issue.

append

public void append(char c)

Specified by:

append in interface CharsetStringBuilder

Parameters:

c - A decoded character to append

append

public void append(String s)

append

public void append(String s,
 int offset,
 int length)

append

public void append(byte b)

Specified by:

append in interface CharsetStringBuilder

Parameters:

b - An encoded byte to append

append

public void append(ByteBuffer buf)

Specified by:

append in interface CharsetStringBuilder

Parameters:

buf - Buffer of encoded bytes to append. The bytes are consumed from the buffer.

append

public void append(byte[] b)

Specified by:

append in interface CharsetStringBuilder

Parameters:

b - Array of encoded bytes to append

append

public void append(byte[] b,
 int offset,
 int length)

Specified by:

append in interface CharsetStringBuilder

Parameters:

b - Array of encoded bytes

offset - offset into the array

length - the number of bytes to append from the array.

append

public boolean append(byte[] b,
 int offset,
 int length,
 int maxChars)

bufferAppend

protected void bufferAppend(char c)

bufferReset

protected void bufferReset()

appendByte

public void appendByte(byte b)
                throws IOException

Throws:

IOException

isComplete

public boolean isComplete()

Returns:

True if the appended sequences are complete UTF-8 sequences.

complete

public void complete()

Complete the appendable, adding a replacement character and coding error if the sequence is not currently complete.

toString

public String toString()

Overrides:

toString in class Object

Returns:

The currently decoded string, excluding any partial sequences appended.

toPartialString

public String toPartialString()

Returns:

The currently decoded string, excluding any partial sequences appended.

toCompleteString

public String toCompleteString()

Get the completely decoded string, which is equivalent to calling complete() then toString().

Returns:

The completely decoded string.

build

public String build(boolean allowPartialString)
             throws CharacterCodingException

Attempt to build the completed string and reset the buffer, returning a partial string if there are encoding errors

Specified by:

build in interface CharsetStringBuilder

Parameters:

allowPartialString - true if a partial string is allowed to be returned, false means if complete string cannot be returned, an exception is thrown.

Returns:

The available string (complete or partial)

Throws:

CharacterCodingException - (only if allowPartialString is false) thrown if the bytes cannot be correctly decoded or a multibyte sequence is incomplete.

takeCompleteString

public <X extends Throwable> String takeCompleteString(Supplier<X> onCodingError)
                                                throws X

Take the completely decoded string.

Type Parameters:

X - The type of the exception thrown

Parameters:

onCodingError - A supplier of a Throwable to use if hasCodingErrors() returns true, or null for no error action

Returns:

The complete string.

Throws:

X - if hasCodingErrors() is true after complete().

takePartialString

public <X extends Throwable> String takePartialString(Supplier<X> onCodingError)
                                               throws X

Take the partially decoded string.

Type Parameters:

X - The type of the exception thrown

Parameters:

onCodingError - A supplier of a Throwable to use if hasCodingErrors() returns true, or null for no error action

Returns:

The complete string.

Throws:

X - if hasCodingErrors() is true after complete().

build

public String build()
             throws CharacterCodingException

Description copied from interface: CharsetStringBuilder

Build the completed string and reset the buffer.

Specified by:

build in interface CharsetStringBuilder

Returns:

The decoded built string which must be complete in regard to any multibyte sequences.

Throws:

CharacterCodingException - If the bytes cannot be correctly decoded or a multibyte sequence is incomplete.