# Class CdsUploadMatcher

java.lang.Object
uk.ac.starlink.ttools.cone.CdsUploadMatcher

All Implemented Interfaces:
  `UploadMatcher`

public class CdsUploadMatcher extends Object implements UploadMatcher
UploadMatcher implementation for the CDS Xmatch service. This class encapsulates all the information about the CDS Xmatch I/O interface.

Since:
  14 May 2014
Author:
  Mark Taylor

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`CdsUploadMatcher.VizierMeta`
Metadata provided for Vizier tables by the CDS Xmatch service.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`SIMBAD_NAME`
Alias for Simbad flat view table.
`static final boolean`
`UPLOAD_EMPTY`
Whether it is safe/recommended to upload empty tables to match.
`static final String`
`XMATCH_URL`
URL for the CDS Xmatch service.

## Constructor Summary

Constructors
Constructor
Description
`CdsUploadMatcher(URL serviceUrl, String tableId, double srArcsec, ServiceFindMode serviceMode, uk.ac.starlink.util.ContentCoding coding)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`ColumnPlan`
`getColumnPlan(uk.ac.starlink.table.ColumnInfo[] resultCols, uk.ac.starlink.table.ColumnInfo[] uploadCols)`
Returns an object that understands what columns are where in an output table generated from the raw result produced by this matcher.
`static String[]`
`readAliases()`
Reads the list of VizieR table aliases that can be used with the Xmatch service.
`static CdsUploadMatcher.VizierMeta`
`readVizierMetadata(String vizName)`
Reads basic table metadata for a given VizieR table.
`static String[]`
`readVizierNames()`
Reads the list of VizieR table names that can be used with the Xmatch service.
`boolean`
`streamRawResult(ConeQueryRowSequence coneSeq, uk.ac.starlink.table.TableSink rawResultSink, RowMapper<?> rowMapper, long maxrec)`
Scans a sequence of positional queries, uploads it to a remote service, and writes the returned values to a given sink.
`static String`
`toCdsId(String txt)`
Turns a user-supplied string referencing a CDS table into an identifier recognisable by the CDS Xmatch service.

### Methods inherited from class Object

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

## Field Details

### XMATCH_URL

public static final String XMATCH_URL
URL for the CDS Xmatch service.

See Also:
  - Constant Field Values

### SIMBAD_NAME

public static final String SIMBAD_NAME
Alias for Simbad flat view table.

See Also:
  - Constant Field Values

### UPLOAD_EMPTY

public static final boolean UPLOAD_EMPTY
Whether it is safe/recommended to upload empty tables to match.

See Also:
  - Constant Field Values

## Constructor Details

### CdsUploadMatcher

public CdsUploadMatcher(URL serviceUrl, String tableId, double srArcsec, ServiceFindMode serviceMode, uk.ac.starlink.util.ContentCoding coding)
Constructor.

Parameters:
  `serviceUrl` - URL of Xmatch service
  `tableId` - identifier of remote table
  `srArcsec` - match radius in arcseconds
  `serviceMode` - type of match
  `coding` - configures HTTP compression for result

## Method Details

### streamRawResult

public boolean streamRawResult(ConeQueryRowSequence coneSeq, uk.ac.starlink.table.TableSink rawResultSink, RowMapper<?> rowMapper, long maxrec) throws IOException
Description copied from interface: `UploadMatcher`
Scans a sequence of positional queries, uploads it to a remote service, and writes the returned values to a given sink.

Both the read and the write should ideally be streamed (read as uploaded and written as received) so that progress can be logged properly.

The result is written to the given `rawResultSink` (which will probably be a `RowStore`). To make sense of the table thus written, it is necessary to use the `RowMapper` supplied to this method and the `ColumnPlan` available from this object. The RowMapper associates result rows with queries from the input row sequence, and the ColumnPlan knows where the special and other columns are in the result table.

Specified by:
  `streamRawResult` in interface `UploadMatcher`
Parameters:
  `coneSeq` - sequence of cone-like positional queries
  `rawResultSink` - destination for result rows obtained from the target matcher service
  `rowMapper` - used to label rows; queries are labelled with the value returned from the `getIndex` method of `coneSeq`
  `maxrec` - user-supplied limit on the maximum number of output rows, though the service may truncate the result; if <0, no limit is requested
Returns:
  true iff the result was truncated due to overflow
Throws:
  `IOException`

### getColumnPlan

public ColumnPlan getColumnPlan(uk.ac.starlink.table.ColumnInfo[] resultCols, uk.ac.starlink.table.ColumnInfo[] uploadCols)
Description copied from interface: `UploadMatcher`
Returns an object that understands what columns are where in an output table generated from the raw result produced by this matcher.

Specified by:
  `getColumnPlan` in interface `UploadMatcher`
Parameters:
  `resultCols` - columns in the raw result table written by this object's `streamRawResult` method
  `uploadCols` - columns from the table that will be joined to the raw result to get the output table
Returns:
  column plan

### toCdsId

public static String toCdsId(String txt)
Turns a user-supplied string referencing a CDS table into an identifier recognisable by the CDS Xmatch service. At present this just prepends a "vizier:" where applicable.

Parameters:
  `txt` - table name
Returns:
  xmatch service identifier

### readAliases

public static String[] readAliases() throws IOException
Reads the list of VizieR table aliases that can be used with the Xmatch service. This is expected to be a short list (a few tens of entries).

Returns:
  alias list
Throws:
  `IOException`

### readVizierNames

public static String[] readVizierNames() throws IOException
Reads the list of VizieR table names that can be used with the Xmatch service. This is expected to be several thousand entries long.

Returns:
  table name list
Throws:
  `IOException`

### readVizierMetadata

public static CdsUploadMatcher.VizierMeta readVizierMetadata(String vizName) throws IOException
Reads basic table metadata for a given VizieR table.

Parameters:
  `vizName` - vizier table name or ID
Returns:
  basic metadata object
Throws:
  `IOException`