vn
Class EventManager

java.lang.Object
  vn.EventManager

public class EventManager
extends Object

This class contains the method that researchers will modify to extend the Inspector to other natural language processing tasks. This method is:

fireEvent(int, int, String, String, String, Element, Element)

All events that are fired during the scanning of the VerbNet XML files end here. The arguments passed to this method provide the context for the location where the event fired. The information given to this method is:

• Current file
• Current class or subclass
• Simple-text representation of XML element that the event is firing for
• Relevant Element objects from the Java XML DOM that represent the XML element from the file

Thus, the events provide two ways to view the content of the VerbNet XML files: parsing the simple-text representations or examining the Element objects.

The simple-text representation is text that would have printed in the Inspector's normal output mode with full view options enabled (-Vab). In other words, all attributes included in each XML element is embedded in the simple-text representation for that element. The specific representation will vary, but every effort will be made to make sure the representation is consistent from version to version of the Inspector. This is so researcher's parsing routines will not break just because they download a new version of the Inspector code. Utilize the key option (-k) to enumerate all representations used by the Inspector.

The Element object can be accessed and traversed with these methods:

• Element.getAttribute(String)
• Element.getElementsByTagName(String)
• Node.getChildNodes()

Events exist for the majority of elements within the XML files. Events do not fire for XML elements such as <VERB/> or <ADV/> as those are absorbed into the events that fire for <SYNTAX>. Events do not fire for the <SEMANTICS> element as whole but rather for each individual <PRED> element inside. Finally, events fire for two addition "elements" - which are not elements in the XML sense. These are PROGRAM and FILE. This allows for futher control over firing code when needed.

The event system is unaffected by the -V operator. The -V operator just describes which elements should be printed to stdout. All events for all elements still fire. In fact, the only way to prevent the events from firing for a given execution of the Inspector is by using the -e option.

The event system is however affected by the -O operator. The -O limits the XML files that the Inspector scans to a subset of all the files. If supplied, events will only fire for the files scanned. For example, if "-Och,spray" is supplied, only the files spray-9.7.xml and those which begin with "ch" are scanned. Events will only fire for these files.

Finally, a few elements span just a single line in the normal output. These "one-liners" are MEMBER, THEMROLE, EXAMPLE, SYNTAX, and SEMANTIC PRED. Both the 'start' and 'end' events for these elements still fire, but they fire one right after another. In other words, the 'end' event is superfluous and fires just for completeness.

For more information about extending the Inspector, refer to the Extension Guide.

The Inspector is ready for use right out of the box. There is very little to configure. However, these notes (all of which shown on Inspector, Sweeper, and EventManager classes) provide some more logistical details about the software.

NOTE 1: The Inspector is implemented almost entirely with static methods. Text parsing and scanning is a very serial process and the Inspector would only have been made more complicated with a more object-oriented scheme.

NOTE 2: The Inspector produces simple-text representations for frame syntax which are congruent with the representations for frame syntax presented in the Unified Verb Index. The only difference is that the UVI represents noun phrase thematic roles with underline (Agent) and the Inspector represents them with a preceding % sign (%Agent). Look at the UVI's key or the Inspector's key (-k option on command line) for more information.

NOTE 3: Use of the Inspector, either by extension or by insertion into an existing application, requires the entirety of the VerbNet XML files. They may be placed anywhere in relation to the Inspector source code, as the only required argument to the Inspector is this XML input directory path. They can be downloaded here. Finally, the DTD file contained in this download is required to be in the same directory as the XML files (it's already there, just don't remove it).

NOTE 4: This software assumes that the XML files it is processing match the VerbNet DTD. This means that elements appear in the proper order (MEMBERS, THEMROLES, FRAMES, SUBCLASSES) and all tag names are in upper case (i.e. <FRAME>). The files available for download should match the DTD almost 100%.

NOTE 5: This documentation utilizes the terms 'researcher' and 'future developer' so as to reduce confusion as much as possible. A researcher is one who downloads the Inspector source code from the website with the intention of extending it for his or her own purposes, or integrating it into an existing NLP application. A future developer is a member of the University of Colorado team responsible for the Inspector who might modify or enhance it over time. This documentation is written for both parties.

NOTE 6: This Javadoc documentation is not written like a standard public API might be written. First, all private members are displayed here because this is also made to be convenient documentation for future developers. Second, all "See Also" links below actually reference other places in the code that reference or are referenced by the given member. This is in contrast to public API documentation, in which the "See Also" links commonly refer the reader to class members of related or contrasted functionality.

NOTE 7: Although originally written with a few Java 1.5 features, the Inspector was downgraded so as to be compilable with javac 1.4.2. The reason for this was so researchers did not need to download and run Java 1.5 for this software. This software will however work with Java 1.5. If you do not have Java installed on your system, download the most recent release right here. Also, here are links to the 1.4.2 documentation and the 1.5.0 documentation.

Version:

1.0, 2006.10.15

Author:

Derek Trumbo

Field Summary

(package private) static int	EVENT_CLASS Identifies that the event is for a main class.
(package private) static int	EVENT_END Identifies that the event firing corresponds to the end of the element in question.
(package private) static int	EVENT_END_FRAMES Identifies the moment right before another class begins.
(package private) static int	EVENT_EXAMPLE Identifies that the event is for an example.
(package private) static int	EVENT_FILE Identifies that the event is for a single XML file.
(package private) static int	EVENT_FRAME Identifies that the event is for a frame.
(package private) static int	EVENT_MEMBER Identifies that the event is for a single member (verb).
(package private) static int	EVENT_PROGRAM Identifies that the event is for the entire program.
(package private) static int	EVENT_SEMANTIC_PRED Identifies that the event is for a single semantic predicate.
(package private) static int	EVENT_START Identifies that the event firing corresponds to the beginning of the element in question.
(package private) static int	EVENT_SUBCLASS Identifies that the event is for a subclass.
(package private) static int	EVENT_SYNTAX Identifies that the event is for syntax.
(package private) static int	EVENT_THEMROLE Identifies that the event is for a thematic role.
(package private) static int	EVENT_VF_PAIR Identifies that the event is for a verb-frame pair.
private static PrintStream	originalStdOut The original stdout stream reference from the System class.

Constructor Summary

private

EventManager() This constructor is private because the class is not intended to ever be instantiated.

Method Summary

(package private) static void	fireEvent(int type, int startOrEnd, String curFile, String curClass, String text, Element n, Element nExtra) Executes custom code specific to each type of element as they are encountered in the VerbNet XML files.
(package private) static void	fireEventMaybe(int type, int startOrEnd, String curFile, String curClass, String text, Node n, Node nExtra) Fires an event if events are enabled for this execution of the Inspector.

Methods inherited from class java.lang.Object

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

Field Detail

EVENT_START

static final int EVENT_START

Identifies that the event firing corresponds to the beginning of the element in question.

See Also:

fireEvent(int, int, String, String, String, Element, Element), Constant Field Values

EVENT_END

static final int EVENT_END

Identifies that the event firing corresponds to the end of the element in question.

See Also:

fireEvent(int, int, String, String, String, Element, Element), Constant Field Values

EVENT_PROGRAM

static final int EVENT_PROGRAM

Identifies that the event is for the entire program.

See Also:

fireEvent(int, int, String, String, String, Element, Element), Constant Field Values

EVENT_FILE

static final int EVENT_FILE

Identifies that the event is for a single XML file.

See Also:

fireEvent(int, int, String, String, String, Element, Element), Constant Field Values

EVENT_CLASS

static final int EVENT_CLASS

Identifies that the event is for a main class.

See Also:

fireEvent(int, int, String, String, String, Element, Element), Constant Field Values

EVENT_SUBCLASS

static final int EVENT_SUBCLASS

Identifies that the event is for a subclass.

See Also:

fireEvent(int, int, String, String, String, Element, Element), Constant Field Values

EVENT_MEMBER

static final int EVENT_MEMBER

Identifies that the event is for a single member (verb).

See Also:

fireEvent(int, int, String, String, String, Element, Element), Constant Field Values

EVENT_THEMROLE

static final int EVENT_THEMROLE

Identifies that the event is for a thematic role.

See Also:

fireEvent(int, int, String, String, String, Element, Element), Constant Field Values

EVENT_FRAME

static final int EVENT_FRAME

Identifies that the event is for a frame.

See Also:

fireEvent(int, int, String, String, String, Element, Element), Constant Field Values

EVENT_EXAMPLE

static final int EVENT_EXAMPLE

Identifies that the event is for an example.

See Also:

fireEvent(int, int, String, String, String, Element, Element), Constant Field Values

EVENT_SYNTAX

static final int EVENT_SYNTAX

Identifies that the event is for syntax.

See Also:

fireEvent(int, int, String, String, String, Element, Element), Constant Field Values

EVENT_SEMANTIC_PRED

static final int EVENT_SEMANTIC_PRED

Identifies that the event is for a single semantic predicate. There are no events that fire for the SEMANTICS element as a whole, only one for each semantic predicate.

See Also:

fireEvent(int, int, String, String, String, Element, Element), Constant Field Values

EVENT_VF_PAIR

static final int EVENT_VF_PAIR

Identifies that the event is for a verb-frame pair.

See Also:

fireEvent(int, int, String, String, String, Element, Element), Constant Field Values

EVENT_END_FRAMES

static final int EVENT_END_FRAMES

Identifies the moment right before another class begins. This is synonymous with </FRAMES> but not synonymous with end of class. So a special event is needed. This event only has an 'end' event.

See Also:

fireEvent(int, int, String, String, String, Element, Element), Constant Field Values

originalStdOut

private static PrintStream originalStdOut

The original stdout stream reference from the System class. This is saved in the static initializer for this class and exists just in case the stdout stream is reset to a custom file in the fireEvent(int, int, String, String, String, Element, Element). A researcher can use this reference to reset the System class's stdout stream back to the original stream whenever desired.

See Also:

System.out, System.setOut(PrintStream)

Constructor Detail

EventManager

private EventManager()

This constructor is private because the class is not intended to ever be instantiated. The Inspector is a very procedural process and thus all the members are static.

Method Detail

fireEvent

static void fireEvent(int type,
                      int startOrEnd,
                      String curFile,
                      String curClass,
                      String text,
                      Element n,
                      Element nExtra)

Executes custom code specific to each type of element as they are encountered in the VerbNet XML files. This method is made specifically for researchers hoping to either extend the Inspector into a custom VerbNet application or embed VerbNet in an existing application. A researcher would download all the Inspector files, add custom methods either in this class or an external class, and modify this method to call those methods at the appropriate times during XML processing.

There are 11 "elements" for which events fire. The word element in this case is not exactly synonymous with XML elements, since PROGRAM and FILE are also considered elements with respect to Inspector events. The elements are: PROGRAM, FILE, CLASS, SUBCLASS, MEMBER, THEMROLE, FRAME, EXAMPLE, SYNTAX, SEMANTIC PRED, and VF-PAIR. There are two events that fire for each element: 'start' and 'end'. The 'start' event fires when the element is entered and the 'end' event fires when the element is exited.

When the class hierarchy is requested (with -c option), the only elements for which events fire are PROGRAM, CLASS, and SUBCLASS).

The 'start' event for PROGRAM fires if there were no problems with the command line arguments and if neither -? nor -k was specified. This event fires before the header is printed (if not suppressed). The 'end' event for PROGRAM fires if and only if the 'start' event fired. This event fires after the final counts have been printed (if not suppressed).

Six of the elements have 'start' events that fire before all the children elements contained within them and 'end' events that fire after all of their children's events have completed. They are: PROGRAM, FILE, CLASS, SUBCLASS, FRAME, and VF-PAIR.

Five of the elements are considered "one-liners". They span exactly one line in the normal output. Their 'end' events fire immediately after their 'start' events. These 'end' events only fire for completeness. They are: MEMBER, THEMROLE, EXAMPLE, SYNTAX, and SEMANTIC PRED.

Both the simple-text representation and the XML Element object is supplied so as to give the researcher flexibility in how they access the VerbNet data. The text argument (a string) can be parsed or the Element object can be traversed. If using the latter, refer to the following methods:

• Element.getAttribute(String)
• Element.getElementsByTagName(String)
• Node.getChildNodes()

The text argument for all 'end' events is the same as the text argument for the corresponding 'start' events. This is so when an 'end' event fires, one can easily identify the specific element to which the event corresponds. This argument does not include leading spaces regardless of -i operator.

For debugging purposes, all events in the system can be suppressed for a single execution of the Inspector using the -e option. If this option is used, the Inspector acts merely as a VerbNet viewer for that exection. This is so a researcher does not have to write any short-circuit code if they don't want to fire their events temporarily. He or she can just supply an extra option on the command line.

If you are integrating the Inspector into an existing application (as opposed to using it as a stand-alone application) and you desire to utilize the VerbNet viewer aspect of the Inspector and you don't want it to send its output (normal or class hierarchy) to stdout, you can redirect this output to an external file temporarily during the execution of the Inspector. In the 'start' event for PROGRAM, you can insert this line:

    try
    {
       System.setOut( new PrintStream( "file.txt" ) );
    }
    catch( Exception e )
    {
       e.printStackTrace();
    }

You can reset the System class's stdout writer to the original stream in the 'end' event for PROGRAM with:

    System.setOut( originalStdOut );

The variable originalStdOut is a pre-defined class variable that is ready for use.

Parameters:

type - the type of element to which this event corresponds (EVENT_PROGRAM, EVENT_FILE, etc.)

startOrEnd - whether this event is for the beginning of the element or the end of the element (EVENT_START or EVENT_END)

curFile - the name of the file currently being processed (i.e. approve-77.xml). This argument is null for the PROGRAM element.

curClass - the name of the class or subclass currently being processed (i.e. devour-39.4-1). This argument is null for the PROGRAM and FILE elements.

text - the simple-text representation of the element to which this event corresponds. This text is equivalent to the text that would be printed for this element had it been printed by the Inspector under the view options -Vab (full output). For the PROGRAM element, this argument is equal to the concatenation of all the command line elements with spaces.

n - the XML node corresponding to the element being visited. This argument is null for the PROGRAM and FILE elements. For verb-frame pairs, this is the XML node corresponding to the MEMBER element in the verb-frame pair.

nExtra - the XML node corresponding to the FRAME element in the verb-frame pair being visited. This argument is null for all other elements.

fireEventMaybe

static void fireEventMaybe(int type,
                           int startOrEnd,
                           String curFile,
                           String curClass,
                           String text,
                           Node n,
                           Node nExtra)

Fires an event if events are enabled for this execution of the Inspector. This method exists only to implement the "suppress all events" option (-e) of the Inspector. Events are enabled by default. This option must be supplied to prevent them from firing. If the events are not being suppressed, this method simply hands the arguments given to it to the real fireEvent method. It also makes a quick conversion between Nodes and Elements for code simplification purposes only. Do not modify this method.

Parameters:

type - the type of element to which this event corresponds (EVENT_PROGRAM, EVENT_FILE, etc.)

startOrEnd - whether this event is for the beginning of the element or the end of the element (EVENT_START or EVENT_END)

curFile - the name of the file currently being processed (i.e. approve-77.xml). This argument is null for the PROGRAM element.

curClass - the name of the class or subclass currently being processed (i.e. devour-39.4-1). This argument is null for the PROGRAM and FILE elements.

text - the simple-text representation of the element to which this event corresponds. This text is equivalent to the text that would be printed for this element had it been printed by the Inspector under the view options -Vab (full output). For the PROGRAM element, this argument is equal to the concatenation of all the command line elements with spaces.

n - the XML node corresponding to the element being visited. This argument is null for the PROGRAM and FILE elements. For verb-frame pairs, this is the XML node corresponding to the MEMBER element in the verb-frame pair.

nExtra - the XML node corresponding to the FRAME element in the verb-frame pair being visited. This argument is null for all other elements.

See Also:

fireEvent(int, int, String, String, String, Element, Element), Inspector.flSuppressEvents