Ion Java 1.11.10 · com.amazon.ion.SymbolTable · APIdia, the JavaDoc alternative

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

Method Summary

Modifier and Type	Method and Description
public SymbolToken	Returns: the interned symbol, with both text and SID defined; or `null` if it's not already interned. find(String the symbol text to find. text) Finds a symbol already interned by this table.
public String	Returns: the interned text associated with the symbol ID, or `null` if the text is not known. findKnownSymbol(int the requested symbol ID. id) Gets the interned text for a symbol ID.
public int	Returns: the id of the requested symbol, or `UNKNOWN_SYMBOL_ID` if it's not defined. findSymbol(String must not be null or empty. name) Gets the symbol ID associated with a given symbol name.
public int	getImportedMaxId() Gets the highest symbol id reserved by this table's imports (including system symbols).
public SymbolTable[]	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). getImportedTables() Gets the sequence of shared symbol tables imported by this (local) symbol table.
public String	Returns: the version identifier; or `null` for non-system shared tables. getIonVersionId() Gets the identifier for the Ion version (and thus the system symbol table) used by this table.
public int	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. getMaxId() Gets the highest symbol id reserved by this table.
public String	Returns: the unique name, or `null` if `isLocalTable()`. getName() Gets the unique name of this symbol table.
public SymbolTable	Returns: not `null`, except for non-system shared tables. getSystemSymbolTable() Gets the system symbol table being used by this local table.
public int	Returns: at least one, or zero if `isLocalTable()`. getVersion() Gets the version of this symbol table.
public SymbolToken	Returns: the interned symbol, with both text and SID defined; not null. intern(String the symbol text to intern. text) Adds a new symbol to this table, or finds an existing definition of it.
public boolean	isLocalTable() Determines whether this symbol table is local, and therefore unnamed and unversioned.
public boolean	Returns: true if this table is read-only, false if symbols may be added. isReadOnly() Determines whether this symbol table can have symbols added to it.
public boolean	isSharedTable() Determines whether this symbol table is shared, and therefore named, versioned, and read-only.
public boolean	isSubstitute() Determines whether this instance is substituting for an imported shared table for which no exact match was found in the catalog.
public boolean	isSystemTable() Determines whether this symbol table is a system symbol table, and therefore shared, named, versioned, and read-only.
public Iterator<String>	Returns: a new iterator. iterateDeclaredSymbolNames() Creates an iterator that will return all non-imported symbol names, in order of their symbol IDs.
public void	makeReadOnly() Prevents this symbol table from accepting any more new symbols.
public void	writeTo(IonWriter must not be null. writer) Writes an Ion representation of this symbol table.

UNKNOWN_SYMBOL_ID	back to summary
public 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.

Method Detail

find back to summary

find	back to summary
public SymbolToken find(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:String the symbol text to find. Returns:SymbolToken the interned symbol, with both text and SID defined; or `null` if it's not already interned. See Also `intern(String)`

public SymbolToken find(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:String: the symbol text to find.

Returns:SymbolToken

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

See Also

intern(String)

findKnownSymbol back to summary

findKnownSymbol	back to summary
public String findKnownSymbol(int id) Gets the interned text for a symbol ID. Parameters id:int the requested symbol ID. Returns:String the interned text associated with the symbol ID, or `null` if the text is not known. Exceptions IllegalArgumentException: if `id < 1`.

public String findKnownSymbol(int id)

Gets the interned text for a symbol ID.

Parameters

id:int: the requested symbol ID.

Returns:String

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

Exceptions

IllegalArgumentException:: if id < 1.

findSymbol back to summary

findSymbol	back to summary
public int findSymbol(String name) Gets the symbol ID associated with a given symbol name. Parameters name:String must not be null or empty. Returns:int the id of the requested symbol, or `UNKNOWN_SYMBOL_ID` if it's not defined. Exceptions NullPointerException: if `name` is null.

public int findSymbol(String name)

Gets the symbol ID associated with a given symbol name.

Parameters

name:String: must not be null or empty.

Returns:int

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

Exceptions

NullPointerException:: if name is null.

getImportedMaxId	back to summary
public 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.

getImportedTables back to summary

getImportedTables	back to summary
public 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:SymbolTable[] `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).

public 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:SymbolTable[]: 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).

getIonVersionId back to summary

getIonVersionId	back to summary
public 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:String the version identifier; or `null` for non-system shared tables.

public 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:String: the version identifier; or null for non-system shared tables.

getMaxId back to summary

getMaxId	back to summary
public int getMaxId() Gets the highest symbol id reserved by this table. Returns:int 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.

public int getMaxId()

Gets the highest symbol id reserved by this table.

Returns:int: 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.

getName back to summary

getName	back to summary
public String getName() Gets the unique name of this symbol table. Returns:String the unique name, or `null` if `isLocalTable()`.

public String getName()

Gets the unique name of this symbol table.

Returns:String: the unique name, or null if isLocalTable().

getSystemSymbolTable back to summary

getSystemSymbolTable	back to summary
public 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:SymbolTable not `null`, except for non-system shared tables.

public 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:SymbolTable: not null, except for non-system shared tables.

getVersion back to summary

getVersion	back to summary
public int getVersion() Gets the version of this symbol table. Returns:int at least one, or zero if `isLocalTable()`.

public int getVersion()

Gets the version of this symbol table.

Returns:int: at least one, or zero if isLocalTable().

intern back to summary

intern	back to summary
public SymbolToken intern(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:String the symbol text to intern. Returns:SymbolToken the interned symbol, with both text and SID defined; not null. Exceptions IonException: if this symtab `isReadOnly()` and the text isn't already interned. See Also `find(String)`

public SymbolToken intern(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:String: the symbol text to intern.

Returns:SymbolToken

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

Exceptions

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

See Also

find(String)

isLocalTable back to summary

isLocalTable	back to summary
public 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`.

public 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.

isReadOnly back to summary

isReadOnly	back to summary
public 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:boolean true if this table is read-only, false if symbols may be added. See Also `makeReadOnly()`

public 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:boolean: true if this table is read-only, false if symbols may be added.
See Also: makeReadOnly()

isSharedTable back to summary

isSharedTable	back to summary
public 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`.

public 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	back to summary
public 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.

isSubstitute

back to summary

public 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 back to summary

isSystemTable	back to summary
public 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`.

public 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.

iterateDeclaredSymbolNames back to summary

iterateDeclaredSymbolNames	back to summary
public Iterator<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:Iterator<String> a new iterator.

public Iterator<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:Iterator<String>: a new iterator.

makeReadOnly back to summary

makeReadOnly	back to summary
public 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()`

public 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()

writeTo	back to summary
public void writeTo(IonWriter writer) throws IOException Writes an Ion representation of this symbol table. Parameters writer:IonWriter must not be null. Exceptions IOException: if thrown by the writer.

writeTo

back to summary

public void writeTo(IonWriter writer) throws IOException

Writes an Ion representation of this symbol table.

Parameters

writer:IonWriter: must not be null.

Exceptions

IOException:: if thrown by the writer.

public Interface SymbolTable

Notes about Substitute symbol tables

Field Summary

Method Summary

Field Detail

Method Detail