Class TableDefinitionProtos

java.lang.Object
io.deephaven.engine.table.proto.TableDefinitionProtos

public final class TableDefinitionProtos extends Object
Persists table definitions to files, and reads them back, so that a definition written by one process (for example, the producer of a table) can be shared with others (for example, its consumers). For storage or transport other than files, serialize(TableDefinition) and deserialize(byte[]) work with the same format as bytes.

The format is the binary protobuf encoding of an internal (non-RPC) message, PersistedTableDefinitionProto. Reading is exact: read(path).equals(definition) after write(path, definition, ...), and deserialize(serialize(definition)).equals(definition), provided every class the definition references can be loaded by the reader. Non-primitive classes are recorded by name, so the reader needs them on its classpath. Reading is also strict: a file containing fields this version does not know about is rejected rather than partially understood.

  • Method Details

    • write

      public static void write(@NotNull @NotNull Path path, @NotNull @NotNull TableDefinition definition, @NotNull @NotNull CopyOption... options) throws IOException
      Writes definition to a new file at path. By default this fails if path already exists; pass StandardCopyOption.REPLACE_EXISTING to replace it.

      This is a convenience helper that does the file IO around serialize(TableDefinition). Callers that need to be more explicit about how they handle IO (for example, to use a specific temporary file name, a different publishing strategy, or a file system with other guarantees) can write the bytes from serialize themselves.

      The file is written to a temporary sibling first and then published at path in a single atomic step, so concurrent readers see either no file (or the previous one, when replacing) or the complete new definition, never a partial write. Publishing always creates a new file: when replacing, the previous file is not modified in place, so its ownership, permissions, and other links are not carried over, and readers that already have it open keep seeing the previous definition. A symbolic link at path is replaced, not followed.

      Like Files.copy(java.io.InputStream, Path, CopyOption...), the supported options are:

      • StandardCopyOption.REPLACE_EXISTING: replace path if it exists. The replacement is atomic. This is not portable: replacing is implemented as an atomic move onto an existing file, and StandardCopyOption.ATOMIC_MOVE leaves it up to the file system provider whether an existing target is replaced or the move fails. It works with the default providers on common local file systems, but may fail with an IOException on others, in which case use serialize and handle the IO directly.
      • StandardCopyOption.ATOMIC_MOVE: accepted, but has no effect, as publishing is always atomic.
      Parameters:
      path - the file to write
      definition - the table definition
      options - how to publish the file
      Throws:
      FileAlreadyExistsException - if path exists and StandardCopyOption.REPLACE_EXISTING is not specified
      UnsupportedOperationException - if options contains an unsupported option, or, when not replacing, if the file system does not support hard links, which are used to publish without replacing
      IOException - if the file cannot be written, or the file system cannot atomically publish path, including when replacing is not supported by the file system provider
    • read

      public static TableDefinition read(@NotNull @NotNull Path path) throws IOException
      Reads a table definition from path, as written by write(Path, TableDefinition, CopyOption...). Class names are resolved against the current thread's context class loader, or, if there is none, the class loader that loaded this class.
      Parameters:
      path - the file to read
      Returns:
      the table definition
      Throws:
      IOException - if the file cannot be read, or is not a valid encoding (an InvalidProtocolBufferException)
      IllegalArgumentException - if the file does not describe a valid table definition, has unknown fields, or names a class that cannot be found
    • serialize

      public static byte[] serialize(@NotNull @NotNull TableDefinition definition)
      Serializes definition to bytes, in the same format write(Path, TableDefinition, CopyOption...) writes to files. Use this to store or transmit a definition somewhere other than a file; the bytes can be read back with deserialize(byte[]).
      Parameters:
      definition - the table definition
      Returns:
      the serialized bytes
    • deserialize

      public static TableDefinition deserialize(byte @NotNull [] bytes) throws com.google.protobuf.InvalidProtocolBufferException
      Deserializes a table definition from bytes, as produced by serialize(TableDefinition) or stored in a file by write(Path, TableDefinition, CopyOption...). Like read(Path), deserialization is exact and strict. Class names are resolved against the current thread's context class loader, or, if there is none, the class loader that loaded this class.
      Parameters:
      bytes - the serialized bytes
      Returns:
      the table definition
      Throws:
      com.google.protobuf.InvalidProtocolBufferException - if bytes is not a valid encoding
      IllegalArgumentException - if bytes does not describe a valid table definition, has unknown fields, or names a class that cannot be found