# Interface TopcatCommunicator

All Known Implementing Classes:
  `SampCommunicator`

public interface TopcatCommunicator
Abstract interface for inter-application messaging requirements of TOPCAT. This can be implemented by SAMP or PLASTIC (or others).

Since:
  4 Sep 2008
Author:
  Mark Taylor

## Method Summary

Modifier and Type
Method
Description
`void`
`addConnectionListener(ChangeListener listener)`
Adds a listener which will be notified any time that connection status may have changed.
`ImageActivity`
`createImageActivity()`
Returns an object which can be used to display images.
`Transmitter`
`createImageTransmitter(DensityWindow densityWindow)`
Returns an object that can send the density map currently displayed in the density plot window to other applications as a FITS image.
`JComponent`
`createInfoPanel()`
Optionally returns a panel which can be displayed in the control window to show communications status.
`Transmitter`
`createResourceListTransmitter(uk.ac.starlink.vo.RegistryPanel regPanel, String resourceType)`
Returns an object that can send the currently displayed resources from a registry panel.
`RowActivity`
`createRowActivity()`
Returns an object which can be used to send messages highlighting single table rows.
`SkyPointActivity`
`createSkyPointActivity()`
Returns an object which can be used to send messages drawing attention to particular sky positions.
`SpectrumActivity`
`createSpectrumActivity()`
Returns an object which can be used to display spectra.
`SubsetActivity`
`createSubsetActivity()`
Returns an object which can be used to send messages selecting table row subsets.
`Transmitter`
`createSubsetTransmitter(TopcatModel tcModel, SubsetWindow subsetWindow)`
Returns an object that can send the RowSubset currently selected in a given subset window to other applications as a row selection on a commonly-known table.
`Action`
`createWindowAction(Component parent)`
Constructs an action which will display a control window for this communicator.
`Action[]`
`getInteropActions()`
Returns a list of actions suitable for insertion in a general purpose menu associated with interoperability functionality (register/unregister etc).
`String`
`getProtocolName()`
Returns the name of the protocol over which this object is implemented.
`Transmitter`
`getTableTransmitter()`
Returns an object that can send send the currently selected table from TOPCAT to other applications.
`boolean`
`isConnected()`
Indicates (without attempting a connection) whether a hub connection is currently in force.
`void`
`maybeStartHub()`
According to the policy of this communicator, this method may start a hub if none is already running.
`boolean`
`setActive()`
Must be called before any of the actions provided by this object are used.
`void`
`startHub(boolean external)`
Attempts to start a messaging hub suitable for use with this object.

## Method Details

### getProtocolName

String getProtocolName()
Returns the name of the protocol over which this object is implemented.

Returns:
  protocol name

### setActive

boolean setActive()
Must be called before any of the actions provided by this object are used. May initiate communication with the messaging system etc.

Returns:
  true iff there is a current connection

### getInteropActions

Action[] getInteropActions()
Returns a list of actions suitable for insertion in a general purpose menu associated with interoperability functionality (register/unregister etc).

Returns:
  action list

### getTableTransmitter

Transmitter getTableTransmitter()
Returns an object that can send send the currently selected table from TOPCAT to other applications.

Returns:
  table transmitter

### createImageTransmitter

Transmitter createImageTransmitter(DensityWindow densityWindow)
Returns an object that can send the density map currently displayed in the density plot window to other applications as a FITS image.

Parameters:
  `densityWindow` - density plot window
Returns:
  new image transmitter

### createSubsetTransmitter

Transmitter createSubsetTransmitter(TopcatModel tcModel, SubsetWindow subsetWindow)
Returns an object that can send the RowSubset currently selected in a given subset window to other applications as a row selection on a commonly-known table.

Parameters:
  `tcModel` - table
  `subsetWindow` - subset window
Returns:
  new subset transmitter

### createResourceListTransmitter

Transmitter createResourceListTransmitter(uk.ac.starlink.vo.RegistryPanel regPanel, String resourceType)
Returns an object that can send the currently displayed resources from a registry panel.

Parameters:
  `regPanel` - registry panel component
  `resourceType` - resource subtype - must match the appropriate voresource.loadlist.* MType subtype
Returns:
  new resource list transmitter

### createSkyPointActivity

SkyPointActivity createSkyPointActivity()
Returns an object which can be used to send messages drawing attention to particular sky positions.

Returns:
  new activity object

### createRowActivity

RowActivity createRowActivity()
Returns an object which can be used to send messages highlighting single table rows.

Returns:
  new activity object

### createSubsetActivity

SubsetActivity createSubsetActivity()
Returns an object which can be used to send messages selecting table row subsets.

Returns:
  new activity object

### createImageActivity

ImageActivity createImageActivity()
Returns an object which can be used to display images. Note this may include options apart from interop-type ones (display in local viewers).

Returns:
  new activity object

### createSpectrumActivity

SpectrumActivity createSpectrumActivity()
Returns an object which can be used to display spectra.

Returns:
  new activity object

### startHub

void startHub(boolean external) throws IOException
Attempts to start a messaging hub suitable for use with this object.

Parameters:
  `external` - true to run hub in external JVM, false to run it in the current one
Throws:
  `IOException`

### maybeStartHub

void maybeStartHub() throws IOException
According to the policy of this communicator, this method may start a hub if none is already running.

Throws:
  `IOException`

### createInfoPanel

JComponent createInfoPanel()
Optionally returns a panel which can be displayed in the control window to show communications status.

Returns:
  status component, or null if unimplemented

### createWindowAction

Action createWindowAction(Component parent)
Constructs an action which will display a control window for this communicator.

Parameters:
  `parent` - parent component
Returns:
  communicator control window, or null if none is available

### isConnected

boolean isConnected()
Indicates (without attempting a connection) whether a hub connection is currently in force.

Returns:
  whether hub is connected

### addConnectionListener

void addConnectionListener(ChangeListener listener)
Adds a listener which will be notified any time that connection status may have changed.

Parameters:
  `listener` - listener to add