Module org.postgresql.pljava

Package org.postgresql.pljava.model

Interface CharsetEncoding

All Known Implementing Classes:

CharsetEncoding.Any

public interface CharsetEncoding

Represents one of PostgreSQL's available character set encodings.

Not all of the encodings that PostgreSQL supports for communication with the client are also supported for use in the backend and in storage. The usableOnServer method identifies which ones are suitable as server encodings.

The encoding that is in use for the current database cannot change during a session, and is found in the final SERVER_ENCODING field.

The encoding currently in use by the connected client may change during a session, and is returned by the clientEncoding method.

The charset method returns the corresponding Java Charset if that can be identified, and several convenience methods are provided to decode or encode values accordingly.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	CharsetEncoding.Any	A distinguished CharsetEncoding representing uses such as -1 in the collencoding column of pg_collation, indicating the collation is usable with any encoding.

Field Summary

Fields

Modifier and Type	Field	Description
static final CharsetEncoding.Any	ANY	A distinguished CharsetEncoding representing uses such as -1 in the collencoding column of pg_collation, indicating the collation is usable with any encoding.
static final CharsetEncoding	SERVER_ENCODING

Method Summary

Modifier and Type	Method	Description
Charset	charset()	Returns the corresponding Java Charset, or null if none can be identified.
static CharsetEncoding	clientEncoding()	Returns the encoding currently selected by the connected client.
default CharBuffer	decode(ByteBuffer bb)	Decode bytes to characters, with exceptions reported.
default CharBuffer	decode(Datum.Input in, boolean close)	Decode bytes to characters, with exceptions reported.
default ByteBuffer	encode(String s)	Encode characters to bytes, with exceptions reported.
default ByteBuffer	encode(CharBuffer cb)	Encode characters to bytes, with exceptions reported.
static CharsetEncoding	fromName(String name)	Returns the CharsetEncoding for the given PostgreSQL encoding name.
static CharsetEncoding	fromOrdinal(int ordinal)	Returns the CharsetEncoding for the given PostgreSQL encoding number (as used in the encoding columns of some system catalogs).
String	icuName()	Returns the name identifying this encoding in ICU (international components for Unicode), or null if its implementation in PostgreSQL does not define one.
String	name()	Returns the PostgreSQL name for this encoding.
default CharsetDecoder	newDecoder()	Returns a CharsetDecoder, configured to report all decoding errors (rather than silently substituting data), if charset() would return a non-null value.
default CharsetEncoder	newEncoder()	Returns a CharsetEncoder, configured to report all encoding errors (rather than silently substituting data), if charset() would return a non-null value.
int	ordinal()	Returns the PostgreSQL encoding number (as used in the encoding columns of some system catalogs) for this encoding.
default InputStreamReader	reader(InputStream in)	Return an InputStreamReader that reports exceptions.
boolean	usableOnServer()	Indicates whether this encoding is usable as a server encoding.
default OutputStreamWriter	writer(OutputStream out)	Return an OutputStreamWriter that reports exceptions.

Field Details

SERVER_ENCODING

static final CharsetEncoding SERVER_ENCODING

ANY

static final CharsetEncoding.Any ANY

A distinguished CharsetEncoding representing uses such as -1 in the collencoding column of pg_collation, indicating the collation is usable with any encoding.

This is its only instance.

Method Details

clientEncoding

static CharsetEncoding clientEncoding()

Returns the encoding currently selected by the connected client.

fromOrdinal

static CharsetEncoding fromOrdinal(int ordinal)

Returns the CharsetEncoding for the given PostgreSQL encoding number (as used in the encoding columns of some system catalogs).

Throws:

IllegalArgumentException - if the argument is not the ordinal of some known encoding

fromName

static CharsetEncoding fromName(String name)

Returns the CharsetEncoding for the given PostgreSQL encoding name.

Throws:

IllegalArgumentException - if the argument is not the name of some known encoding

ordinal

int ordinal()

Returns the PostgreSQL encoding number (as used in the encoding columns of some system catalogs) for this encoding.

name

String name()

Returns the PostgreSQL name for this encoding.

The PostgreSQL encoding names have a long history and may not match cleanly with more standardized names in modern libraries.

icuName

String icuName()

Returns the name identifying this encoding in ICU (international components for Unicode), or null if its implementation in PostgreSQL does not define one.

When present, the ICU name can be a better choice for matching encodings in other libraries.

usableOnServer

boolean usableOnServer()

Indicates whether this encoding is usable as a server encoding.

charset

Charset charset()

Returns the corresponding Java Charset, or null if none can be identified.

newDecoder

default CharsetDecoder newDecoder()

Returns a CharsetDecoder, configured to report all decoding errors (rather than silently substituting data), if charset() would return a non-null value.

newEncoder

default CharsetEncoder newEncoder()

Returns a CharsetEncoder, configured to report all encoding errors (rather than silently substituting data), if charset() would return a non-null value.

decode

default CharBuffer decode(ByteBuffer bb)
                   throws CharacterCodingException

Decode bytes to characters, with exceptions reported.

Unlike the corresponding convenience method on Charset, this method will throw exceptions rather than silently substituting characters. This is a database system; it doesn't go changing your data without telling you.

Other behaviors can be obtained by calling newDecoder and configuring it as desired.

Throws:

CharacterCodingException

encode

default ByteBuffer encode(CharBuffer cb)
                   throws CharacterCodingException

Encode characters to bytes, with exceptions reported.

Unlike the corresponding convenience method on Charset, this method will throw exceptions rather than silently substituting characters. This is a database system; it doesn't go changing your data without telling you.

Other behaviors can be obtained by calling newEncoder and configuring it as desired.

Throws:

CharacterCodingException

encode

default ByteBuffer encode(String s)
                   throws CharacterCodingException

Encode characters to bytes, with exceptions reported.

Unlike the corresponding convenience method on Charset, this method will throw exceptions rather than silently substituting characters. This is a database system; it doesn't go changing your data without telling you.

Other behaviors can be obtained by calling newEncoder and configuring it as desired.

Throws:

CharacterCodingException

decode

default CharBuffer decode(Datum.Input in,
 boolean close)
                   throws SQLException,
IOException

Decode bytes to characters, with exceptions reported.

The input Datum is pinned around the decoding operation.

Throws:

SQLException

IOException

reader

default InputStreamReader reader(InputStream in)

Return an InputStreamReader that reports exceptions.

Other behaviors can be obtained by calling newDecoder and configuring it as desired before constructing an InputStreamReader.

writer

default OutputStreamWriter writer(OutputStream out)

Return an OutputStreamWriter that reports exceptions.

Other behaviors can be obtained by calling newEncoder and configuring it as desired before constructing an OutputStreamWriter.