Package uk.ac.starlink.topcat

## Class TopcatUtils

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

-     public class TopcatUtils
      extends java.lang.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 | Description
    --- | --- | ---
    `static uk.ac.starlink.table.ValueInfo` | `ACTIVATORS_INFO` | Parameter key for storing an activation action for a table.
    `static uk.ac.starlink.table.ValueInfo` | `COLID_INFO` | Column auxiliary metadata key identifying the uniqe column identifier for use in algebraic expressions.
    `static java.lang.String` | `DEMO_LOCATION` |
    `static java.lang.String` | `DEMO_NODES` |
    `static java.lang.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 java.lang.String` | `STATUS_URL` |
    `static uk.ac.starlink.table.ValueInfo` | `TIME_INFO` | Data identifier for epoch-type data.
    `static java.lang.String` | `VERSION_RESOURCE` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TopcatUtils()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static void` | `addSubset​(javax.swing.JComponent parent, TopcatModel tcModel, java.util.BitSet matchMask, java.lang.String dfltName, java.lang.String[] msgLines, java.lang.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​(javax.swing.JComponent[] comps)` | Reshapes a set of components so that they all have the same preferred size (that of the largest one).
    `static boolean` | `canExec()` | Indicates whether we have System.exec permission.
    `static boolean` | `canJel()` | Indicates if it's possible to use JEL to compile algebraic expressions.
    `static boolean` | `canSog()` | Indicates whether there are enough classes to make SoG work at runtime.
    `static TopcatModel` | `decodeSession​(uk.ac.starlink.table.StarTable table, java.lang.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 boolean` | `equals​(java.lang.Object o1, java.lang.Object o2)` | Determines whether two objects are equal in the sense of `Object.equals(java.lang.Object)`.
    `static java.lang.String` | `formatLong​(long num)` | Formats a long value for presentation as text.
    `static java.lang.String[]` | `getAbout()` | Returns some lines of text describing this copy of the software including its version and versions of some important components.
    `static java.lang.String` | `getApplicationName()` | Returns the name of this application.
    `static java.lang.String` | `getBaseName​(java.lang.String origName, java.lang.String baseSuffix)` | Returns the base name of a column; that is one without any suffix based on `baseSuffix`.
    `static java.lang.String` | `getDistinctName​(ColumnList colList, java.lang.String origName, java.lang.String baseSuffix)` | Returns a column name based on a given one which is guaranteed distinct from any others in the column list.
    `static java.lang.String` | `getExpression​(uk.ac.starlink.table.ColumnInfo info)` | Returns the expression text for a column.
    `static java.lang.String` | `getRevision()` | Returns the version control revision number for TOPCAT and its dependencies.
    `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 java.lang.String` | `getSTILVersion()` | Returns the version string for the version of STIL being used here.
    `static java.lang.String` | `getVersion()` | Returns the version string for this copy of TOPCAT.
    `static void` | `memoryError​(java.lang.OutOfMemoryError e)` | Alerts the user that the system has run out of memory, and provides the option of some useful tips.
    `static void` | `memoryErrorLater​(java.lang.OutOfMemoryError e)` | Queues a `memoryError(java.lang.OutOfMemoryError)` call for later execution on the event dispatch thread.

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

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

- - ### Field Detail

    - #### DEMO_LOCATION

          public static java.lang.String DEMO_LOCATION

    - #### DEMO_TABLE

          public static java.lang.String DEMO_TABLE

    - #### DEMO_NODES

          public static java.lang.String DEMO_NODES

    - #### VERSION_RESOURCE

          public static final java.lang.String VERSION_RESOURCE

      See Also:
        Constant Field Values

    - #### STATUS_URL

          public static final java.lang.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.

    - #### ACTIVATORS_INFO

          public static final uk.ac.starlink.table.ValueInfo ACTIVATORS_INFO

      Parameter key for storing an activation action for a table.

    - #### 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 java.lang.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 java.lang.String getBaseName​(java.lang.String origName,
                                                     java.lang.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 java.lang.String getDistinctName​(ColumnList colList,
                                                         java.lang.String origName,
                                                         java.lang.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 java.lang.String getApplicationName()

      Returns the name of this application.
      Returns:
        "TOPCAT"

    - #### getAbout

          public static java.lang.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

    - #### memoryError

          public static void memoryError​(java.lang.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​(java.lang.OutOfMemoryError e)

      Queues a `memoryError(java.lang.OutOfMemoryError)` call for later execution on the event dispatch thread.
      Parameters:
        `e` - exception, or null

    - #### canSog

          public static boolean canSog()

      Indicates whether there are enough classes to make SoG work at runtime.
      Returns:
        true iff it's safe to use a SoG-based viewer

    - #### canExec

          public static boolean canExec()

      Indicates whether we have System.exec permission.
      Returns:
        true if it's possible to exec

    - #### canJel

          public static boolean canJel()

      Indicates if it's possible to use JEL to compile algebraic expressions. If the security manager does not permit creation of private class loaders, it will fail.
      Returns:
        true iff JEL epxression compilation will work

    - #### getVersion

          public static java.lang.String getVersion()

      Returns the version string for this copy of TOPCAT.
      Returns:
        version number only

    - #### getRevision

          public static java.lang.String getRevision()

      Returns the version control revision number for TOPCAT and its dependencies.
      Returns:
        revision identifier

    - #### getSTILVersion

          public static java.lang.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​(java.lang.Object o1,
                                       java.lang.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

    - #### formatLong

          public static java.lang.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​(javax.swing.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

    - #### addSubset

          public static void addSubset​(javax.swing.JComponent parent,
                                       TopcatModel tcModel,
                                       java.util.BitSet matchMask,
                                       java.lang.String dfltName,
                                       java.lang.String[] msgLines,
                                       java.lang.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,
                                                  java.lang.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

Copyright © 2003-2018 CCLRC: Council for the Central Laboratory of the Research Councils. All Rights Reserved.