Top Description Inners Fields Constructors Methods
org.eclipse.jetty.util

public Class Utf8StringBuilder

extends Object
implements CharsetStringBuilder
Class Inheritance
All Implemented Interfaces
org.eclipse.jetty.util.CharsetStringBuilder
Known Direct Subclasses
org.eclipse.jetty.util.CharsetStringBuilder.ReportingUtf8StringBuilder
Imports
java.io.IOException, java.nio.ByteBuffer, java.nio.charset.CharacterCodingException, java.util.function.Supplier, org.slf4j.Logger, .LoggerFactory

UTF-8 StringBuilder.

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
{@link CharsetStringBuilder} for decoding of arbitrary java.nio.charset.Charsets.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static class
Utf8StringBuilder.Utf8CharacterCodingException

public static class
Utf8StringBuilder.Utf8IllegalArgumentException

Field Summary

Modifier and TypeField and Description
pack-priv final StringBuilder
_buffer

private int
_codep

private boolean
_codingErrors

protected int
_state

private static final byte[]
BYTE_TABLE

protected static final Logger
LOG

public static final char
REPLACEMENT

private static final byte[]
TRANS_TABLE

private static final int
UTF8_ACCEPT

private static final int
UTF8_REJECT

Constructor Summary

AccessConstructor and Description
public
Utf8StringBuilder()

public
Utf8StringBuilder(int capacity)

protected
Utf8StringBuilder(StringBuilder buffer)

Method Summary

Modifier and TypeMethod and Description
public void
append(char
A decoded character to append
c)

Implements org.eclipse.jetty.util.CharsetStringBuilder.append.

public void
append(String s)

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

public void
append(byte
An encoded byte to append
b)

Implements org.eclipse.jetty.util.CharsetStringBuilder.append.

public void
append(ByteBuffer
Buffer of encoded bytes to append. The bytes are consumed from the buffer.
buf)

Overrides default org.eclipse.jetty.util.CharsetStringBuilder.append.

public void
append(byte[]
Array of encoded bytes to append
b)

Overrides default org.eclipse.jetty.util.CharsetStringBuilder.append.

public void
append(byte[]
Array of encoded bytes
b, int
offset into the array
offset, int
the number of bytes to append from the array.
length)

Overrides default org.eclipse.jetty.util.CharsetStringBuilder.append.

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

public void
appendByte(byte b)

protected void
bufferAppend(char c)

protected void
bufferReset()

public String
build()

Implements org.eclipse.jetty.util.CharsetStringBuilder.build.

Build the completed string and reset the buffer.

protected void
checkCharAppend()

public void
complete()

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

public boolean

Returns:

True if the characters decoded have contained UTF8 coding errors.
hasCodingErrors()

public boolean

Returns:

True if the appended sequences are complete UTF-8 sequences.
isComplete()

public int
length()

Implements org.eclipse.jetty.util.CharsetStringBuilder.length.

public void
partialReset()

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

public void
reset()

Implements org.eclipse.jetty.util.CharsetStringBuilder.reset.

Reset the appendable, clearing the buffer, resetting decoding state and clearing any errors.
public <
The type of the exception thrown
X extends Throwable> String

Returns:

The complete string.
takeCompleteString(Supplier<X>
A supplier of a Throwable to use if hasCodingErrors() returns true, or null for no error action
onCodingError)

Take the completely decoded string.

public <
The type of the exception thrown
X extends Throwable> String

Returns:

The complete string.
takePartialString(Supplier<X>
A supplier of a Throwable to use if hasCodingErrors() returns true, or null for no error action
onCodingError)

Take the partially decoded string.

public String

Returns:

The completely decoded string.
toCompleteString()

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

public String

Returns:

The currently decoded string, excluding any partial sequences appended.
toPartialString()

public String

Returns:

The currently decoded string, excluding any partial sequences appended.
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

_bufferback to summary
pack-priv final StringBuilder _buffer
_codepback to summary
private int _codep
_codingErrorsback to summary
private boolean _codingErrors
_stateback to summary
protected int _state
BYTE_TABLEback to summary
private static final byte[] BYTE_TABLE
LOGback to summary
protected static final Logger LOG
REPLACEMENTback to summary
public static final char REPLACEMENT
TRANS_TABLEback to summary
private static final byte[] TRANS_TABLE
UTF8_ACCEPTback to summary
private static final int UTF8_ACCEPT
UTF8_REJECTback to summary
private static final int UTF8_REJECT

Constructor Detail

Utf8StringBuilderback to summary
public Utf8StringBuilder()
Utf8StringBuilderback to summary
public Utf8StringBuilder(int capacity)
Utf8StringBuilderback to summary
protected Utf8StringBuilder(StringBuilder buffer)

Method Detail

appendback to summary
public void append(char c)

Implements org.eclipse.jetty.util.CharsetStringBuilder.append.

Parameters
c:char

Doc from org.eclipse.jetty.util.CharsetStringBuilder.append.

A decoded character to append

appendback to summary
public void append(String s)
appendback to summary
public void append(String s, int offset, int length)
appendback to summary
public void append(byte b)

Implements org.eclipse.jetty.util.CharsetStringBuilder.append.

Parameters
b:byte

Doc from org.eclipse.jetty.util.CharsetStringBuilder.append.

An encoded byte to append

Annotations
@Override
appendback to summary
public void append(ByteBuffer buf)

Overrides default org.eclipse.jetty.util.CharsetStringBuilder.append.

Parameters
buf:ByteBuffer

Doc from org.eclipse.jetty.util.CharsetStringBuilder.append.

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

Annotations
@Override
appendback to summary
public void append(byte[] b)

Overrides default org.eclipse.jetty.util.CharsetStringBuilder.append.

Parameters
b:byte[]

Doc from org.eclipse.jetty.util.CharsetStringBuilder.append.

Array of encoded bytes to append

Annotations
@Override
appendback to summary
public void append(byte[] b, int offset, int length)

Overrides default org.eclipse.jetty.util.CharsetStringBuilder.append.

Parameters
b:byte[]

Doc from org.eclipse.jetty.util.CharsetStringBuilder.append.

Array of encoded bytes

offset:int

Doc from org.eclipse.jetty.util.CharsetStringBuilder.append.

offset into the array

length:int

Doc from org.eclipse.jetty.util.CharsetStringBuilder.append.

the number of bytes to append from the array.

Annotations
@Override
appendback to summary
public boolean append(byte[] b, int offset, int length, int maxChars)
appendByteback to summary
public void appendByte(byte b) throws IOException
bufferAppendback to summary
protected void bufferAppend(char c)
bufferResetback to summary
protected void bufferReset()
buildback to summary
public String build() throws CharacterCodingException

Implements org.eclipse.jetty.util.CharsetStringBuilder.build.

Doc from org.eclipse.jetty.util.CharsetStringBuilder.build.

Build the completed string and reset the buffer.

Returns:String

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

Annotations
@Override
Exceptions
CharacterCodingException:
If the bytes cannot be correctly decoded or a multibyte sequence is incomplete.
checkCharAppendback to summary
protected void checkCharAppend()
completeback to summary
public void complete()

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

hasCodingErrorsback to summary
public boolean hasCodingErrors()
Returns:boolean

True if the characters decoded have contained UTF8 coding errors.

isCompleteback to summary
public boolean isComplete()
Returns:boolean

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

lengthback to summary
public int length()

Implements org.eclipse.jetty.util.CharsetStringBuilder.length.

Returns:int

Doc from org.eclipse.jetty.util.CharsetStringBuilder.length.

the length in characters

Annotations
@Override
partialResetback to summary
public void partialReset()

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

resetback to summary
public void reset()

Implements org.eclipse.jetty.util.CharsetStringBuilder.reset.

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

Annotations
@Override
takeCompleteStringback to summary
public <X extends Throwable> String takeCompleteString(Supplier<X> onCodingError) throws Supplier-:X

Take the completely decoded string.

Parameters
<X>
The type of the exception thrown
onCodingError:Supplier<X>

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

Returns:String

The complete string.

Exceptions
Supplier-:X:
if hasCodingErrors() is true after complete().
takePartialStringback to summary
public <X extends Throwable> String takePartialString(Supplier<X> onCodingError) throws Supplier-:X

Take the partially decoded string.

Parameters
<X>
The type of the exception thrown
onCodingError:Supplier<X>

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

Returns:String

The complete string.

Exceptions
Supplier-:X:
if hasCodingErrors() is true after complete().
toCompleteStringback to summary
public String toCompleteString()

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

Returns:String

The completely decoded string.

toPartialStringback to summary
public String toPartialString()
Returns:String

The currently decoded string, excluding any partial sequences appended.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

The currently decoded string, excluding any partial sequences appended.

Annotations
@Override
org.eclipse.jetty.util back to summary

public Class Utf8StringBuilder.Utf8CharacterCodingException

extends CharacterCodingException
Class Inheritance

Constructor Summary

AccessConstructor and Description
public
Utf8CharacterCodingException()

Method Summary

Modifier and TypeMethod and Description
public String
getMessage()

Overrides java.lang.Throwable.getMessage.

Returns the detail message string of this throwable.
public String
toString()

Overrides java.lang.Throwable.toString.

Returns a short description of this throwable.

Constructor Detail

Utf8CharacterCodingExceptionback to summary
public Utf8CharacterCodingException()

Method Detail

getMessageback to summary
public String getMessage()

Overrides java.lang.Throwable.getMessage.

Doc from java.lang.Throwable.getMessage.

Returns the detail message string of this throwable.

Returns:String

the detail message string of this Throwable instance (which may be null).

Annotations
@Override
toStringback to summary
public String toString()

Overrides java.lang.Throwable.toString.

Doc from java.lang.Throwable.toString.

Returns a short description of this throwable. The result is the concatenation of:

  • the name of the class of this object
  • ": " (a colon and a space)
  • the result of invoking this object's getLocalizedMessage method
If getLocalizedMessage returns null, then just the class name is returned.
Returns:String

a string representation of this throwable.

Annotations
@Override
org.eclipse.jetty.util back to summary

public Class Utf8StringBuilder.Utf8IllegalArgumentException

extends IllegalArgumentException
Class Inheritance

Constructor Summary

AccessConstructor and Description
public
Utf8IllegalArgumentException()

Constructor Detail

Utf8IllegalArgumentExceptionback to summary
public Utf8IllegalArgumentException()