Top Description Fields Constructors Methods
com.amazon.ion.impl

pack-priv final Class SharedSymbolTable

extends Object
implements SymbolTable
Class Inheritance
All Implemented Interfaces
com.amazon.ion.SymbolTable
Static Imports
com.amazon.ion.SystemSymbols.ION, .SystemSymbols.ION_1_0, .SystemSymbols.NAME_SID, .SystemSymbols.SYMBOLS_SID, .SystemSymbols.VERSION_SID, com.amazon.ion.impl._Private_Utils.getSidForSymbolTableField

An immutable shared symbol table, supporting (non-system) shared symbol tables and system symbol tables.

Instances of this class are safe for use by multiple threads.

Field Summary

Modifier and TypeField and Description
private static final SymbolTable
ION_1_0_SYSTEM_SYMTAB

The singleton instance of Ion 1.0 system symbol table.

private final String
myName

The name of this shared symbol table.

private final String[]
mySymbolNames

The names (aka text) of declared symbols in this shared symbol table (that are not imported from some other symbol table); never null.

private final Map<String, Integer>
mySymbolsMap

Map of symbol names to symbol ids of declared symbols.

private final int
myVersion

The version of this shared symbol table.

private static final String[]
SYSTEM_SYMBOLS

The array of system symbols as defined by Ion 1.0.

Constructor Summary

AccessConstructor and Description
private
SharedSymbolTable(String name, int version, List<String> symbolsList, Map<String, Integer> symbolsMap)

private
SharedSymbolTable(String name, int version, String[] symbolNames, Map<String, Integer> symbolsMap)

Method Summary

Modifier and TypeMethod and Description
public SymbolToken
find(String
the symbol text to find.
text
)

Implements com.amazon.ion.SymbolTable.find.

Finds a symbol already interned by this table.

public String
findKnownSymbol(int
the requested symbol ID.
id
)

Implements com.amazon.ion.SymbolTable.findKnownSymbol.

Gets the interned text for a symbol ID.

public int
findSymbol(String
must not be null or empty.
name
)

Implements com.amazon.ion.SymbolTable.findSymbol.

Gets the symbol ID associated with a given symbol name.

public int
getImportedMaxId()

Implements com.amazon.ion.SymbolTable.getImportedMaxId.

Gets the highest symbol id reserved by this table's imports (including system symbols).

public SymbolTable[]
getImportedTables()

Implements com.amazon.ion.SymbolTable.getImportedTables.

Gets the sequence of shared symbol tables imported by this (local) symbol table.

public String
getIonVersionId()

Implements com.amazon.ion.SymbolTable.getIonVersionId.

Gets the identifier for the Ion version (and thus the system symbol table) used by this table.

public int
getMaxId()

Implements com.amazon.ion.SymbolTable.getMaxId.

Gets the highest symbol id reserved by this table.

public String
getName()

Implements com.amazon.ion.SymbolTable.getName.

Gets the unique name of this symbol table.

pack-priv static SymbolTable
getSystemSymbolTable(int
the specified version of the system symbol table; currently, only version 1 (Ion 1.0) is supported
version
)

Gets a specific version of the system symbol table.

public SymbolTable
getSystemSymbolTable()

Implements com.amazon.ion.SymbolTable.getSystemSymbolTable.

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

public int
getVersion()

Implements com.amazon.ion.SymbolTable.getVersion.

Gets the version of this symbol table.

public SymbolToken
intern(String
the symbol text to intern.
text
)

Implements com.amazon.ion.SymbolTable.intern.

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

public boolean
isLocalTable()

Implements com.amazon.ion.SymbolTable.isLocalTable.

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

public boolean
isReadOnly()

Implements com.amazon.ion.SymbolTable.isReadOnly.

Determines whether this symbol table can have symbols added to it.

public boolean
isSharedTable()

Implements com.amazon.ion.SymbolTable.isSharedTable.

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

public boolean
isSubstitute()

Implements com.amazon.ion.SymbolTable.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()

Implements com.amazon.ion.SymbolTable.isSystemTable.

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

public Iterator<String>
iterateDeclaredSymbolNames()

Implements com.amazon.ion.SymbolTable.iterateDeclaredSymbolNames.

Creates an iterator that will return all non-imported symbol names, in order of their symbol IDs.

public void
makeReadOnly()

Implements com.amazon.ion.SymbolTable.makeReadOnly.

Prevents this symbol table from accepting any more new symbols.

pack-priv static SymbolTable
newSharedSymbolTable(String
the name of the new shared symbol table
name
,
int
the version of the new shared symbol table
version
,
SymbolTable
may be null
priorSymtab
,
Iterator<String>
never null
symbols
)

Constructs a new shared symbol table from the parameters.

pack-priv static SymbolTable
newSharedSymbolTable(IonStruct
the IonStruct representing the new shared symbol table
ionRep
)

Constructs a new shared symbol table represented by the passed in IonStruct.

pack-priv static SymbolTable
newSharedSymbolTable(IonReader
the IonReader positioned on the shared symbol table represented as an IonStruct
reader
,
boolean
denotes whether the IonReader is already positioned on the struct; false if it is positioned before the struct
isOnStruct
)

Constructs a new shared symbol table represented by the current value of the passed in IonReader.

private static void
prepSymbolsListAndMap(SymbolTable priorSymtab, Iterator<String> symbols, List<String> symbolsList, Map<String, Integer> symbolsMap)

Collects the necessary symbols from priorSymtab and symbols, and load them into the passed-in symbolsList and symbolsMap.

private static void
putToMapIfNotThere(Map<String, Integer> symbolsMap, String text, int sid)

private static void
transferNonExistingSymbols(List<String> symbolsList, Map<String, Integer> symbolsMap)

Transfer symbols from symbolsList to symbolsMap that doesn't already exist in the map.

public void
writeTo(IonWriter
must not be null.
writer
)

Implements com.amazon.ion.SymbolTable.writeTo.

Writes an Ion representation of this symbol table.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

ION_1_0_SYSTEM_SYMTABback to summary
private static final SymbolTable ION_1_0_SYSTEM_SYMTAB

The singleton instance of Ion 1.0 system symbol table.

TODO amazon-ion/ion-java/issues/34 Optimize system symtabs by using our custom backing impl.

myNameback to summary
private final String myName

The name of this shared symbol table. If this is a system symbol table, it is SystemSymbols#ION.

mySymbolNamesback to summary
private final String[] mySymbolNames

The names (aka text) of declared symbols in this shared symbol table (that are not imported from some other symbol table); never null. The sid of the first element is 1.

Note that null references are valid elements within this member field, denoting undefined symbol IDs ("gaps").

mySymbolsMapback to summary
private final Map<String, Integer> mySymbolsMap

Map of symbol names to symbol ids of declared symbols.

myVersionback to summary
private final int myVersion

The version of this shared symbol table.

SYSTEM_SYMBOLSback to summary
private static final String[] SYSTEM_SYMBOLS

The array of system symbols as defined by Ion 1.0.

Constructor Detail

SharedSymbolTableback to summary
private SharedSymbolTable(String name, int version, List<String> symbolsList, Map<String, Integer> symbolsMap)
SharedSymbolTableback to summary
private SharedSymbolTable(String name, int version, String[] symbolNames, Map<String, Integer> symbolsMap)

Method Detail

findback to summary
public SymbolToken find(String text)

Implements com.amazon.ion.SymbolTable.find.

Doc from com.amazon.ion.SymbolTable.find.

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.

findKnownSymbolback to summary
public String findKnownSymbol(int id)

Implements com.amazon.ion.SymbolTable.findKnownSymbol.

Doc from com.amazon.ion.SymbolTable.findKnownSymbol.

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.

findSymbolback to summary
public int findSymbol(String name)

Implements com.amazon.ion.SymbolTable.findSymbol.

Doc from com.amazon.ion.SymbolTable.findSymbol.

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.

getImportedMaxIdback to summary
public int getImportedMaxId()

Implements com.amazon.ion.SymbolTable.getImportedMaxId.

Doc from com.amazon.ion.SymbolTable.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.

getImportedTablesback to summary
public SymbolTable[] getImportedTables()

Implements com.amazon.ion.SymbolTable.getImportedTables.

Doc from com.amazon.ion.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).

getIonVersionIdback to summary
public String getIonVersionId()

Implements com.amazon.ion.SymbolTable.getIonVersionId.

Doc from com.amazon.ion.SymbolTable.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.

getMaxIdback to summary
public int getMaxId()

Implements com.amazon.ion.SymbolTable.getMaxId.

Doc from com.amazon.ion.SymbolTable.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.

getNameback to summary
public String getName()

Implements com.amazon.ion.SymbolTable.getName.

Doc from com.amazon.ion.SymbolTable.getName.

Gets the unique name of this symbol table.

Returns:String

the unique name, or null if isLocalTable().

getSystemSymbolTableback to summary
pack-priv static SymbolTable getSystemSymbolTable(int version)

Gets a specific version of the system symbol table.

Parameters
version:int

the specified version of the system symbol table; currently, only version 1 (Ion 1.0) is supported

Exceptions
IllegalArgumentException:
if the specified version isn't supported
getSystemSymbolTableback to summary
public SymbolTable getSystemSymbolTable()

Implements com.amazon.ion.SymbolTable.getSystemSymbolTable.

Doc from com.amazon.ion.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.

getVersionback to summary
public int getVersion()

Implements com.amazon.ion.SymbolTable.getVersion.

Doc from com.amazon.ion.SymbolTable.getVersion.

Gets the version of this symbol table.

Returns:int

at least one, or zero if isLocalTable().

internback to summary
public SymbolToken intern(String text)

Implements com.amazon.ion.SymbolTable.intern.

Doc from com.amazon.ion.SymbolTable.intern.

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.

isLocalTableback to summary
public boolean isLocalTable()

Implements com.amazon.ion.SymbolTable.isLocalTable.

Doc from com.amazon.ion.SymbolTable.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.

isReadOnlyback to summary
public boolean isReadOnly()

Implements com.amazon.ion.SymbolTable.isReadOnly.

Doc from com.amazon.ion.SymbolTable.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.

isSharedTableback to summary
public boolean isSharedTable()

Implements com.amazon.ion.SymbolTable.isSharedTable.

Doc from com.amazon.ion.SymbolTable.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.

isSubstituteback to summary
public boolean isSubstitute()

Implements com.amazon.ion.SymbolTable.isSubstitute.

Doc from com.amazon.ion.SymbolTable.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.

isSystemTableback to summary
public boolean isSystemTable()

Implements com.amazon.ion.SymbolTable.isSystemTable.

Doc from com.amazon.ion.SymbolTable.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.

iterateDeclaredSymbolNamesback to summary
public Iterator<String> iterateDeclaredSymbolNames()

Implements com.amazon.ion.SymbolTable.iterateDeclaredSymbolNames.

Doc from com.amazon.ion.SymbolTable.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.

makeReadOnlyback to summary
public void makeReadOnly()

Implements com.amazon.ion.SymbolTable.makeReadOnly.

Doc from com.amazon.ion.SymbolTable.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.

newSharedSymbolTableback to summary
pack-priv static SymbolTable newSharedSymbolTable(String name, int version, SymbolTable priorSymtab, Iterator<String> symbols)

Constructs a new shared symbol table from the parameters.

As per IonSystem#newSharedSymbolTable(String, int, Iterator, SymbolTable...), any duplicate or null symbol texts are skipped.

Therefore, THIS METHOD IS NOT SUITABLE WHEN READING SERIALIZED SHARED SYMBOL TABLES since that scenario must preserve all sids.

Parameters
name:String

the name of the new shared symbol table

version:int

the version of the new shared symbol table

priorSymtab:SymbolTable

may be null

symbols:Iterator<String>

never null

newSharedSymbolTableback to summary
pack-priv static SymbolTable newSharedSymbolTable(IonStruct ionRep)

Constructs a new shared symbol table represented by the passed in IonStruct.

Parameters
ionRep:IonStruct

the IonStruct representing the new shared symbol table

newSharedSymbolTableback to summary
pack-priv static SymbolTable newSharedSymbolTable(IonReader reader, boolean isOnStruct)

Constructs a new shared symbol table represented by the current value of the passed in IonReader.

Parameters
reader:IonReader

the IonReader positioned on the shared symbol table represented as an IonStruct

isOnStruct:boolean

denotes whether the IonReader is already positioned on the struct; false if it is positioned before the struct

prepSymbolsListAndMapback to summary
private static void prepSymbolsListAndMap(SymbolTable priorSymtab, Iterator<String> symbols, List<String> symbolsList, Map<String, Integer> symbolsMap)

Collects the necessary symbols from priorSymtab and symbols, and load them into the passed-in symbolsList and symbolsMap.

putToMapIfNotThereback to summary
private static void putToMapIfNotThere(Map<String, Integer> symbolsMap, String text, int sid)
transferNonExistingSymbolsback to summary
private static void transferNonExistingSymbols(List<String> symbolsList, Map<String, Integer> symbolsMap)

Transfer symbols from symbolsList to symbolsMap that doesn't already exist in the map.

writeToback to summary
public void writeTo(IonWriter writer) throws IOException

Implements com.amazon.ion.SymbolTable.writeTo.

Doc from com.amazon.ion.SymbolTable.writeTo.

Writes an Ion representation of this symbol table.

Parameters
writer:IonWriter

must not be null.

Exceptions
IOException:
if thrown by the writer.