Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS | NEXT CLASS	FRAMES | NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

Class ncsa.horizon.model.FileFormat

java.lang.Object
  |
  +--ncsa.horizon.model.FileFormat

Subclasses:

RemoteFileFormat, SupportedFileFormat, UnknownFileFormat

public abstract class FileFormat

extends java.lang.Object

implements java.io.Serializable

a representation of the format of a file and methods for handling it.

A FileFormat object identifies the format of a data file, a characteristic necessary for reading the file's contents. This class encapsulates three major ways of identifying a file of the format the class represents:

1. recognized filename extensions
2. recognized MIME types
3. a unique pattern of leading bytes from the file (as encapsulated by a MagicNumber object).

This class also specifies factory methods for creating a FileHander object that is used for selecting and creating a Viewable of an array within the data file in a format-independent way.

The common way that one obtains a FileFormat object is by handing the file in question to one of the Horizon class's static getFileFormat() methods.

Supporting New File Formats

Horizon uses the FileFormat class as first tool for supporting a format in an automated, format-independent way. In particular, the Dataset class will open a file of some type by first determining its format type by testing it against known file formats, each of which are represented by an instance of this class. Thus, to add such automatic support for a new class, one must represent a format by a FileFormat object.

This is most easily done by instantiating the SimplySupportedFileFormat class with parameters that properly describe the new format. The most important parameter is the name of a FormatHandler class that can read the contents of the data file. In most cases, this method will be sufficient for identifying a new format.

One can take greater control of handling the identification of a file format and/or the creation of a FormatHandler object to read the file by subclassing this class. This is more easily done by subclassing the SupportedFileFormat which provides default implementations of all methods save the createFormatHandler() method. To allow fully automated support for the new format in a Horizon application, the application should instantiate a FileFormat object and register it with the Horizon system via Horizon.supportFileFormat(). This allows an application to handle files ofthe new format in an automated way along side of other supported formats without explicit knowledge of its actual format.

See Also:

Serialized Form

Constructor Summary

FileFormat()

Method Summary

FormatHandler	createFormatHandler(java.lang.Object data) create a FormatHandler object for a given identifying object.
java.lang.String[]	getContentTypes() return the MIME types that can be associated with this file format.
java.lang.String	getDescription() return a short string describing the format.
java.lang.String[]	getExtensions() return a list of the recognized file extensions identifying a file as having this format.
MagicNumber	getMagicNumber() return a MagicNumber object that represents the leading byte signiture for the file format, or null if such a signiture is not known.
java.lang.String	getName() get the name of this file format.
java.lang.String	getReference() return a string giving a reference to definition of or information about the format.
java.lang.String	getReferenceURL() return a URL to a reference to definition of or information about the format.

Methods inherited from class java.lang.Object

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

Constructor Detail

FileFormat

public FileFormat()

Method Detail

getName

public abstract java.lang.String getName()

get the name of this file format. The return should be non-null.

getDescription

public abstract java.lang.String getDescription()

return a short string describing the format. This can be null.

getReference

public abstract java.lang.String getReference()

return a string giving a reference to definition of or information about the format. This can be null.

getReferenceURL

public abstract java.lang.String getReferenceURL()

return a URL to a reference to definition of or information about the format. This can be null.

getContentTypes

public abstract java.lang.String[] getContentTypes()

return the MIME types that can be associated with this file format. If null is returned, no MIME types are known.

getMagicNumber

public abstract MagicNumber getMagicNumber()

return a MagicNumber object that represents the leading byte signiture for the file format, or null if such a signiture is not known.

See Also:

MagicNumber

getExtensions

public abstract java.lang.String[] getExtensions()

return a list of the recognized file extensions identifying a file as having this format. These extensions should start with a period if applicable. If null is returned, no extensions will be recognized.

createFormatHandler

public abstract FormatHandler createFormatHandler(java.lang.Object data)
                                                             throws DataAccessException,
                                                                    UnsupportedFormatException,
                                                                    java.lang.IllegalArgumentException

create a FormatHandler object for a given identifying object.

Parameters:

data - the object identifying the data file. This is usually a File or a URL but can be something else depending on the format.