Class TableDefinitionProtos
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 Summary
Modifier and TypeMethodDescriptionstatic TableDefinitiondeserialize(byte @NotNull [] bytes) Deserializes a table definition frombytes, as produced byserialize(TableDefinition)or stored in a file bywrite(Path, TableDefinition, CopyOption...).static TableDefinitionReads a table definition frompath, as written bywrite(Path, TableDefinition, CopyOption...).static byte[]serialize(@NotNull TableDefinition definition) Serializesdefinitionto bytes, in the same formatwrite(Path, TableDefinition, CopyOption...)writes to files.static voidwrite(@NotNull Path path, @NotNull TableDefinition definition, @NotNull CopyOption... options) Writesdefinitionto a new file atpath.
-
Method Details
-
write
public static void write(@NotNull @NotNull Path path, @NotNull @NotNull TableDefinition definition, @NotNull @NotNull CopyOption... options) throws IOException Writesdefinitionto a new file atpath. By default this fails ifpathalready exists; passStandardCopyOption.REPLACE_EXISTINGto 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 fromserializethemselves.The file is written to a temporary sibling first and then published at
pathin 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 atpathis replaced, not followed.Like
Files.copy(java.io.InputStream, Path, CopyOption...), the supported options are:StandardCopyOption.REPLACE_EXISTING: replacepathif it exists. The replacement is atomic. This is not portable: replacing is implemented as an atomic move onto an existing file, andStandardCopyOption.ATOMIC_MOVEleaves 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 anIOExceptionon others, in which case useserializeand handle the IO directly.StandardCopyOption.ATOMIC_MOVE: accepted, but has no effect, as publishing is always atomic.
- Parameters:
path- the file to writedefinition- the table definitionoptions- how to publish the file- Throws:
FileAlreadyExistsException- ifpathexists andStandardCopyOption.REPLACE_EXISTINGis not specifiedUnsupportedOperationException- ifoptionscontains an unsupported option, or, when not replacing, if the file system does not support hard links, which are used to publish without replacingIOException- if the file cannot be written, or the file system cannot atomically publishpath, including when replacing is not supported by the file system provider
-
read
Reads a table definition frompath, as written bywrite(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 (anInvalidProtocolBufferException)IllegalArgumentException- if the file does not describe a valid table definition, has unknown fields, or names a class that cannot be found
-
serialize
Serializesdefinitionto bytes, in the same formatwrite(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 withdeserialize(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 frombytes, as produced byserialize(TableDefinition)or stored in a file bywrite(Path, TableDefinition, CopyOption...). Likeread(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- ifbytesis not a valid encodingIllegalArgumentException- ifbytesdoes not describe a valid table definition, has unknown fields, or names a class that cannot be found
-