Collects shared symbol tables for use by an
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.
Notes for Implementors
This interface defines two methods with subtly different semantics.
The first variant takes only a symbol table name, and returns the highest
version possible. The second takes a version number and attempts to match it
exactly, and if that's not possible it falls back to the the "best match"
possible:
- If any versions larger than the requested version are
available, select the smallest among them (still larger than requested).
- Otherwise all available versions are smaller than the
requested version, so return the largest of them.
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.