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

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