Getting Started with Notio

Last Modified: 2001/07/05
This document contains instructions on how to try out Notio and start programming with it.

Contents

How To Use Notio

Notio is not an application or tool. It is a programming API for developing applications and tools. Therefore, there is no way to simply "run" Notio. However, there are some examples and tests that come with Notio that you can try out and use as guides to developing your own programs.

Installing and Setting Up Notio

In order to try Notio's various examples or to develop your own programs with it, you must let the Java Virtual Machine and compiler know whether the Notio classes may be found. There are couple of ways to do this and it depends partially on which version of Java you are using. Notio's classes are bundled into a JAR file, a type of archive used by Java tools, called "Notio.jar". The advice below assumes that will be using the JAR file. Alternately, you can unpack the JAR file and use the .class files in their various directories.

Source Code and Packages

The source code for the entire Notio reference implementation can be found in the source code archive which is provided in a variety of archive formats (NotioSrc.zip, NotioSrc.tar.gz, or NotioSrc.jar). Unpacking any of these archives will give the following directory structure: Each of these corresponds to a Java package.
notio
This package is the essential Notio API. Strictly speaking, none of the other packages are required. It contains everything needed to construct and operate on graphs.
notio.demos
This package contains some demonstrations in the form of GUI applets. These are probably not a good starting point for example code and are chiefly used to demonstrate Notio on the web.
notio.examples
This package contains well-documented example code and is the best starting point for people interested in developing applications with Notio.
notio.test
This package contains a test suite used to monitor changes to Notio in order to prevent regressions and maintain quality.
notio.translators
This package is probably the second most useful package in terms of development. It contains components useful for building parsers and generators that plug into the Notio framework. It includes implementations of CGIF and LF translators.

Important Classes

Browsing the API documentation will reveal a large number of classes which can be a little daunting at first. The following is a list of the more important classes to help guide your early investigations:
Graph
Instances of this class represent individual CG's and it provides many useful operations for dealing with CG's.
Concept
The class for concept nodes.
Relation
The class for relation nodes.
ConceptType and RelationType
The classes for individual concept types and relation types.
ConceptTypeHierarchy and RelationTypeHierarchy
The classes for storing hierarchies of types.
Referent
The class for concept referents.
Designator and its subclasses
The class for designators in referents.
CGIFParser and CGIFGenerator
The class for reading and writing CGIF format graphs.
MatchingScheme
The class for describing how a match should be performed.
Most of the other classes are abstractions or components of the above classes, exceptions and errors, or provide little functionality at present.

Running The Examples

The package "notio.examples" contains a set of commented examples that show how to perform several basics tasks using Notio, such as:

The examples can be found in the source code archive in the "examples" subdirectory. You can run these examples but they are most useful as a guide to writing your own programs. The CGIFTranslation and CGStreamTranslation classes are probably the only interesting ones to try out for yourself. These are very similar, the first dealing with single CGIF graphs and the second dealing with a stream of graphs (separated by periods). Both can read from standard input or a file and output to standard output or a file.
The following parses a graph from standard input until terminated (probably with CTRL-D) and then generates that graph back to standard output:
java -cp path-to-jar-file/Notio.jar notio.examples.CGIFTranslation
The following parses a stream of graphs from the specified input file and then generates those graphs back to standard output:
java -cp path-to-jar-file/Notio.jar notio.examples.CGStreamTranslation <input file>
The following parses a stream of graphs from the specified input file and then generates those graphs into the specified output file:
java -cp path-to-jar-file/Notio.jar notio.examples.CGStreamTranslation <input file> <output file>

Running The Tests

Running the test suite can be useful if you start changing the internals of Notio itself. The tests can be run individually by executing the specific class or they can all be run using the TestAllNotio class. A list of tests will be printed along with a PASS or FAIL rating. If the test fails, an explanation will be printed:

java -cp path-to-jar-file/Notio.jar notio.test.TestAllNotio

This package is also useful for developing new tests. Look at the other tests to see how they are constructed. If you build any tests that can be applied to the Notio package, please submit it for inclusion in the distribution, especially if you think you have identified a bug and are reporting it.