public interface IonCatalog
IonSystem
.
It is expected that many applications will implement this interface to
customize behavior beyond that provided by the default SimpleCatalog
.
A typical implementation would retrieve symbol tables from some external
source.
To utilize a custom catalog, it must be given to the
IonSystemBuilder
before a system is built, or to
selected methods of the IonSystem
for localized use.
Catalog implementations should never accept substitute symbol
tables and never return them. Substitute tables are used when the
catalog cannot find an exact match, that is, the catalog cannot find an
imported shared symtab with the same name, version and max_id. Refer to
SymbolTable
.
This interface is the only abstraction point for caching shared
symbol tables. Within this library, there is no caching mechanism in place on
shared symbol tables that are loaded into the IonSystem
.
This means that when a shared symbol table needs to be retrieved by the
library's code-paths, methods of this interface are invoked directly,
without any additional caching whatsoever.
As such, implementors of this interface should implement their own caching
mechanism if desired.
When encoding Ion binary data, its always best to use an exact match to the requested version whenever possible. Earlier versions are very likely to be missing symbols that are needed by the data. Later versions of the table could have the same problem, but that's less likely under best practices.
While "get latest version" is generally okay for encoding, it's not universally acceptable: one can imagine a client/server protocol where the client declares what symtab/versions it can handle, and the server needs to meet those requirements.
Binary decoding prefers an exact match, and in a couple edge cases, requires it. Therefore a single "get latest version" method is insufficient. See the Ion Symbols page for more details on this topic.
It's expected that many if not most applications will implement a dynamic catalog that can fetch symtabs from some source. In such cases the catalog should make its best effort to find an exact match, and if that's not possible fall back to the best match it can acquire.
Modifier and Type | Method and Description |
---|---|
SymbolTable |
getTable(String name)
Gets a symbol table with a specific name and the highest version
possible.
|
SymbolTable |
getTable(String name,
int version)
Gets a desired symbol table from this catalog, using an exact match if
possible.
|
SymbolTable getTable(String name)
name
- identifies the desired symbol table.null
if this catalog has no table with the name.SymbolTable getTable(String name, int version)
Implentations must make a best effort to find an exact match. If an exact match cannot be found, then this method must make a best effort to find the best match available.
null
.