uk.ac.starlink.gbin

## Class GbinObjectReader

- java.lang.Object
- - uk.ac.starlink.gbin.GbinObjectReader

-     public class GbinObjectReader
      extends java.lang.Object

  Provides read services for an object implementing the `gaia.cu1.tools.dal.gbin.GbinReader` interface. This object can read the elements stored in a GBIN file.

  Access is via reflection, so I don't need GaiaTools on the classpath at build time, for several reasons:

  - The GbinReader class is targeted at Java 1.7, and at time of writing STIL is targeted at java 1.5
  - GbinReader and its dependencies are probably large and complicated (though I haven't actually checked that)
  - To use this class for most actual GBIN files, you're going to need Gaia data model classes on the classpath which I have no intention of packaging with STIL. If you have the data model classes on the path, there's a good chance that you've got the relevant bits of GaiaTools as well.
  - It can benefit from future GbinReader implementations without requiring updates to the code in STIL (as long as the basic interfaces don't change).
  Since:
    13 Aug 2014

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `GbinObjectReader(java.lang.Object gbinReaderObj)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.Object` | `createGbinReaderObject(java.io.InputStream in)` Constructs a GbinReader from a given input stream.
    `static GbinObjectReader` | `createReader(java.io.InputStream in)` Attempts to construct a GbinObjectReader that can read records from a given input stream.
    `boolean` | `hasNext()` Indicates whether this reader can read another element.
    `static void` | `initGaiaTools()` Performs GaiaTools setup required before GbinReaders are used etc.
    `static boolean` | `isMagic(byte[] intro)` Indicates whether a buffer containing the first few bytes of a file look like a GBIN magic number.
    `static void` | `logError(java.util.logging.Level level, java.lang.String msg, java.lang.Throwable error)` Write a logging message including an exception.
    `java.lang.Object` | `next()` Reads the next record.

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

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

- - ### Constructor Detail

    - #### GbinObjectReader

          public GbinObjectReader(java.lang.Object gbinReaderObj)

      Constructor.
      Parameters:
        `gbinReaderObj` - object implementing `gaia.cu1.tools.dal.gbin.GbinReader`
      Throws:
        `java.lang.IllegalArgumentException` - if `gbinReaderObj` doesn't appear to be a GbinReader

  - ### Method Detail

    - #### hasNext

          public boolean hasNext()
                          throws java.io.IOException

      Indicates whether this reader can read another element.
      Returns:
        true if another record will be returned by `next`
      Throws:
        `java.io.IOException`

    - #### next

          public java.lang.Object next()
                                throws java.io.IOException

      Reads the next record.
      Returns:
        object implementing `gaia.cu1.tools.dm.GaiaRoot`
      Throws:
        `java.io.IOException`

    - #### createReader

          public static GbinObjectReader createReader(java.io.InputStream in)
                                               throws java.io.IOException

      Attempts to construct a GbinObjectReader that can read records from a given input stream.
      Parameters:
        `in` - input stream containing a GBIN file
      Returns:
        gbin object reader
      Throws:
        `java.io.IOException`

    - #### isMagic

          public static boolean isMagic(byte[] intro)

      Indicates whether a buffer containing the first few bytes of a file look like a GBIN magic number.

      Note this has not been exhaustively tested with all known GBIN variants.

      Parameters:
        `intro` - first few bytes to test
      Returns:
        true if buffer looks like it could be the start of a GBIN file

    - #### initGaiaTools

          public static void initGaiaTools()

      Performs GaiaTools setup required before GbinReaders are used etc. Called by `createReader`. Calls after the first one do nothing, but are harmless and cheap. Uses reflection.

    - #### createGbinReaderObject

          public static java.lang.Object createGbinReaderObject(java.io.InputStream in)
                                                         throws java.io.IOException

      Constructs a GbinReader from a given input stream. Uses reflection to invoke `gaia.cu1.tools.dal.gbin.GbinFactory.getGbinReader()`.
      Parameters:
        `in` - input stream assumed to contain a GBIN file
      Returns:
        object implementing `gaia.cu1.tools.dal.gbin.GbinReader` interface
      Throws:
        `java.io.IOException` - with informative message if something goes wrong, including reflection trouble

    - #### logError

          public static void logError(java.util.logging.Level level,
                                      java.lang.String msg,
                                      java.lang.Throwable error)

      Write a logging message including an exception. This is a drop-in replacement for the method `Logger.log(java.util.logging.Level, String, Throwable)`; it's required because loading the GaiaTools classes seems to mess up the system configuration done by stilts/topcat on startup, so this implementation includes the actual exception stringification in the log message itself, as well as passing the exception itself to the logging system (which seems to get ignored after loading GaiaTools, even with stilts -debug). Exception text is also unlikely to frighten GBIN-competent users.
      Parameters:
        `level` - logging level
        `msg` - basic log message
        `error` - exception