Package org.cytoscape.jobs

Interface CyJobDataService

public interface CyJobDataService
The main interface for the marshalling and unmarshalling of data to be exchanged with remote services. Implementations of this interface will often be independent of the remote service (e.g. a JSON implementation of CyJobDataService may be used for multiple backend services). Not all of the methods will be provided by every implementation (see the default methods below).

Cytoscape Backwards Compatibility (SPI Interface): We expect that this interface will be implemented. Therefore to maintain backwards compatibility this interface will only be modified for major version updates.

Module: jobs-api

To use this in your app, include the following dependency in your POM:

<dependency>
    <groupId>org.cytoscape</groupId>
    <artifactId>jobs-api</artifactId>
</dependency>

  • Method Details

    • getServiceName

      String getServiceName()
      The name of the service. This is usually the classname and is the name that should be registered with OSGi.
      Returns:
      the service name

    • getDataInstance

      CyJobData getDataInstance()
      Returns an empty instance of CyJobData that may be used with this service. Note that implementations of CyJobData are not meant to be compatible even though they implement a small common subset of methods.
      Returns:
      an empty CyJobData

    • addData

      CyJobData addData​(CyJobData data, String key, Map<Object,​Object> mapData)
      Add generic key, value pairs to a CyJobData item. If the data argument is null, create a new CyJobData object initialized with mapData.
      Parameters:
      data - if not null, add mapData to this data object.
      key - a key string used to retrieve the data
      mapData - the data to add.
      Returns:
      data if provided, else a new CyJobData object

    • addData

      CyJobData addData​(CyJobData data, String key, Object mapData)
      Add a single data item to a CyJobData object. If the data argument is null, create a new CyJobData object initialized with mapData.
      Parameters:
      data - if not null, add item to this data object.
      key - a key string used to retrieve the data
      item - the data to add.
      Returns:
      data if provided, else a new CyJobData object

    • addData

      default CyJobData addData​(CyJobData data, String key, CyNetwork network, List<? extends CyIdentifiable> nodesAndEdges, List<String> nodeColumns, List<String> edgeColumns)
      An optional method to add network data to a CyJobData item. If the data argument is null, create a new CyJobData object initialized with the network data. If the list of nodes and edges (nodesAndEdges is provided, the network data will be restricted to this list. The list of nodeColumns and edgeColumns will restrict the attributes to those columns. For implementations that intent to use a column other than the SUID to map the data back, by convention the key column should be the first column in the list and the list should not be empty.
      NOTE: it is important that implementations of this method deal with the mapping of network, node, and edge SUIDs, which will change across sessions. Typically, this will be done by adding a new column in the appropriate HIDDEN_ATTRS table with the name or id of the job. A utility class SUIDUtil is provided to support one possible mechanism to do this
      Parameters:
      data - if not null, add the model data to this data object.
      key - a key string used to retrieve the data
      network - the CyNetwork to extract the data from.
      nodesAndEdges - the list of org.cytoscape.modelCyNodes and org.cytoscape.modelCyEdges to encode. If null or empty, the entire network will be added
      nodeColumns - the list of columns to include for node data
      edgeColumns - the list of columns to include for edge data
      Returns:
      data if provided, else a new CyJobData object

    • addData

      default CyJobData addData​(CyJobData data, String key, CyTable table, List<CyRow> rows, List<String> columns)
      An optional method to add table data to a CyJobData item. If the data argument is null, create a new CyJobData object initialized with the table data. If the list of CyRows (rows is is provided, the table data will be restricted to these rows. The list of columns will restrict the data to those columns. For implementations that intent to use a column other than the SUID to map the data back, by convention the key column should be the first column in the list and the list should not be empty.
      NOTE: it is important that implementations of this method deal with the mapping of SUIDs, which will change across sessions. Typically, this will be done by adding a new column in the appropriate HIDDEN_ATTRS table with the name or id of the job. A utility class SUIDUtil is provided to support one possible mechanism to do this
      Parameters:
      data - if not null, add the model data to this data object.
      key - a key string used to retrieve the data
      table - the CyTable to extract the data from.
      rows - the list of CyRows to encode. If null or empty, the entire table will be added
      columns - the list of columns to include from table
      Returns:
      data if provided, else a new CyJobData object

    • addData

      default CyJobData addData​(CyJobData data, String key, CyNetworkView networkView, List<? extends CyIdentifiable> nodesAndEdges, List<VisualProperty<?>> properties)
      An optional method to add network view data to a CyJobData item. If the data argument is null, create a new CyJobData object initialized with the network view data. If the list of nodes and edges (nodesAndEdges is provided, the view data will be restricted to this list. The list of properties will restrict the VisualPropertys to only those in the list. NOTE: it is important that implementations of this method deal with the mapping of network, node, and edge SUIDs, which will change across sessions. Typically, this will be done by adding a new column in the appropriate HIDDEN_ATTRS table with the name or id of the job. A utility class SUIDUtil is provided to support one possible mechanism to do this
      Parameters:
      data - if not null, add the model data to this data object.
      key - a key string used to retrieve the data
      networkView - the CyNetworkView to extract the data from.
      nodesAndEdges - the list of CyNodes and CyEdges to encode. If null or empty, the entire network view will be added
      properties - the list of visual properties to include
      Returns:
      data if provided, else a new CyJobData object

    • getData

      Object getData​(CyJobData data, String key)
      Extract data from a CyJobData object.
      Parameters:
      data - the CyJobData object that has the data
      key - the key that accesses the data
      Returns:
      the untyped data, or null if the data doesn't exist. Note that it is up to the consumer to determine if this object is of the correct type.

    • getMapData

      Map<Object,​Object> getMapData​(CyJobData data, String key)
      Extract a map from a CyJobData object.
      Parameters:
      data - the CyJobData object that has the map
      key - the key that accesses the map
      Returns:
      the map itself, or null if the data doesn't exist.

    • getNetworkData

      default CyNetwork getNetworkData​(CyJobData data, String key)
      Optional method to extract network data from a CyJobData object.
      Parameters:
      data - the CyJobData object that has the CyNetwork
      key - the key that accesses the network
      Returns:
      the returned network or null if it doesn't exist. This should include any nodes, edges, and network tables that were included

    • getTableData

      default CyTable getTableData​(CyJobData data, String key)
      Optional method to extract table data (usually not model associated tables) from a CyJobData object.
      Parameters:
      data - the CyJobData object that has the CyTable
      key - the key that accesses the table
      Returns:
      the returned table or null if it doesn't exist. This should include any rows and columns that were included.

    • getViewData

      default CyNetworkView getViewData​(CyJobData data, String key)
      Optional method to extract data for a CyNetworkView from a CyJobData object.
      Parameters:
      data - the CyJobData object that has the CyNetworkView
      key - the key that accesses the table
      Returns:
      the returned view or null if it doesn't exist. Note that this will only include view data for the nodes and edges specified in the CyJobData store. All VisualProperty values will be default unless explicitly included, in which case they will be overrides.

    • getSerializedData

      Object getSerializedData​(CyJobData data)
      This method is used to extract the data from the CyJobData object in a form that is appropriate for use by the job execution service. This method will be called by CyJobExecutionService.executeJob(CyJob, String, Map, CyJobData) method to serialize all of the data in the CyJobData object for submission to the remote service.
      Parameters:
      data - the input data
      Returns:
      the serialized data

    • deserialize

      CyJobData deserialize​(Object object)
      This method is used to create a new CyJobData object from a serialized data object retrieved from a remote execution. This method will be called from the CyJobExecutionService.fetchResults(CyJob, CyJobData) to unmarshal the data sent by the finished job.
      Parameters:
      object - the serialized data object
      Returns:
      a the CyJobData object containing the unserialized data

    • deserialize

      CyJobData deserialize​(Reader reader)
      This method is used to create a new CyJobData object from a serialized data stream retrieved from a remote execution. This method will be called from the CyJobExecutionService.fetchResults(CyJob, CyJobData) to unmarshal the data sent by the finished job.
      Parameters:
      object - the serialized data stream
      Returns:
      a the CyJobData object containing the unserialized data

    • deserialize

      CyJobData deserialize​(InputStream inputStream)
      This method is used to create a new CyJobData object from a serialized data stream retrieved from a remote execution. This method will be called from the CyJobExecutionService.fetchResults(CyJob, CyJobData) to unmarshal the data sent by the finished job.
      Parameters:
      object - the serialized data stream
      Returns:
      a the CyJobData object containing the unserialized data