Package uk.ac.starlink.topcat.interop

## Class TopcatSampControl

- java.lang.Object
- - uk.ac.starlink.topcat.interop.TopcatSampControl

-     public class TopcatSampControl
      extends java.lang.Object

  Provides TOPCAT's SAMP functionality.
  Since:
    29 Aug 2008
  Author:
    Mark Taylor

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TopcatSampControl​(org.astrogrid.samp.client.HubConnector hubConnector, ControlWindow controlWindow)` | Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `org.astrogrid.samp.Message` | `createRowMessage​(TopcatModel tcModel, long lrow)` | Creates a message suitable for sending a row highlight SAMP message to other clients.
    `java.util.Map<?,​?>` | `createSubsetMessage​(TopcatModel tcModel, RowSubset rset)` | Creates a message suitable for sending a row list selection SAMP message to other clients.
    `ControlWindow` | `getControlWindow()` | Returns the control window which owns this connector.
    `javax.swing.ListModel<TopcatModel>` | `getIdentifiableTableListModel()` | Returns a ListModel listing the TopcatModels that can reasonably be used in SAMP messages that reference a table using the `table-id`/`url` message parameter (`table.highlight.row`, `table.select.rowList`).
    `java.lang.String` | `getTableIdForSending​(TopcatModel tcModel)` | Returns a public reference ID indicating the current state of a given TOPCAT table which will be used to send it in a SAMP message.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### TopcatSampControl

          public TopcatSampControl​(org.astrogrid.samp.client.HubConnector hubConnector,
                                   ControlWindow controlWindow)
                            throws java.io.IOException

      Constructor.
      Parameters:
        `controlWindow` - TOPCAT top-level window
      Throws:
        `java.io.IOException`

  - ### Method Detail

    - #### getControlWindow

          public ControlWindow getControlWindow()

      Returns the control window which owns this connector.
      Returns:
        control window

    - #### getTableIdForSending

          public java.lang.String getTableIdForSending​(TopcatModel tcModel)

      Returns a public reference ID indicating the current state of a given TOPCAT table which will be used to send it in a SAMP message. For now, "state" refers to the combination of the table and its row sequence, though other items may become important if SAMP messages arise which require consistency of other attributes. Note: this method may update the list of tables known to have been sent via SAMP, which can be used to determine what tables are potentially referencable by other SAMP messages. For this reason, this method should not be invoked speculatively, but only if the intention is to actually send a message using the returned identifier.
      Parameters:
        `tcModel` - table to identify
      Returns:
        opaque ID string

    - #### createSubsetMessage

          public java.util.Map<?,​?> createSubsetMessage​(TopcatModel tcModel,
                                                              RowSubset rset)

      Creates a message suitable for sending a row list selection SAMP message to other clients. It is sensibly done here because this class keeps track of which tables have been labelled with which IDs in communications with other SAMP clients.
      Parameters:
        `tcModel` - table
        `rset` - row subset of tcModel to send
      Returns:
        table.select.rowList message

    - #### getIdentifiableTableListModel

          public javax.swing.ListModel<TopcatModel> getIdentifiableTableListModel()

      Returns a ListModel listing the TopcatModels that can reasonably be used in SAMP messages that reference a table using the `table-id`/`url` message parameter (`table.highlight.row`, `table.select.rowList`). TopcatModels may be added to this list when they have been involved in a relevant SAMP message (usually `table.load.*`). Code can register a listener on this list to be notified when the identifiability status of tables change.
      Returns:
        listmodel of identifiable tables

    - #### createRowMessage

          public org.astrogrid.samp.Message createRowMessage​(TopcatModel tcModel,
                                                             long lrow)

      Creates a message suitable for sending a row highlight SAMP message to other clients.
      Parameters:
        `tcModel` - table
        `lrow` - index of row in tcModel to highlight
      Returns:
        table.highlight.row message, or null if no suitable message can be constructed