TopcatUtils (TOPCAT API)

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

```
public class TopcatUtils
extends Object
```
Class containing miscellaneous static methods and constants for use in TOPCAT.

Since:

19 Aug 2004

Author:

Mark Taylor

Field Summary

Fields
Modifier and Type	Field and Description
`static uk.ac.starlink.table.ValueInfo`	`COLID_INFO` Column auxiliary metadata key identifying the uniqe column identifier for use in algebraic expressions.
`static String`	`DEMO_LOCATION`
`static String`	`DEMO_NODES`
`static String`	`DEMO_TABLE`
`static uk.ac.starlink.table.ValueInfo`	`EXPR_INFO` Column auxiliary metadata key identifying the text string which gives an expression for a synthetic column.
`static uk.ac.starlink.table.ValueInfo`	`NUMERIC_CONVERTER_INFO` Column auxiliary metadata key identifying an object which can convert from non-numeric cell values to numeric ones.
`static String`	`STATUS_URL`
`static uk.ac.starlink.table.ValueInfo`	`TIME_INFO` Data identifier for epoch-type data.
`static String`	`VERSION_RESOURCE`

Constructor Summary

Constructors
Constructor and Description

TopcatUtils()

Constructors
Constructor and Description
`TopcatUtils()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`addSubset(JComponent parent, TopcatModel tcModel, BitSet matchMask, String dfltName, String[] msgLines, String title)` Using input from the user, adds a new (or reused) Row Subset to the given TopcatModel based on a given BitSet.
`static void`	`alignComponents(JComponent[] comps)` Reshapes a set of components so that they all have the same preferred size (that of the largest one).
`static boolean`	`canJel()` Indicates if it's possible to use JEL to compile algebraic expressions.
`static TopcatModel`	`decodeSession(uk.ac.starlink.table.StarTable table, String location, ControlWindow controlWindow)` Attempts to unpack a StarTable into a TopcatModel containing per-table application session information.
`static uk.ac.starlink.table.StarTable`	`encodeSession(TopcatModel tcModel)` Encodes a TopcatModel as a StarTable including per-table session information, suitable for serialization.
`static void`	`enquireLatestVersion()` Ascertains the most recent release using an external connection, and reports through the logging system as appropriate.
`static void`	`ensureRowIndexIsVisible(JTable jtab, int irow)` Scrolls a JTable as necessary to ensure that a given row index is scrolled to the visible part of the viewport.
`static boolean`	`equals(Object o1, Object o2)` Determines whether two objects are equal in the sense of `Object.equals(java.lang.Object)`.
`static String`	`formatLong(long num)` Formats a long value for presentation as text.
`static String[]`	`getAbout()` Returns some lines of text describing this copy of the software including its version and versions of some important components.
`static String`	`getApplicationName()` Returns the name of this application.
`static String`	`getBaseName(String origName, String baseSuffix)` Returns the base name of a column; that is one without any suffix based on `baseSuffix`.
`static Desktop`	`getBrowserDesktop()` Returns a browse-capable desktop instance, or null if none is available.
`static String`	`getDistinctName(ColumnList colList, String origName, String baseSuffix)` Returns a column name based on a given one which is guaranteed distinct from any others in the column list.
`static java.util.function.Consumer<URL>`	`getDocUrlHandler()` Returns an object that will take documentation-type URLs and display them somehow, probably in an external browser window.
`static String`	`getExpression(uk.ac.starlink.table.ColumnInfo info)` Returns the expression text for a column.
`static String`	`getRevision()` Returns the version control revision number for TOPCAT and its dependencies.
`static List<uk.ac.starlink.table.DescribedValue>`	`getRowAsParameters(TopcatModel tcModel, long lrow)` Returns the values from a row of a given table as a list of DescribedValues, suitable for use as parameters (per-value metadata) of a StarTable.
`static uk.ac.starlink.table.StarTable`	`getSaveTable(TopcatModel tcModel)` Returns the table represented by the current state of a given TopcatModel in a form suitable for persisting into one of the known serialization formats.
`static String`	`getSTILVersion()` Returns the version string for the version of STIL being used here.
`static String`	`getVersion()` Returns the version string for this copy of TOPCAT.
`static String`	`identityString(Object obj)` Returns a string unique to an object's identity.
`static void`	`memoryError(OutOfMemoryError e)` Alerts the user that the system has run out of memory, and provides the option of some useful tips.
`static void`	`memoryErrorLater(OutOfMemoryError e)` Queues a `memoryError(java.lang.OutOfMemoryError)` call for later execution on the event dispatch thread.
`static boolean`	`setAboutHandler(Runnable doAbout)` Invokes the java.awt.Desktop.setAboutHandler method.
`static void`	`setClipboardText(String txt)` Sets the text content of the system clipboard(s).
`static void`	`showAbout(Component parent)` Displays an informational About TOPCAT window.

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

- Field Detail
  - DEMO_LOCATION
```
public static String DEMO_LOCATION
```
  - DEMO_TABLE
```
public static String DEMO_TABLE
```
  - DEMO_NODES
```
public static String DEMO_NODES
```
  - VERSION_RESOURCE
```
public static final String VERSION_RESOURCE
```
    See Also:
    
    Constant Field Values
  - STATUS_URL
```
public static final String STATUS_URL
```
    See Also:
    
    Constant Field Values
  - COLID_INFO
```
public static final uk.ac.starlink.table.ValueInfo COLID_INFO
```
    Column auxiliary metadata key identifying the uniqe column identifier for use in algebraic expressions.
  - EXPR_INFO
```
public static final uk.ac.starlink.table.ValueInfo EXPR_INFO
```
    Column auxiliary metadata key identifying the text string which gives an expression for a synthetic column.
  - NUMERIC_CONVERTER_INFO
```
public static final uk.ac.starlink.table.ValueInfo NUMERIC_CONVERTER_INFO
```
    Column auxiliary metadata key identifying an object which can convert from non-numeric cell values to numeric ones.
  - TIME_INFO
```
public static final uk.ac.starlink.table.ValueInfo TIME_INFO
```
    Data identifier for epoch-type data.
- Constructor Detail
  - TopcatUtils
```
public TopcatUtils()
```
- Method Detail
  - getSaveTable
```
public static uk.ac.starlink.table.StarTable getSaveTable(TopcatModel tcModel)
```
    Returns the table represented by the current state of a given TopcatModel in a form suitable for persisting into one of the known serialization formats.
    This basicaly uses TopcatModel.getApparentStarTable(), but may apply a few extra tweaks for a table that is known to be about to be saved.
    
    Parameters:
    
    tcModel - topcat model
    
    Returns:
    
    saveable table
  - getExpression
```
public static String getExpression(uk.ac.starlink.table.ColumnInfo info)
```
    Returns the expression text for a column. This should only have a non-null value for synthetic columns.
    
    Parameters:
    
    info - column info
    
    Returns:
    
    synthetic expression string
  - getBaseName
```
public static String getBaseName(String origName,
                                 String baseSuffix)
```
    Returns the base name of a column; that is one without any suffix based on baseSuffix. This method is used in conjunction with getDistinctName(uk.ac.starlink.topcat.ColumnList, java.lang.String, java.lang.String).
    
    Parameters:
    
    origName - full name, possibly including bits of suffix
    
    baseSuffix - the base suffix string
    
    Returns:
    
    name without any suffix-like elements of the sort specified by baseSuffix
  - getDistinctName
```
public static String getDistinctName(ColumnList colList,
                                     String origName,
                                     String baseSuffix)
```
    Returns a column name based on a given one which is guaranteed distinct from any others in the column list. If the submitted origName is already unique, it may be returned. Otherwise a new name may be made which involves appending the given baseSuffix to it.
    
    Parameters:
    
    colList - column list within which distinct naming is required
    
    origName - initial name
    
    baseSuffix - suffix used for deduplication
    
    Returns:
    
    a name resembling origName which is not the same as any existing column names in colList
    
    See Also:
    
    getBaseName(java.lang.String, java.lang.String)
  - getApplicationName
```
public static String getApplicationName()
```
    Returns the name of this application.
    
    Returns:
    
    "TOPCAT"
  - getAbout
```
public static String[] getAbout()
```
    Returns some lines of text describing this copy of the software including its version and versions of some important components.
    
    Returns:
    
    lines of About text
  - getDocUrlHandler
```
public static java.util.function.Consumer<URL> getDocUrlHandler()
```
    Returns an object that will take documentation-type URLs and display them somehow, probably in an external browser window.
    
    Returns:
    
    url handler, or null if browsing is not possible
  - getRowAsParameters
```
public static List<uk.ac.starlink.table.DescribedValue> getRowAsParameters(TopcatModel tcModel,
                                                                           long lrow)
```
    Returns the values from a row of a given table as a list of DescribedValues, suitable for use as parameters (per-value metadata) of a StarTable.
    
    Parameters:
    
    tcModel - table supplying values
    
    lrow - row index
    
    Returns:
    
    list of described values
  - setClipboardText
```
public static void setClipboardText(String txt)
```
    Sets the text content of the system clipboard(s). This is somewhat OS-dependent. X11 uses a PRIMARY selection (middle mouse button) alongside the CLIPBOARD selection (explicit cut'n'paste). JTextComponents fill both, though not under exactly the same circumstances. This method sets the text for both if both are available. This may not replicate exactly the behaviour expected by X clients, but I think it's what users would want to happen. I may be wrong.
    
    Parameters:
    
    txt - text to set as clipboard contents
  - ensureRowIndexIsVisible
```
public static void ensureRowIndexIsVisible(JTable jtab,
                                           int irow)
```
    Scrolls a JTable as necessary to ensure that a given row index is scrolled to the visible part of the viewport.
    
    Parameters:
    
    jtab - JTable
    
    irow - table index that must be visible
    
    See Also:
    
    JList.ensureIndexIsVisible(int)
  - memoryError
```
public static void memoryError(OutOfMemoryError e)
```
    Alerts the user that the system has run out of memory, and provides the option of some useful tips.
    
    Parameters:
    
    e - exception, or null
  - memoryErrorLater
```
public static void memoryErrorLater(OutOfMemoryError e)
```
    Queues a memoryError(java.lang.OutOfMemoryError) call for later execution on the event dispatch thread.
    
    Parameters:
    
    e - exception, or null
  - canJel
```
public static boolean canJel()
```
    Indicates if it's possible to use JEL to compile algebraic expressions.
    This used to query the SecurityManager, but the java.lang.SecurityManager class is deprecated for removal in later JREs, and I don't think it's likely that expression compilation will be blocked. So this method currently returns true unconditionally, but retain it in case it turns out there are circumstances we can test for that bear on this.
    
    Returns:
    
    true iff JEL epxression compilation is expected to work
  - getBrowserDesktop
```
public static Desktop getBrowserDesktop()
```
    Returns a browse-capable desktop instance, or null if none is available.
    
    Returns:
    
    desktop
  - getVersion
```
public static String getVersion()
```
    Returns the version string for this copy of TOPCAT.
    
    Returns:
    
    version number only
  - getRevision
```
public static String getRevision()
```
    Returns the version control revision number for TOPCAT and its dependencies.
    
    Returns:
    
    revision identifier
  - getSTILVersion
```
public static String getSTILVersion()
```
    Returns the version string for the version of STIL being used here.
    
    Returns:
    
    STIL version number
  - enquireLatestVersion
```
public static void enquireLatestVersion()
```
    Ascertains the most recent release using an external connection, and reports through the logging system as appropriate.
  - equals
```
public static boolean equals(Object o1,
                             Object o2)
```
    Determines whether two objects are equal in the sense of Object.equals(java.lang.Object). Unlike that method however, it returns true if both objects are null, and won't throw a NullPointerException.
    
    Parameters:
    
    o1 - first object
    
    o2 - second object
    
    Returns:
    
    true if o1.equals(o2) or they're both null
  - identityString
```
public static String identityString(Object obj)
```
    Returns a string unique to an object's identity. This is modelled on the value that Object.toString() usually returns, though not guaranteed to be the same.
    
    Parameters:
    
    obj - object
    
    Returns:
    
    unique string for object
  - formatLong
```
public static String formatLong(long num)
```
    Formats a long value for presentation as text. This typically puts separators between groups of three numbers for improved visibility. TOPCAT policy is usually to do this only for numbers which are, or might be expected to be, quite large.
    
    Parameters:
    
    num - number to format
    
    Returns:
    
    formatted value
  - alignComponents
```
public static void alignComponents(JComponent[] comps)
```
    Reshapes a set of components so that they all have the same preferred size (that of the largest one).
    
    Parameters:
    
    comps - components to align
  - showAbout
```
public static void showAbout(Component parent)
```
    Displays an informational About TOPCAT window.
    
    Parameters:
    
    parent - parent component
  - setAboutHandler
```
public static boolean setAboutHandler(Runnable doAbout)
```
    Invokes the java.awt.Desktop.setAboutHandler method. Since that method was introduced at Java 9, and at time of writing the build and minimal target deployment platform is Java 8, this is done by reflection, and hence will only do useful work in a runtime environment of >=9. This method only does useful work anyway on certain platforms, notably MacOS, for which an About button is part of the standard application GUI. If for whatever reason the assignment doesn't work, it fails silently.
    If the target platform is upgraded one day to Java >= 9, this reflective code can be eliminated or replaced by something very much simpler.
    
    Parameters:
    
    doAbout - callback to display an About Application window
    
    Returns:
    
    true iff the handler installation apparently succeeded
  - addSubset
```
public static void addSubset(JComponent parent,
                             TopcatModel tcModel,
                             BitSet matchMask,
                             String dfltName,
                             String[] msgLines,
                             String title)
```
    Using input from the user, adds a new (or reused) Row Subset to the given TopcatModel based on a given BitSet.
    
    Parameters:
    
    parent - parent component for dialogue
    
    tcModel - topcat model
    
    matchMask - mask for included rows
    
    dfltName - default name for subset
    
    msgLines - lines of text to appear in dialogue window
    
    title - dialogue window title
  - encodeSession
```
public static uk.ac.starlink.table.StarTable encodeSession(TopcatModel tcModel)
```
    Encodes a TopcatModel as a StarTable including per-table session information, suitable for serialization.
    
    Parameters:
    
    tcModel - model
    
    Returns:
    
    table
  - decodeSession
```
public static TopcatModel decodeSession(uk.ac.starlink.table.StarTable table,
                                        String location,
                                        ControlWindow controlWindow)
```
    Attempts to unpack a StarTable into a TopcatModel containing per-table application session information. For this to work it must have been written using one of the TopcatCodec formats that this application is aware of. If not, null is returned.
    
    Parameters:
    
    table - encoded table
    
    location - table location string
    
    controlWindow - control window, or null if necessary
    
    Returns:
    
    topcat model, or null

Class TopcatUtils

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEMO_LOCATION

DEMO_TABLE

DEMO_NODES

VERSION_RESOURCE

STATUS_URL

COLID_INFO

EXPR_INFO

NUMERIC_CONVERTER_INFO

TIME_INFO

Constructor Detail

TopcatUtils

Method Detail

getSaveTable

getExpression

getBaseName

getDistinctName

getApplicationName

getAbout

getDocUrlHandler

getRowAsParameters

setClipboardText

ensureRowIndexIsVisible

memoryError

memoryErrorLater

canJel

getBrowserDesktop

getVersion

getRevision

getSTILVersion

enquireLatestVersion

equals

identityString

formatLong

alignComponents

showAbout

setAboutHandler

addSubset

encodeSession

decodeSession