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

net.sourceforge.nite.gui.util
Class AbstractCallableTool

java.lang.Object
  extended by net.sourceforge.nite.gui.util.AbstractCallableTool
Direct Known Subclasses:
DACoder, JastCoder, NECoder, TestCoder
public abstract class AbstractCallableTool
extends java.lang.Object

DOCUMENTATION UNDER CONSTRUCTION. NEED HELP? ASK dennisr at hmi dot utwente dot nl
A general abstract class that implements a lot of the default support for annotation tools. It is targeted at observation-related callable tools such as a dialogue act coder or named entity coder.

Main functionalities:

The rest of this documentation addresses each point in more detail. At the end a short section goes into even more detail regarding implementation issues for new tools that subclass this AbstractCallableTool class.

Using an existing tool implementation in a corpus

This part of the documentation should maybe be put somewhere else...

Global Metadatafile entry

Example for dialogue act coder: 
        <callable-program description="Dialogue Act Annotation" name="net.sourceforge.nite.tools.dacoder.DACoder">
            <required-argument name="corpus" type="corpus"/>
            <required-argument name="observation" type="observation"/>
        </callable-program>
toolname (class), corpus and observation are generally a required argument (most annotation tools operate on one recording at a time)

Specific annotators

CallableTool Entry gets one more option: 
            <required-argument name="annotator" type="annotator"/>
If set, annotator is asked for name, and the codings that are annotator specific (e.g. in DACoder this would be the dialogue act file and the adjacency pair file) are loaded especially for that coder and saved in a separate directory. This means that the current coder will not see the data from these layers generated by annotators with other name, and other annotators will not see results of this annotator. This prevents mixup of multiple versions of the same annotation created by different people.
QUESTION: Which layers are loaded/saved separately for this anntoator?
ANSWER: That is dependent on the specific tool subclass. Each implementation of AbstractCallableTool implements a function called initNomAnnotatorSpecificLoads(net.sourceforge.nite.nom.nomwrite.impl.NOMWriteCorpus). E.g. in the DACoder that method is implemented to set exactly those codings to be annotator specific that contain the dialogue acts and the adjacency pairs.

usecvs

CallableTool Entry gets one more option: (not entirely stable yet) 
            <required-argument default="true" name="usecvs"/>
If set, the tool will try, upon startup, to get the latest version of the relevant codings
QUESTION: What is the advantage of this?
ANSWER: Well, this means that the annotator can continue working on the annotations on a different computer tomorrow, without having to worry about copying files etc. He/she alwyas has the latest versions of his/her work available. Furthermore, the corpus manager will also always have access to the latest material.
QUESTION: Which layers get committed TO the server on closing the tool?
ANSWER: Exactly those layers that are 'annotator specific', i.e. generally those layers that are being annotated. (Dialogue acts, emotions, whatever...)
QUESTION: Which layers get updated/copied FROM the server on starting the tool?
ANSWER: Everything. (for now :-) ) (that will change)

configuration of tools for a specific corpus

It is possible to configure one of these tools for a specific corpus. Reasons to do this might be for example the fact that a tool needs to know what the name of a specific layer is (e.g. the DACoder needs to know the name of the layer containing Dialogue Acts). The reader is referred to another section in this documentation that discusses this issue.

Configuration of tools: hardcoded settings and user-configurable settings

Config class, config file; settings that should be changed by corpus developer, settings that may be changed by annotator A MyAbstractCallableTool gets its settings from a corresponding MyAbstractCallableToolConfig, created in a overridden version of 'initConfig()'. This config object is initialized with the name of the metadatafile of the currently loaded corpus. This config object can define any number of convenience methods such as 'getDialogActLayer' or 'getTranscriptionElementName' that return the appropriate values. These values are either hardcoded (e.g. selection strategies in DACoder), or taken from the settings defined in the nxtConfig.xml configuration file.

toolconfig setting in metadata file

CallableTool Entry can get one more option: 
            <required-argument default="myConfigFileName.xml" name="config"/>
If set, the tool will try to load the specified configuration file rather than the default nxtConfig.xml. further to this, the specific corpus and gui-settings within the configuration file can be named with two more required-argument in the CallableTool: 
          <required-argument name="corpus-settings" default="my-corpus-settings-id"/>
          <required-argument name="gui-settings" default="my-gui-settings-id"/>
the first naming the ID of the corpus-settings node in the config file that should be used, the second naming the ID of the gui-settings node.

Default functionalities in this class; how to invoke these functionalities in a SIMPLE subclass

New tool MyCallableTool. needed: main function (show example) 

 The main method for a subclassing tool is probably always the same: simply call
 the constructor and pass any arguments.

    public static void main(String[] args) {
        DACoder mainProg = new DACoder(args);
    }
needed: proper constructor calling a list of functions (show list, explain if each is necessary, optional, how and why) a config object!!!! 

 This method starts with parsing the arguments passed to this tool, after which it calls
 all those useful methods from the superclass that make development of a new tool such an
 easy process.

    public DACoder(String[] args) {
        //* mostly necessary: *
        parseArguments(args); //AbstractCallableTool.parseArguments parses the usual arguments: corpus, observation, annotator, usecvs.
        initConfig(); //cfreate the tool specific configuration class
        initializeCorpus(getCorpusName(),getObservationName(), getAnnotatorName()); //initialize the corpus, given the settings passed as arguments
        setupMainFrame(getConfig().getApplicationName()); //setup a main frame 
        initLnF(); // Look and feel. Can be ignored/left out if you happen to like the default metal look-and-feel
        setupDesktop(); //setup a desktop on which all the windows (media viewer, transcription view, etc) are added

        //* pretty much optional: *
        setupLog(Logger.global, 530, 535, 465, 90); //a logging window, useful for giving feedback to the user
        setupMediaPlayer(695,15,300,400); //a mediaplayer: necessary if you want video or audio players synchronized to the transcription view
        setupTranscriptionView(15,15,500,600); //one of the most important elements for many tools: a view of the transcription. Highly customizable in the methods initTranscriptionView and refreshTranscriptionView.
        setupSearch(); //search functinoality can be included by default in all subclassing tools. Search results can be highlighted in the transcription view.
        setupActions();
        setupMenus();

        //* setup any tool specific extras... *

    } 

 The config method creates a configuration object specific for this subclass.
 More information on this configuration stuff can be found below.
    protected void initConfig() {
        config = new DACoderConfig();
    }
The documentation of the methods called in the above example constructor should help a lot in deciding whether (and how) to use them. In many cases the utility methods make some asssumptions about what has been called before (e.g. the setupVideo should be called AFTER the corpus has been initialized /loaded etc). Keep track of this by reading javadoc! needed: config class / config file settings. See other section for this.

Subclassing this AbstractCallableTool: more details

What are the most usual functions to override and extend? setupMenus, setupActions, initTranscriptionView, some setupToolSpecific method for a few extra panels and buttons...

Author:
Dennis Reidsma, UTwente

Field Summary
static java.lang.String EXIT_ACTION
          Exit action: Exit application.
static java.lang.String HELP_ACTION
          Show help.
static java.lang.String PRINT_NTV_ACTION
          Print action: print the NTranscriptionView.
static java.lang.String REFRESH_NTV_ACTION
          Refresh action: refresh the NTranscriptionView.
static java.lang.String SAVE_ACTION
          Save action: Save corpus.
static java.lang.String SEARCH_ACTION
          Show searchwindow.
 
Constructor Summary
AbstractCallableTool()
           
 
Method Summary
 javax.swing.ActionMap getActionMap()
          See ntv attribute.
 java.lang.String getAnnotatorName()
           
 Clock getClock()
           
 ClockFace getClockFace()
          Returns the clockface of this class.
 AbstractCallableToolConfig getConfig()
           
 java.lang.String getConfigFileName()
           
 NOMWriteCorpus getCorpus()
           
 java.lang.String getCorpusName()
           
 java.lang.String getCorpusSettingsName()
           
 java.lang.String getGUISettingsName()
           
 NiteMetaData getMetaData()
           
 NTranscriptionView getNTV()
          Returns the transcription view, if it has already been created by a call to setupTranscriptionView().
 java.lang.String getObservationName()
           
 QueryHandler getQueryHandler()
           
 void initTranscriptionViewSettings()
          Initializes the settings of the transcriptionView.
 void refreshTranscriptionView()
          Refresh the transcriptionView.
 java.util.List search(java.lang.String query)
           
 boolean useCVS()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

REFRESH_NTV_ACTION

public static final java.lang.String REFRESH_NTV_ACTION
Refresh action: refresh the NTranscriptionView. See ntv attribute. Doesn't exist if no NTV initialized when actmap was created!

See Also:
Constant Field Values

PRINT_NTV_ACTION

public static final java.lang.String PRINT_NTV_ACTION
Print action: print the NTranscriptionView. See ntv attribute. Doesn't exist if no NTV initialized when actmap was created!

See Also:
Constant Field Values

EXIT_ACTION

public static final java.lang.String EXIT_ACTION
Exit action: Exit application. Check for saved changes! Also causes the CVS commit/checkin, if usecvs true was specified at tool startup.

See Also:
Constant Field Values

SAVE_ACTION

public static final java.lang.String SAVE_ACTION
Save action: Save corpus.

See Also:
Constant Field Values

HELP_ACTION

public static final java.lang.String HELP_ACTION
Show help.

See Also:
Constant Field Values

SEARCH_ACTION

public static final java.lang.String SEARCH_ACTION
Show searchwindow.

See Also:
Constant Field Values
Constructor Detail

AbstractCallableTool

public AbstractCallableTool()
Method Detail

getConfig

public AbstractCallableToolConfig getConfig()

getCorpusName

public java.lang.String getCorpusName()

getObservationName

public java.lang.String getObservationName()

getAnnotatorName

public java.lang.String getAnnotatorName()

useCVS

public boolean useCVS()

getConfigFileName

public java.lang.String getConfigFileName()

getCorpusSettingsName

public java.lang.String getCorpusSettingsName()

getGUISettingsName

public java.lang.String getGUISettingsName()

getCorpus

public NOMWriteCorpus getCorpus()

getMetaData

public NiteMetaData getMetaData()

getClock

public Clock getClock()

getClockFace

public ClockFace getClockFace()
Returns the clockface of this class. A clockface is the 'play control panel' for the video and audio, and in this tool for the virtual meeting animation as well. Before you initialize this, you must have at least a mainframe, a desktop and an initialized corpus.

getNTV

public NTranscriptionView getNTV()
Returns the transcription view, if it has already been created by a call to setupTranscriptionView().

initTranscriptionViewSettings

public void initTranscriptionViewSettings()
Initializes the settings of the transcriptionView. This method does NOT fill the contents of the view. The contents are filled in refreshTranscriptionView. This methods will be overriden by the implementations.

WHAT SHOULD BE INITIALIZED? See also new config classes

refreshTranscriptionView

public void refreshTranscriptionView()
Refresh the transcriptionView. This method does NOT change the settings of the view, it merely clears the contents and redisplays the transcription segments and the annotation elements. The view settings are changed in initTranscriptionViewSettings. May be overriden, but default behaviour is OK for most. Default: display all segments of type config.getSegmentationElementName() and display all annotation element of all types in config.getDisplayedAnnotationNames().

search

public java.util.List search(java.lang.String query)

getQueryHandler

public QueryHandler getQueryHandler()

getActionMap

public javax.swing.ActionMap getActionMap()
See ntv attribute.

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