com.amazon.ion

Interface SymbolTable

public interface SymbolTable

A symbol table maps symbols between their textual form and an integer ID used in the binary encoding.

WARNING: This interface should not be implemented or extended by code outside of this library.

There are two kinds of symbol tables: shared and local. With that, there are two further distinctions of shared symbol tables: system and substitute.

Notes about Substitute symbol tables

Substitute tables are used when the relevant catalog cannot find an exact match, that is, the catalog cannot find an imported shared symtab with the same name, version and max_id.

In order to ensure that we retain the correct import declarations, a substitute table is created, substituting the originally matched shared symtab from the catalog. The substitute table in turns exposes the correct name, version and max_id for any callers that require it, and becomes a delegate of the substituted symtab's interface.

Implementations of this interface are safe for use by multiple threads.

See Also:

Ion Symbols page

Field Summary

Fields

Modifier and Type	Field and Description
static int	UNKNOWN_SYMBOL_ID Indicates that a symbol's integer ID could not be determined.

Method Summary

Modifier and Type	Method and Description
SymbolToken	find(java.lang.String text) Finds a symbol already interned by this table.
java.lang.String	findKnownSymbol(int id) Gets the interned text for a symbol ID.
int	findSymbol(java.lang.String name) Gets the symbol ID associated with a given symbol name.
int	getImportedMaxId() Gets the highest symbol id reserved by this table's imports (including system symbols).
SymbolTable[]	getImportedTables() Gets the sequence of shared symbol tables imported by this (local) symbol table.
java.lang.String	getIonVersionId() Gets the identifier for the Ion version (and thus the system symbol table) used by this table.
int	getMaxId() Gets the highest symbol id reserved by this table.
java.lang.String	getName() Gets the unique name of this symbol table.
SymbolTable	getSystemSymbolTable() Gets the system symbol table being used by this local table.
int	getVersion() Gets the version of this symbol table.
SymbolToken	intern(java.lang.String text) Adds a new symbol to this table, or finds an existing definition of it.
boolean	isLocalTable() Determines whether this symbol table is local, and therefore unnamed and unversioned.
boolean	isReadOnly() Determines whether this symbol table can have symbols added to it.
boolean	isSharedTable() Determines whether this symbol table is shared, and therefore named, versioned, and read-only.
boolean	isSubstitute() Determines whether this instance is substituting for an imported shared table for which no exact match was found in the catalog.
boolean	isSystemTable() Determines whether this symbol table is a system symbol table, and therefore shared, named, versioned, and read-only.
java.util.Iterator<java.lang.String>	iterateDeclaredSymbolNames() Creates an iterator that will return all non-imported symbol names, in order of their symbol IDs.
void	makeReadOnly() Prevents this symbol table from accepting any more new symbols.
void	writeTo(IonWriter writer) Writes an Ion representation of this symbol table.

Field Detail

UNKNOWN_SYMBOL_ID

static final int UNKNOWN_SYMBOL_ID

Indicates that a symbol's integer ID could not be determined. That's generally the case when constructing value instances that are not yet contained by a datagram.

See Also:

Constant Field Values

Method Detail

getName

java.lang.String getName()

Gets the unique name of this symbol table.

Returns:

the unique name, or null if isLocalTable().

getVersion

int getVersion()

Gets the version of this symbol table.

Returns:

at least one, or zero if isLocalTable().

isLocalTable

boolean isLocalTable()

Determines whether this symbol table is local, and therefore unnamed and unversioned.

If this method returns true, then both isSharedTable() and isSystemTable() will return false.

isSharedTable

boolean isSharedTable()

Determines whether this symbol table is shared, and therefore named, versioned, and read-only.

If this method returns true, then isLocalTable() will return false.

isSubstitute

boolean isSubstitute()

Determines whether this instance is substituting for an imported shared table for which no exact match was found in the catalog. Such tables are not authoritative and may not even have any symbol text at all (as is the case when no version of an imported table is found).

Substitute tables are always shared, non-system tables.

isSystemTable

boolean isSystemTable()

Determines whether this symbol table is a system symbol table, and therefore shared, named, versioned, and read-only.

If this method returns true, then isLocalTable() will return false and isSharedTable() will return true.

isReadOnly

boolean isReadOnly()

Determines whether this symbol table can have symbols added to it. Shared symtabs are always read-only. Local symtabs can also be made read-only on demand, which enables some optimizations when writing data but will cause failures if new symbols are encountered.

Returns:

true if this table is read-only, false if symbols may be added.

See Also:

makeReadOnly()

makeReadOnly

void makeReadOnly()

Prevents this symbol table from accepting any more new symbols. Shared symtabs are always read-only. Making a local symtab read-only enables some optimizations when writing data, but will cause failures if new symbols are encountered.

See Also:

isReadOnly()

getSystemSymbolTable

SymbolTable getSystemSymbolTable()

Gets the system symbol table being used by this local table.

If isSystemTable() then this method returns this. Otherwise, if isSharedTable() then this method returns null.

Returns:

not null, except for non-system shared tables.

getIonVersionId

java.lang.String getIonVersionId()

Gets the identifier for the Ion version (and thus the system symbol table) used by this table. The version identifier is a string of the form "$ion_X_Y".

Returns:

the version identifier; or null for non-system shared tables.

getImportedTables

SymbolTable[] getImportedTables()

Gets the sequence of shared symbol tables imported by this (local) symbol table. The result does not include a system table.

If this local table imported a shared table for which the relevant IonCatalog has the same name but different version and/or max_id, then that entry will be a substitute table with the correct version and max_id, wrapping the original shared symbol table that was found.

If this local table imported a shared table for which the relevant IonCatalog has no entry with the same name, but the import declaration has a max_id available, then that entry will be a substitute table with max_id undefined symbols.

Returns:

null if this is a shared or system table, otherwise a non-null but potentially zero-length array of shared tables (but no system table).

getImportedMaxId

int getImportedMaxId()

Gets the highest symbol id reserved by this table's imports (including system symbols). Any id higher than this value is a local symbol declared by this table. This value is zero for shared symbol tables, since they do not utilize imports.

getMaxId

int getMaxId()

Gets the highest symbol id reserved by this table.

Returns:

the largest integer such that findKnownSymbol(int) could return a non-null result. Note that there is no promise that it will return a name, only that any larger id will not have a name defined.

intern

SymbolToken intern(java.lang.String text)

Adds a new symbol to this table, or finds an existing definition of it.

The resulting SymbolToken has the same String instance that was first interned. In order to reduce memory footprint, callers should generally replace their copy of the text with the string in the result.

This method will not necessarily return the same instance given the same input.

Parameters:

text - the symbol text to intern.

Returns:

the interned symbol, with both text and SID defined; not null.

Throws:

IonException - if this symtab isReadOnly() and the text isn't already interned.

See Also:

find(String)

find

SymbolToken find(java.lang.String text)

Finds a symbol already interned by this table.

This method will not necessarily return the same instance given the same input.

Parameters:

text - the symbol text to find.

Returns:

the interned symbol, with both text and SID defined; or null if it's not already interned.

See Also:

intern(String)

findSymbol

int findSymbol(java.lang.String name)

Gets the symbol ID associated with a given symbol name.

Parameters:

name - must not be null or empty.

Returns:

the id of the requested symbol, or UNKNOWN_SYMBOL_ID if it's not defined.

Throws:

java.lang.NullPointerException - if name is null.

findKnownSymbol

java.lang.String findKnownSymbol(int id)

Gets the interned text for a symbol ID.

Parameters:

id - the requested symbol ID.

Returns:

the interned text associated with the symbol ID, or null if the text is not known.

Throws:

java.lang.IllegalArgumentException - if id < 1.

iterateDeclaredSymbolNames

java.util.Iterator<java.lang.String> iterateDeclaredSymbolNames()

Creates an iterator that will return all non-imported symbol names, in order of their symbol IDs. The iterator will return null where there is an undefined sid.

The first string returned by the iterator has a symbol ID that is one more than getImportedMaxId(), and the last string has symbol ID equals to getMaxId().

Returns:

a new iterator.

writeTo

void writeTo(IonWriter writer)
      throws java.io.IOException

Writes an Ion representation of this symbol table.

Parameters:

writer - must not be null.

Throws:

java.io.IOException - if thrown by the writer.