net.sourceforge.nite.tools.videolabeler
Class Document

java.lang.Object
  java.util.Observable
      net.sourceforge.nite.tools.videolabeler.Document

public class Document
extends java.util.Observable

A document is a global singleton object. Before it is used it should be created with createInstance(). From then on the same document can be retrieved with getInstance().

The document makes use of the NITE XML Toolkit. It is assumed that you are familiar with the concepts of this toolkit. A document is created with the path to a metadata file, the name of an observation and the name of an annotator. The metadata and observation data for the specified annotator will be read into this document object. The metadata can later be retrieved with getMetaData() and the observation is retrieved with getObservation().

There are three base methods to obtain the available agents, layers and signals from the metadata. These methods are getAgents(), getLayers() and getSignals(). The document only returns layers for which there is a layerinfo element in the configuration file.

The only possible document changes are creating, adding and deleting annotations. The respective methods are createAnnotation(), insertAnnotation and deleteAnnotation(). These methods ensure that the annotations do not overlap. If the GUI setting makeContinuous is true, it is also ensured that the annotations remain continuous, i.e. there are no gaps between them.

The document is Observable. Observers (see Observer can register themselves with the document to be notified of any changes. When the document notifies an observer of a change, it will pass an argument, which is a List that consists of two Double objects. The first one contains a start time, the second an end time. The document changed between that start and end time.

The document is saved with save(). To check whether a document has been saved and show a prompt if not, use checkSave().

Method Summary

boolean	checkSave() Checks whether the document has been saved.
NOMWriteElement	createAnnotation(java.lang.String code, double startTime, NAgent agent) Creates a new annotation for the specified code name, start time and agent.
static Document	createInstance(java.lang.String metadata, java.lang.String observation, java.lang.String annotator) Initialises the singleton document.
void	deleteAnnotation(AnnotationLayer layer, NOMObjectModelElement annotation) Deletes an annotation from the corpus.
java.util.List	getAgents() Returns a list with the available agents.
Clock	getClock() Returns the clock for this document.
NOMWriteCorpus	getCorpus() Returns the corpus.
static Document	getInstance() Returns the singleton document.
java.util.List	getLayers() Returns a list with the available annotation layers.
NMetaData	getMetaData() Returns the metadata.
NObservation	getObservation() Returns the observation.
java.util.List	getSignals() Returns a list with the available signals.
void	insertAnnotation(AnnotationLayer layer, NOMWriteElement annotation) Inserts a new annotation into the corpus.
void	notifyObservers(double start, double end) Notifies all observers that the document has changed between the specified start and end time.
void	save() Saves the document (metadata and corpus).
java.util.List	searchAnnotations(java.lang.String query) Performs a search in the corpus.

Methods inherited from class java.util.Observable

addObserver, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers

Methods inherited from class java.lang.Object

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

Method Detail

createInstance

public static Document createInstance(java.lang.String metadata,
                                      java.lang.String observation,
                                      java.lang.String annotator)
                               throws NiteMetaException,
                                      NOMException

Initialises the singleton document. This method reads the metadata from the specified metadata file and the data for the specified observation into the document.

If the singleton document has already been initialised, this method does not create a new document, but simple returns the existing singleton document.

Parameters:

metadata - the path to the metadata file

observation - the name of the observation

Returns:

the singleton document

Throws:

NiteMetaException - if the metadata could not be loaded

NOMException - if the observation data could not be loaded

getInstance

public static Document getInstance()

Returns the singleton document. The document should have been initialised first with createInstance(). If the document has not been initialised yet, this method returns null.

Returns:

the singleton document or null

getCorpus

public NOMWriteCorpus getCorpus()

Returns the corpus. Normally the corpus should not be edited outside this class. The methods createAnnotation, insertAnnotation and deleteAnnotation ensure that annotations remain non-overlapping and continuous, and that observers are notified.

Returns:

the corpus

getMetaData

public NMetaData getMetaData()

Returns the metadata.

Returns:

the metadata

getObservation

public NObservation getObservation()

Returns the observation.

Returns:

the observation

getAgents

public java.util.List getAgents()

Returns a list with the available agents. The objects in the list are instances of NAgent.

Returns:

a list with the available agents

getClock

public Clock getClock()

Returns the clock for this document.

Returns:

the clock

getLayers

public java.util.List getLayers()

Returns a list with the available annotation layers. This method iterates through the list of all time-aligned layers defined in the metadata. For each layer it is checked whether there is a layerinfo element in the configuration file (see CSLConfig.getLayerInfo()). If so, the AnnotationLayerFactory is used to create an annotation layer (instance of AnnotationLayer). This method returns a list of those annotation layers. If an error occurs, a message is printed to standard output.

Returns:

a list with the available annotation layers (instances of AnnotationLayer)

getSignals

public java.util.List getSignals()

Returns a list with the available signals. The objects in the list are instances of NSignal.

Returns:

a list with the available signals

searchAnnotations

public java.util.List searchAnnotations(java.lang.String query)
                                 throws java.lang.Throwable

Performs a search in the corpus. This method takes a query in the NITE Query Language. It should specify only one variable for the search results. This method returns a simple list of annotations (instances of NOMElement) rather than the more complex result of Engine.search(). The annotations will be sorted on their start times.

Parameters:

query - a query in the NITE Query Language

Returns:

a sorted list of annotations

Throws:

java.lang.Throwable - if an error occurs while searching the corpus

notifyObservers

public void notifyObservers(double start,
                            double end)

Notifies all observers that the document has changed between the specified start and end time.

createAnnotation

public NOMWriteElement createAnnotation(java.lang.String code,
                                        double startTime,
                                        NAgent agent)
                                 throws NOMException

Creates a new annotation for the specified code name, start time and agent. The annotation without an end time (end time is Double.NaN) is added to the corpus. When the end time is set, call insertAnnotation. If an error occurs, this method throws an exception and the document won't be changed.

Parameters:

code - the code name

startTime - the start time

agent - the agent

Returns:

the new annotation

Throws:

NOMException - if an error occurs

insertAnnotation

public void insertAnnotation(AnnotationLayer layer,
                             NOMWriteElement annotation)
                      throws java.lang.Throwable

Inserts a new annotation into the corpus. The annotation must have been created with createAnnotation(). The annotation must have a valid start time and end time! This method does not really add the annotation, as this was already done in createAnnotation(). This method only enforces some constraints as described below.

Because the annotations cannot overlap, it may be necessary to make space for the new annotation by deleting (parts of) existing annotations in the period between the specified start and end time. This method ensures that annotations will not overlap.

If CSLConfig.makeContinuous() returns true, this method also ensures that there are no gaps in the time line. This would happen if the start time of the new annotation is greater than the end time of the previous annotation, or if the end time of the new annotation is less than the start time of the next annotation. In these cases, the start or end time of the new annotation is changed so the annotation is connected to the previous or next annotation.

As a result there may be two annotations with the same target next to each other. In that case the annotations are merged. Note therefore that the specified annotation may be edited or deleted altogether!

DR:05.17.2005 merging made dependent on gui config var 'merge'

If makeContinuous is false, this method will execute one corpus search. If makeContinuous is true, it will execute three corpus searches.

Parameters:

layer - the annotation layer

annotation - the annotation to be inserted

Throws:

java.lang.Throwable - if the annotation cannot be inserted

deleteAnnotation

public void deleteAnnotation(AnnotationLayer layer,
                             NOMObjectModelElement annotation)
                      throws java.lang.Throwable

Deletes an annotation from the corpus.

If CSLConfig.makeContinuous() returns true, this method tries to fill the resulting space in the time line with the previous or next annotation. If there is a previous annotation, its end time will be set to the end time of the deleted annotation. If there is no previous annotation, but there is a next annotation, its start time will be set to the start time of the deleted annotation.

As a result there may be two annotations with the same target next to each other. In that case the annotations are merged.

If makeContinuous is false and the deleted annotation has a duration greater than zero, this method will perform no corpus search. Otherwise it will perform two corpus searches.

Parameters:

layer - the layer that contains the specified annotation

annotation - the annotation to be deleted

Throws:

NOMException - if an error occurs while merging two annotations

java.lang.Throwable

save

public void save()
          throws NOMException

Saves the document (metadata and corpus).

Throws:

NOMException - if the document could not be saved

checkSave

public boolean checkSave()

Checks whether the document has been saved. If yes, this method returns true. If not, this method shows a dialogue window to ask the user whether the document should be saved. If the user clicks "Yes", the document will be saved and this method returns true. If the user clicks "No", the document will not be saved, but this method still returns true. If the user clicks "Cancel", the document will not be saved and this method returns false.

This method should be called before the application is closed. If this method returns true, the application can be closed.

Returns:

true if the application can be closed (the document was saved or the user does not want to save it), false otherwise