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
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.
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.
- Add to CLASSPATH (Java 1.1 or higher)
- Java tools recognize and use an environment variable called
"CLASSPATH".
- CLASSPATH is a list of directories and JAR files that will be searched
whenever a Java class is used.
- You may already have a CLASSPATH set in your environment. The
following commands will add Notio.jar to that path. The command can be
typed at each session or added to your startup procedure (e.g.
AUTOEXEC.BAT in DOS/Windows).
- Note that colons are used in some cases and semi-colons in others.
- DOS/Windows:
set CLASSPATH=%CLASSPATH%;path-to-jar-file\Notio.jar
- Unix sh or bash:
export CLASSPATH=$CLASSPATH:path-to-jar-file/Notio.jar
- Indicate on command line (Java 1.2 or higher)
- Compiling classes that use the Notio classes:
javac -classpath path-to-jar-file/Notio.jar <files to compile>
- Running programs that use the Notio classes:
java -cp path-to-jar-file/Notio.jar <class to run>
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:
- notio
- demos
- examples
- test
- translators
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.
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.
The package "notio.examples" contains a set of commented examples that show
how to perform several basics tasks using Notio, such as:
- Constructing a simple graph piece by piece (SimpleGraphBuild.java)
- Constructing a type hierarchy (TypeBuild.java)
- Matching two graphs (MatchTwoGraphs.java)
- Parsing and generating graphs in CGIF format (CGIFTranslation.java and
CGStreamTranslation.java)
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 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.