public interface SymbolTable
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.
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.
Modifier and Type | Field and Description |
---|---|
static int |
UNKNOWN_SYMBOL_ID
Indicates that a symbol's integer ID could not be determined.
|
Modifier and Type | Method and Description |
---|---|
SymbolToken |
find(String text)
Finds a symbol already interned by this table.
|
String |
findKnownSymbol(int id)
Gets the interned text for a symbol ID.
|
int |
findSymbol(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.
|
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.
|
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(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.
|
Iterator<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.
|
static final int UNKNOWN_SYMBOL_ID
String getName()
null
if isLocalTable()
.int getVersion()
isLocalTable()
.boolean isLocalTable()
If this method returns true
, then both isSharedTable()
and isSystemTable()
will return false
.
boolean isSharedTable()
If this method returns true
, then isLocalTable()
will return false
.
boolean isSubstitute()
Substitute tables are always shared, non-system tables.
boolean isSystemTable()
If this method returns true
, then isLocalTable()
will return false
and isSharedTable()
will return
true
.
boolean isReadOnly()
makeReadOnly()
void makeReadOnly()
isReadOnly()
SymbolTable getSystemSymbolTable()
If isSystemTable()
then this method returns this
.
Otherwise, if isSharedTable()
then this method returns
null
.
null
, except for non-system shared tables.String getIonVersionId()
"$ion_X_Y"
.null
for non-system shared
tables.SymbolTable[] getImportedTables()
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.
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).int getImportedMaxId()
int getMaxId()
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.SymbolToken intern(String text)
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.
text
- the symbol text to intern.IonException
- if this symtab isReadOnly()
and
the text isn't already interned.find(String)
SymbolToken find(String text)
This method will not necessarily return the same instance given the same input.
text
- the symbol text to find.null
if it's not already interned.intern(String)
int findSymbol(String name)
name
- must not be null or empty.UNKNOWN_SYMBOL_ID
if it's not defined.NullPointerException
- if name
is null.EmptySymbolException
- if name
is empty.String findKnownSymbol(int id)
id
- the requested symbol ID.null
if the text is not known.IllegalArgumentException
- if id < 1
.Iterator<String> iterateDeclaredSymbolNames()
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()
.
void writeTo(IonWriter writer) throws IOException
writer
- must not be null.IOException
- if thrown by the writer.