Package com.amazon.ion

Interface IonCatalog

All Known Subinterfaces:
IonMutableCatalog
All Known Implementing Classes:
SimpleCatalog
public interface IonCatalog
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.

  • Method Summary

    Modifier and Type
    Method
    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.

  • Method Details

    • getTable

      SymbolTable getTable(String name)
      Gets a symbol table with a specific name and the highest version possible.
      Parameters:
      name - identifies the desired symbol table.
      Returns:
      a shared symbol table with the given name, or null if this catalog has no table with the name.

    • getTable

      SymbolTable getTable(String name, int version)
      Gets a desired symbol table from this catalog, using an exact match if possible.

      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.

      Returns:
      the shared symbol table with the given name and version, when an exact match is possible. Otherwise, returns the lowest possible version larger than requested. Otherwise, return the largest possible version lower than requested. If no table with the name can be found, then this method returns null.