Package com.amazon.ion

Interface SymbolTable

  • public interface SymbolTable
    A symbol table maps symbols between their textual form and an integer ID used in the binary encoding.

    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.

    Notes about Substitute symbol tables

    Substitute tables are used when the relevant catalog cannot find an exact match, that is, the catalog cannot find an imported shared symtab with the same name, version and max_id.

    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.

    See Also:
    Ion Symbols page

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int UNKNOWN_SYMBOL_ID
      Indicates that a symbol's integer ID could not be determined.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      SymbolToken find​(java.lang.String text)
      Finds a symbol already interned by this table.
      java.lang.String findKnownSymbol​(int id)
      Gets the interned text for a symbol ID.
      int findSymbol​(java.lang.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.
      java.lang.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.
      java.lang.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​(java.lang.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.
      java.util.Iterator<java.lang.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.

    • Field Detail

      • UNKNOWN_SYMBOL_ID

        static final int UNKNOWN_SYMBOL_ID
        Indicates that a symbol's integer ID could not be determined. That's generally the case when constructing value instances that are not yet contained by a datagram.
        See Also:
        Constant Field Values

    • Method Detail

      • getName

        java.lang.String getName()
        Gets the unique name of this symbol table.
        Returns:
        the unique name, or null if isLocalTable().

      • getVersion

        int getVersion()
        Gets the version of this symbol table.
        Returns:
        at least one, or zero if isLocalTable().

      • isLocalTable

        boolean 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.

      • isSharedTable

        boolean 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.

      • isSubstitute

        boolean 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.

      • isSystemTable

        boolean 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.

      • isReadOnly

        boolean 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:
        true if this table is read-only, false if symbols may be added.
        See Also:
        makeReadOnly()

      • makeReadOnly

        void 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.
        See Also:
        isReadOnly()

      • getSystemSymbolTable

        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:
        not null, except for non-system shared tables.

      • getIonVersionId

        java.lang.String 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:
        the version identifier; or null for non-system shared tables.

      • getImportedTables

        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:
        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).

      • getImportedMaxId

        int 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.

      • getMaxId

        int getMaxId()
        Gets the highest symbol id reserved by this table.
        Returns:
        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.

      • intern

        SymbolToken intern​(java.lang.String text)
        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 - the symbol text to intern.
        Returns:
        the interned symbol, with both text and SID defined; not null.
        Throws:
        IonException - if this symtab isReadOnly() and the text isn't already interned.
        See Also:
        find(String)

      • find

        SymbolToken find​(java.lang.String text)
        Finds a symbol already interned by this table.

        This method will not necessarily return the same instance given the same input.

        Parameters:
        text - the symbol text to find.
        Returns:
        the interned symbol, with both text and SID defined; or null if it's not already interned.
        See Also:
        intern(String)

      • findSymbol

        int findSymbol​(java.lang.String name)
        Gets the symbol ID associated with a given symbol name.
        Parameters:
        name - must not be null or empty.
        Returns:
        the id of the requested symbol, or UNKNOWN_SYMBOL_ID if it's not defined.
        Throws:
        java.lang.NullPointerException - if name is null.

      • findKnownSymbol

        java.lang.String findKnownSymbol​(int id)
        Gets the interned text for a symbol ID.
        Parameters:
        id - the requested symbol ID.
        Returns:
        the interned text associated with the symbol ID, or null if the text is not known.
        Throws:
        java.lang.IllegalArgumentException - if id < 1.

      • iterateDeclaredSymbolNames

        java.util.Iterator<java.lang.String> 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:
        a new iterator.

      • writeTo

        void writeTo​(IonWriter writer)
      throws java.io.IOException
        Writes an Ion representation of this symbol table.
        Parameters:
        writer - must not be null.
        Throws:
        java.io.IOException - if thrown by the writer.