1_-_Introduction

Allan Cunliffe

Xena relies on plugins to allow it to normalise files. The Xena architecture supports dynamic loading of plugins. This means that plugins are loaded when the program is run. The plugins are loaded through the plugin manager in one of two ways:

  • directly with an API call, passing in the fully-qualified class name of the main plugin class
  • as a JAR file that is loaded while Xena is running.

The aim of this How To is to enable you to write a functional Xena plugin. It includes the following:

  • creation of a simple plugin that performs a simple normalisation for a single file type
  • extending the simple normaliser, including the implementation of multiple file inputs, multiple output packages
  • creating a simple file namer
  • creating a simple metadata package wrapper.

Definitions

Normalise

Transform a file from its existing format to XML.

Normaliser

A java object that is a component of a plugin that can transform a file into XML.

Plugin

One or more compiled java classes that may be bundled in a java archive, and can then be used by Xena to perform some of the functions required by Xena.

Plugin Classes

Each plugin consists of a number of classes. Each class performs a specific role in the normalisation process.

XenaPlugin

The XenaPlugin class is used to define the various components which will form a plugin. All plugins need to implement a XenaPlugin subclass.

PluginManager

The plugin manager is the overall control of the plugins within Xena.

FileNamer

The file namer component is responsible for generating new files for Xena output.

The abstract FileNamer has a number of methods and variables. Every FileNamer must have the:

  • option to keep a history file containing the input source and the generated file name
  • option to overwrite Xena output files and use the same name for a given Xena Input Source
  • ability to access a map containing the Xena Input Source names and for each a list of generated filenames.

Normaliser

The normaliser component is responsible for taking a XenaInputSource and transforming it into an XML file. A normaliser should extend the abstract class AbstractNormaliser.

Type

The XenaType object is used to associate a type with a normaliser. A single normaliser may normalise multiple types, but each type should correspond to a specific normaliser.

DeNormaliser

The denormaliser component is responsible for taking a normalised data object, and transforming it back into a normal file.

MetaDataWrapper

The metadata wrapper component wraps the normalised data with XML that contains meta information for the archived data object. This XML includes such things as the source id, checksums and other meta information. A wrapper extends the AbstractMetaDataWrapper.

Guesser

The guesser component of Xena is responsible for ascertaining the type of a given XenaInputSource. In order to do this, for each Xena Type there is a corresponding guesser, which creates a Xena Guess object. Each Xena Guess object consists of a Xena Type and a number of attributes. The attributes are used by the Guesser to find the most likely type for the given XenaInputSource. Attributes are weighted so as to allow accurate guessing to be undertaken. The following attributes are currently included in the Xena Guess object:

  • MIME Type
  • File Extension
  • Magic number in the file header
  • Data in the body of the file
  • possibility the file is of the current type
  • Xena is certain the file is of the current type
  • priority of the current guesser.

By default, the values of the attributes, other than the priority of the guesser, are set to ‘Unknown’. Each guesser analyses the input source, and sets the attributes as required.

For example, in the case of the JPEG guesser, if it receives a XenaInputSource with the correct extension, the correct magic number in the header, and the data in the file appears to be a valid JPEG, then the guesser would set the file extension, magic number, data and possible attributes to ‘true’. All others would be left alone. Based on this the Guesser would surmise that this XenaInputSource is indeed a JPEG. This could be overridden only if another Guesser returned the same results with a higher priority, or a guesser returned a guess with the certain attribute set.

Conversely, if the JPEG Guesser received a file that contained the incorrect header (ie no magic number) the JPEG could set possible to false, and the guess would be ignored – JPEG would be ruled out as the type of this XenaInputSource. The guessed type for a given XenaInputSource can still be overridden by specifying the normaliser to use when attempting to normalise the XenaInputSource.

View

The view component is responsible for displaying normalised files.

In order to view a normalised object, Xena must first find the appropriate viewer. This is done by taking the outermost tag from the Xena file and obtaining the viewer that is responsible for that particular tag.

To view a file, Xena instantiates a XenaView object. The XenaView object has two important components to it:

  • JPanel
  • ContentHandler.

The JPanel is used to actually display the Xena file, and the ContentHandler parses the XML of the normalised file and add components to the JPanel. In order to display a given normalised file, an appropriate viewer is instantiated, then an XML parser is instantiated and the content handler for XML parser is set to that of the viewer. The normalised file is then parsed, and the content handler performs the necessary actions to display the file.

For example, in the case of the plaintext viewer, when the viewer is instantiated, it creates a JPanel, adds a text area component to the JPanel, then the ContentHandler adds the preserved text to the text area.


Related

Wiki: About_plugins
Wiki: Main_Page