Package uk.ac.starlink.topcat

# Interface TopcatCodec

All Known Implementing Classes:
  `TopcatCodec1`, `TopcatCodec2`

public interface TopcatCodec
Defines encoding and decoding for TopcatModels in order to perform per-table session save/restore. Information beyond the StarTable data and metadata itself should include things like defined row subsets, hidden columns, apparent table sort order etc. This class translates between a TopcatModel and a StarTable; the StarTable can be de/serialized using one of the standard STIL I/O handlers (probably a VOTable-based one since there will be significant amounts of metadata).

Note this means that the "serialization" done here is not free-form, all the required metadata and data has to be encoded in a form that can be captured by the StarTable data model (basically, columns and parameters with associated metadata). Additionally, to be useful, it needs to store this information in a way that can be later serialized by at least one of the available STIL I/O handlers. Formats based on the VOTable format are generally capable enough for this, though note that ColumnInfo "auxiliary" metadata items will probably be lost during VOTable serialization, so probably can't be used when implementing this interface.

Since:
  16 Jul 2010
Author:
  Mark Taylor

## Method Summary

Modifier and Type
Method
Description
`TopcatModel`
`decode(uk.ac.starlink.table.StarTable table, String location, ControlWindow controlWindow)`
Takes a table which has been previously serialized by calling this codec's `encode` method, and for which the `isEncoded` method returns true, and turns it into a TopcatModel.
`uk.ac.starlink.table.StarTable`
`encode(TopcatModel tcModel)`
Turns a TopcatModel into a StarTable, ready for serialization.
`boolean`
`isEncoded(uk.ac.starlink.table.StarTable table)`
Indicates whether a given table is a candidate for this codec's `decode` method.

## Method Details

### encode

uk.ac.starlink.table.StarTable encode(TopcatModel tcModel)
Turns a TopcatModel into a StarTable, ready for serialization.

Parameters:
  `tcModel` - model
Returns:
  table

### isEncoded

boolean isEncoded(uk.ac.starlink.table.StarTable table)
Indicates whether a given table is a candidate for this codec's `decode` method. It should in general return true for a table that has been returned from this object's `encode` method (possibly following a table write/read cycle) and false for other tables.

Parameters:
  `table` - data+metadata table
Returns:
  true iff it looks like the table was written by this codec and can be decoded by it

### decode

TopcatModel decode(uk.ac.starlink.table.StarTable table, String location, ControlWindow controlWindow)
Takes a table which has been previously serialized by calling this codec's `encode` method, and for which the `isEncoded` method returns true, and turns it into a TopcatModel. If decoding fails, null is returned.

If used with a ControlWindow that users may be interacting with, this method should be called from the AWT event dispatch thread. This method may (for instance during testing) be called with a null value for the `controlWindow` parameter, but the resulting TopcatModel may not be suitable for all kinds of user interactions.

Parameters:
  `table` - encoded table
  `location` - table location string
  `controlWindow` - control window, or null if necessary
Returns:
  topcat model, or null