TopcatModel (TOPCAT API)

java.lang.Object
- uk.ac.starlink.topcat.TopcatModel

```
public class TopcatModel
extends Object
```
Defines all the state for the representation of a given table as viewed by TOPCAT. As well as the table itself this contains information about current row ordering, defined subsets, etc. It also constructs and keeps track of windows and actions associated with the table.
This is a big ugly mixed bag of various different models. It has crossed my mind to attempt to amalgamate them into something a bit more rational, but the structure of one model containing a set of other (swing-defined) models seems to work OK.

Since:

18 Feb 2004

Author:

Mark Taylor (Starlink)

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`TopcatModel(uk.ac.starlink.table.StarTable startab, int id, String location, ControlWindow controlWindow)` Constructs a new model from a given table.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addParameter(uk.ac.starlink.table.DescribedValue param)` Adds a new table parameter to the table.
`void`	`addSubset(RowSubset rset)` Adds a new row subset to the list which this model knows about.
`void`	`addTopcatListener(TopcatListener listener)` Adds a listener to be notified of changes in this model.
`void`	`appendColumn(uk.ac.starlink.table.ColumnData col)` Appends a new column to the existing table as the last column.
`void`	`appendColumn(uk.ac.starlink.table.ColumnData col, int colIndex)` Appends a new column to the existing table at a given column index.
`void`	`appendColumns(uk.ac.starlink.table.StarTable colTable)` Appends all the columns in a given table as new columns in this one.
`void`	`applySubset(RowSubset rset)` Sets a given row subset to the Current one.
`static TopcatModel`	`createDefaultTopcatModel(uk.ac.starlink.table.StarTable table, String location, ControlWindow controlWindow)` Returns a new TopcatModel suitable for a table that has just been loaded in the usual way.
`static TopcatModel`	`createDummyModel()` Creates and returns a new TopcatModel with no data.
`TopcatJELRowReader`	`createJELRowReader()` Returns a JEL expression evaluation context appropriate for the current state of this table.
`JComboBox<String>`	`createNewSubsetNameSelector()` Returns a new editable JComboBox which can be used to select the name of a new RowSubset.
`static TopcatModel`	`createRawTopcatModel(uk.ac.starlink.table.StarTable table, String location, ControlWindow controlWindow)` Returns a new TopcatModel based on a table but without some of the additional decorations.
`static TopcatModel`	`createUnloadedTopcatModel(uk.ac.starlink.table.StarTable table, String name)` Returns a new TopcatModel that is supposed to be used independently rather than loaded into the main topcat application list.
`SubsetConsumer`	`enquireNewSubsetConsumer(Component parent)` Pops up a dialogue to ask the user what to do with a newly created RowSubset.
`void`	`explodeColumn(uk.ac.starlink.table.gui.StarTableColumn tcol)` Replaces an N-element array-valued column in the table with N scalar-valued columns.
`void`	`fireModelChanged(int code, Object datum)` Notifies all registered listeners that this model has changed.
`SingleRowSubset`	`getActivatedSubset()` Returns a subset representing the currently activated row.
`ActivationWindow`	`getActivationWindow()` Returns the window that manages this model's activation actions.
`uk.ac.starlink.table.StarTable`	`getApparentStarTable()` Returns a StarTable representing the table data as displayed by a JTable looking at this model.
`ColumnList`	`getColumnList()` Returns the list of columns available from this table.
`TableColumnModel`	`getColumnModel()` Returns the table column model which should be used by this a `JTable` for table display.
`ColumnSelectorModel`	`getColumnSelectorModel(uk.ac.starlink.table.ValueInfo info)` Returns a ColumnSelectorModel which represents the current choice for a given ValueInfo for this table.
`PlasticStarTable`	`getDataModel()` Returns the container for the data held by this viewer.
`int`	`getID()` Returns the model's ID number.
`String`	`getLabel()` Returns this model's label.
`String`	`getLocation()` Returns the location of the table described by this model.
`Action`	`getNewSubsetAction()` Gets an action which will pop up a window for defining a new algebraic subset for this model.
`SortOrder`	`getSelectedSort()` Returns the most recently selected sort order.
`RowSubset`	`getSelectedSubset()` Returns the most recently selected row subset.
`Action`	`getSortAction(SortOrder order, boolean ascending)` Returns an action which sorts the table on the contents of a given column.
`SortOrderSelector.Model`	`getSortSelectionModel()` Returns the selection model which controls sorts on the table rows.
`JToggleButton.ToggleButtonModel`	`getSortSenseModel()` Returns the model indicating whether sorts are up or down.
`RowSubset`	`getSubsetByKey(RowSubset.Key key)` Returns the subset in this model's subset list identified by key.
`Map<RowSubset,Long>`	`getSubsetCounts()` Returns the Map which contains the number of rows believed to be in each subset.
`OptionsListModel<RowSubset>`	`getSubsets()` Returns the `ListModel` which keeps track of which `RowSubset` objects are available.
`ComboBoxModel<RowSubset>`	`getSubsetSelectionModel()` Returns the selection model which controls the active subset for the viewed table.
`uk.ac.starlink.table.TableBuilder`	`getTableFormat()` Returns the table builder object that originally loaded this model's table.
`Action`	`getUnsortAction()` Gets an action which will return the view model for this model to its unsorted state.
`ViewerTableModel`	`getViewModel()` Returns the table model which should be used by a `JTable` for table display.
`boolean`	`hasActivationWindow()` Indicates whether this model currently has an activation window.
`void`	`highlightRow(long lrow)` Performs all actions required to highlight a row, including notifying external applications via SAMP/PLASTIC if this model is currently so configured.
`void`	`highlightRow(long lrow, boolean sendOut)` Performs actions required to highlight a row, optionally including notifying external applications via SAMP/PLASTIC.
`void`	`recompileSubsets()` Recompiles all synthetic subsets from their expressions.
`boolean`	`removeParameter(uk.ac.starlink.table.DescribedValue param)` Removes a table parameter from the table.
`void`	`removeTopcatListener(TopcatListener listener)` Removes a listener from notification of changes in this model.
`void`	`renameColumn(TableColumn tcol, String name)` Changes the name of a TableColumn in this model.
`void`	`setLabel(String label)` Sets the label for model identification.
`void`	`showSubset(RowSubset rset)` Causes a given row subset to be be highlighted in some way.
`void`	`sortBy(SortOrder order, boolean ascending)` Trigger a sort of the rows in the viewModel.
`String`	`toString()`
`void`	`updateSubsetCount(RowSubset rset, long nrow)` Stores the known row count value for a given subset.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - TopcatModel
```
protected TopcatModel(uk.ac.starlink.table.StarTable startab,
                      int id,
                      String location,
                      ControlWindow controlWindow)
```
    Constructs a new model from a given table. The only row subset available is ALL.
    
    Parameters:
    
    startab - random-access table providing the data
    
    id - id number; should be unique for loaded tables
    
    location - location string
    
    controlWindow - control window instance
- Method Detail
  - getLocation
```
public String getLocation()
```
    Returns the location of the table described by this model. This is some indication of its provenance, and will not normally change over its lifetime.
    
    Returns:
    
    location
  - getLabel
```
public String getLabel()
```
    Returns this model's label. This is a (short?) string which can be changed by the user, used for human identification of the model.
    
    Returns:
    
    label
  - getID
```
public int getID()
```
    Returns the model's ID number. This is a small sequence number, typically starting at one and increasing for every model created in this topcat instance. It's used for identifying the model to the user.
    
    Returns:
    
    numeric ID
  - getTableFormat
```
public uk.ac.starlink.table.TableBuilder getTableFormat()
```
    Returns the table builder object that originally loaded this model's table.
    
    Returns:
    
    table origin input handler if known, or null
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - setLabel
```
public void setLabel(String label)
```
    Sets the label for model identification.
    
    Parameters:
    
    label - new label value
  - getDataModel
```
public PlasticStarTable getDataModel()
```
    Returns the container for the data held by this viewer. This model, which is a StarTable object, is not affected by changes to the data view such as the order of the results presented in the viewer. It can have columns added to it but not removed.
    
    Returns:
    
    the data model
  - getViewModel
```
public ViewerTableModel getViewModel()
```
    Returns the table model which should be used by a JTable for table display. This is based on the dataModel, but can be reordered and configured to display only a subset of the rows and so on.
    
    Returns:
    
    the table model
  - getColumnModel
```
public TableColumnModel getColumnModel()
```
    Returns the table column model which should be used by this a JTable for table display. This can be manipulated either programmatically or as a consequence of user interaction with the JTable (dragging columns around) to modify the mapping of columns visible in this viewer to columns in the dataModel.
    
    Returns:
    
    the column model
  - getColumnList
```
public ColumnList getColumnList()
```
    Returns the list of columns available from this table. Unlike a TableColumnModel, this keeps track of all the columns which have ever been in the column model, and is able to say whether they are currently hidden or not.
    
    Returns:
    
    the column list
  - getSubsets
```
public OptionsListModel<RowSubset> getSubsets()
```
    Returns the ListModel which keeps track of which RowSubset objects are available.
    
    Returns:
    
    the RowSubset list model
  - getSubsetCounts
```
public Map<RowSubset,Long> getSubsetCounts()
```
    Returns the Map which contains the number of rows believed to be in each subset. The keys of this map are the subsets themselves, and the values are Long objects giving the row counts. If the subset has not been counted, it will not appear in the map. The count in the map may not be accurate, if the table data or subset definitions have changed since the count was last done.
    
    Returns:
    
    subset count map
  - getSortSelectionModel
```
public SortOrderSelector.Model getSortSelectionModel()
```
    Returns the selection model which controls sorts on the table rows. This can be used as the basis for a JComboBox which allows the user to specify a sort. This model is the primary guardian of the most recent sort, it does not reflect the state of some other holder of that information.
    
    Returns:
    
    sort selection model
  - getSortSenseModel
```
public JToggleButton.ToggleButtonModel getSortSenseModel()
```
    Returns the model indicating whether sorts are up or down. This can be used as the basis for a tickbox or something.
    
    Returns:
    
    sort direction model
  - getSubsetSelectionModel
```
public ComboBoxModel<RowSubset> getSubsetSelectionModel()
```
    Returns the selection model which controls the active subset for the viewed table. This can be used as the basis of a JComboBox which allows the user to specify a subset to be applied. This model is the primary guardian of the active subset, it does not reflect the state of some other holder of that information.
    
    Returns:
    
    active row selection model
  - getSelectedSubset
```
public RowSubset getSelectedSubset()
```
    Returns the most recently selected row subset. This is the one which defines the apparent table.
    
    Returns:
    
    current row subset
  - getSubsetByKey
```
public RowSubset getSubsetByKey(RowSubset.Key key)
```
    Returns the subset in this model's subset list identified by key.
    
    Parameters:
    
    key - subset identifier
    
    Returns:
    
    subset with given key, or null
  - getSelectedSort
```
public SortOrder getSelectedSort()
```
    Returns the most recently selected sort order. This is the one which defines the apparent table.
    
    Returns:
    
    current sort order
  - getColumnSelectorModel
```
public ColumnSelectorModel getColumnSelectorModel(uk.ac.starlink.table.ValueInfo info)
```
    Returns a ColumnSelectorModel which represents the current choice for a given ValueInfo for this table. A map is maintained, so the same info will always result in getting the same selector model. If it hasn't been seen before though, a new one will be created.
    
    Parameters:
    
    info - description of the column which is wanted
    
    Returns:
    
    model which can be used for selection of a column in this table with the characteristics of info
  - getActivatedSubset
```
public SingleRowSubset getActivatedSubset()
```
    Returns a subset representing the currently activated row.
    
    Returns:
    
    subset
  - getActivationWindow
```
public ActivationWindow getActivationWindow()
```
    Returns the window that manages this model's activation actions.
    
    Returns:
    
    activation window, created lazily
  - hasActivationWindow
```
public boolean hasActivationWindow()
```
    Indicates whether this model currently has an activation window. If this method returns false, then calling getActivationWindow() will result in one being created.
    
    Returns:
    
    true iff an activation window has already been created for this model
  - addTopcatListener
```
public void addTopcatListener(TopcatListener listener)
```
    Adds a listener to be notified of changes in this model.
    
    Parameters:
    
    listener - listener to add
  - removeTopcatListener
```
public void removeTopcatListener(TopcatListener listener)
```
    Removes a listener from notification of changes in this model.
    
    Parameters:
    
    listener - listener to remove
  - fireModelChanged
```
public void fireModelChanged(int code,
                             Object datum)
```
    Notifies all registered listeners that this model has changed.
    
    Parameters:
    
    code - item code indicating the type of change that has occurred (one of the static final constants in TopcatEvent)
    
    datum - additional information about the event
  - highlightRow
```
public void highlightRow(long lrow)
```
    Performs all actions required to highlight a row, including notifying external applications via SAMP/PLASTIC if this model is currently so configured.
    
    Parameters:
    
    lrow - row index
  - highlightRow
```
public void highlightRow(long lrow,
                         boolean sendOut)
```
    Performs actions required to highlight a row, optionally including notifying external applications via SAMP/PLASTIC.
    
    Parameters:
    
    lrow - index of the row to activate, or -1 to clear activation
    
    sendOut - if true, will notify external applications via SAMP/PLASTIC when this model is so configured; if false, no such external notifications will be sent
  - getNewSubsetAction
```
public Action getNewSubsetAction()
```
    Gets an action which will pop up a window for defining a new algebraic subset for this model.
    
    Returns:
    
    subset definition action
  - getUnsortAction
```
public Action getUnsortAction()
```
    Gets an action which will return the view model for this model to its unsorted state.
    
    Returns:
    
    unsort action
  - getSortAction
```
public Action getSortAction(SortOrder order,
                            boolean ascending)
```
    Returns an action which sorts the table on the contents of a given column. The sort is effected by creating a mapping between model rows and (sorted) view rows, and installing this into this viewer's data model.
    
    Parameters:
    
    order - sort order
    
    ascending - sense of sort (true for up, false for down)
  - appendColumn
```
public void appendColumn(uk.ac.starlink.table.ColumnData col,
                         int colIndex)
```
    Appends a new column to the existing table at a given column index. This method appends a column to the dataModel, fixes the TableColumnModel to put it in at the right place, and ensures that everybody is notified about what has gone on.
    
    Parameters:
    
    col - the new column
    
    colIndex - the column index at which the new column is to be appended, or -1 for at the end
  - appendColumn
```
public void appendColumn(uk.ac.starlink.table.ColumnData col)
```
    Appends a new column to the existing table as the last column.
    
    Parameters:
    
    col - the new column
  - appendColumns
```
public void appendColumns(uk.ac.starlink.table.StarTable colTable)
```
    Appends all the columns in a given table as new columns in this one.
    
    Parameters:
    
    colTable - table containing columns to be grafted onto this table
  - renameColumn
```
public void renameColumn(TableColumn tcol,
                         String name)
```
    Changes the name of a TableColumn in this model. Renaming should be done using this call rather than directly to ensure that all the data is updated properly.
    
    Parameters:
    
    tcol - column in this topcat model whose name is to be updated
    
    name - new name
  - explodeColumn
```
public void explodeColumn(uk.ac.starlink.table.gui.StarTableColumn tcol)
```
    Replaces an N-element array-valued column in the table with N scalar-valued columns. More precisely, it adds N new columns after the original and then hides the original.
    
    Parameters:
    
    tcol - vector-valued column
  - enquireNewSubsetConsumer
```
public SubsetConsumer enquireNewSubsetConsumer(Component parent)
```
    Pops up a dialogue to ask the user what to do with a newly created RowSubset. The user may supply a new or old name which adds it to this model, or may elect to send it to another application via SAMP/PLASTIC.
    
    Parameters:
    
    parent - parent component
    
    Returns:
    
    subset consumer, or null if the user doesn't want to play
  - createNewSubsetNameSelector
```
public JComboBox<String> createNewSubsetNameSelector()
```
    Returns a new editable JComboBox which can be used to select the name of a new RowSubset. The selectable items in the combo box are the existing RowSubsets for this model, with the exception of RowSubset.ALL, which ought not to be redefined. The user may either select one of these existing subsets, or may type in a new name. Thus the selectedItem for the returned combo box may be either a String, or an existing RowSubset (which is generally to be used by using its name as the name of a new RowSubset to be added to this model).
    
    Returns:
    
    a selector to determine the name of a new RowSubset
  - createJELRowReader
```
public TopcatJELRowReader createJELRowReader()
```
    Returns a JEL expression evaluation context appropriate for the current state of this table. It may not be updated by future updates to this model, so it should only be used for preparation of evaluation of expressions at call time, not saved for use in compiling expressions acquired later.
    Note this currently returns a one-size-fits-all implementation, safe for multi-thread use. But it may not be efficient for multi-thread use (synchronization, contention). This should be fixed so that efficient single-threaded access is possible.
    
    Returns:
    
    row reader
  - addSubset
```
public void addSubset(RowSubset rset)
```
    Adds a new row subset to the list which this model knows about. If the supplied subset has a name which is the same as an existing one in the list, the new one replaces the old one. Otherwise, it is appended to the end.
    
    Parameters:
    
    rset - the new row subset
  - recompileSubsets
```
public void recompileSubsets()
```
    Recompiles all synthetic subsets from their expressions. Where this can't be done, a warning is issued.
  - updateSubsetCount
```
public void updateSubsetCount(RowSubset rset,
                              long nrow)
```
    Stores the known row count value for a given subset.
    
    Parameters:
    
    rset - subset
    
    nrow - row count known for the subset
  - addParameter
```
public void addParameter(uk.ac.starlink.table.DescribedValue param)
```
    Adds a new table parameter to the table.
    
    Parameters:
    
    param - new parameter to add to the table
  - removeParameter
```
public boolean removeParameter(uk.ac.starlink.table.DescribedValue param)
```
    Removes a table parameter from the table.
    
    Parameters:
    
    param - parameter object to remove
    
    Returns:
    
    true if param was removed, false if it wasn't one of the table parameters in the first place
  - sortBy
```
public void sortBy(SortOrder order,
                   boolean ascending)
```
    Trigger a sort of the rows in the viewModel. In case of a material change this causes a TopcatEvent.CURRENT_ORDER event to be sent to listeners.
    
    Parameters:
    
    order - sort order
    
    ascending - sort sense (true for up, false for down)
  - applySubset
```
public void applySubset(RowSubset rset)
```
    Sets a given row subset to the Current one. Amongst other things this causes a TopcatEvent.CURRENT_SUBSET event to be sent to listeners and changes the selection of rows visible in the viewModel.
    
    Parameters:
    
    rset - the row subset to use (must be one from the known list)
  - showSubset
```
public void showSubset(RowSubset rset)
```
    Causes a given row subset to be be highlighted in some way. This does not set the current subset, but does cause a TopcatEvent.SHOW_SUBSET event to be sent to listeners.
    
    Parameters:
    
    rset - the row subset to use (must be one from the known list)
  - getApparentStarTable
```
public uk.ac.starlink.table.StarTable getApparentStarTable()
```
    Returns a StarTable representing the table data as displayed by a JTable looking at this model. This may differ from the original StarTable object held by it in a number of ways; it may have a different row order, different column orderings, and added or removed columns.
    
    Returns:
    
    a StarTable object representing what this viewer appears to be showing
  - createDefaultTopcatModel
```
public static TopcatModel createDefaultTopcatModel(uk.ac.starlink.table.StarTable table,
                                                   String location,
                                                   ControlWindow controlWindow)
```
    Returns a new TopcatModel suitable for a table that has just been loaded in the usual way. RowSubsets are generated for each boolean column.
    
    Parameters:
    
    table - random-access table providing the data
    
    location - location string
    
    controlWindow - control window instance
  - createRawTopcatModel
```
public static TopcatModel createRawTopcatModel(uk.ac.starlink.table.StarTable table,
                                               String location,
                                               ControlWindow controlWindow)
```
    Returns a new TopcatModel based on a table but without some of the additional decorations. In particular no column-based subsets are added.
    
    Parameters:
    
    table - random-access table providing the data
    
    location - location string
    
    controlWindow - control window instance
  - createUnloadedTopcatModel
```
public static TopcatModel createUnloadedTopcatModel(uk.ac.starlink.table.StarTable table,
                                                    String name)
```
    Returns a new TopcatModel that is supposed to be used independently rather than loaded into the main topcat application list.
    
    Parameters:
    
    table - random-access table providing the data
    
    name - name by which the table will be known
  - createDummyModel
```
public static TopcatModel createDummyModel()
```
    Creates and returns a new TopcatModel with no data. This does not increment the count of existing models - it's intended for things like initialising data models which must stop referring to a live TopcatModel.
    
    Returns:
    
    new empty TopcatModel

Class TopcatModel

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TopcatModel

Method Detail

getLocation

getLabel

getID

getTableFormat

toString

setLabel

getDataModel

getViewModel

getColumnModel

getColumnList

getSubsets

getSubsetCounts

getSortSelectionModel

getSortSenseModel

getSubsetSelectionModel

getSelectedSubset

getSubsetByKey

getSelectedSort

getColumnSelectorModel

getActivatedSubset

getActivationWindow

hasActivationWindow

addTopcatListener

removeTopcatListener

fireModelChanged

highlightRow

highlightRow

getNewSubsetAction

getUnsortAction

getSortAction

appendColumn

appendColumn

appendColumns

renameColumn

explodeColumn

enquireNewSubsetConsumer

createNewSubsetNameSelector

createJELRowReader

addSubset

recompileSubsets

updateSubsetCount

addParameter

removeParameter

sortBy

applySubset

showSubset

getApparentStarTable

createDefaultTopcatModel

createRawTopcatModel

createUnloadedTopcatModel

createDummyModel