JAX - A JAVA AGENT-X CLIENT TOOLKIT
===================================

Copyright (c) 2000 Technical University of Braunschweig.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; see the file COPYING.  If not, write to
the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.

@(#) $Id: README,v 1.9 2001/05/10 16:54:46 strauss Exp $

JAX is a Java package that provides classes to implement Java AgentX
(RFC 2741) sub-agents. It is designed to allow easy integration with
existent Java code without requiring much knowledge on SNMP.

Although JAX has been initiated within the Jasmin project to give
distributed scripts running in an Jasmin agent the capability to
provide new managed objects, JAX is not concerned with the Script-MIB.

Managed objects can be implemented by compiling a usual SMI MIB module
file to Java classes using the smidump tool which is part of the
libsmi software distribution. You need version 0.2.14 of libsmi.
Later version may be work as well.


MANIFEST
========

README          this file
COPYING         the JAX license terms (GPL)
Makefile	the Makefile to build the code on UNIX systems
jax/		the sources of the JAX package classes
examples/
  ping/		a simple MIB example
  jigsaw/	patch to make Jigsaw support the WWW-MIB using JAX
doc/
  paper.ps	a paper that describes the JAX toolkit
  jax.eps	PostScript UML class diagram of the JAX architecture
  jax.dia	Dia source file of the class diagram


BUILDING JAX
============

JAX consists of pure Java code. It can be compiled and packaged as
any other Java code with your favorite Java development environment.
On UNIX systems you might want to use the supplied Makefile:

	$ make

will compile the `jax' package's classes and build the `jax.jar'
package archive that has to be added to the classpath of any JAX
application that you will build and run.


WRITING JAX SUB-AGENTS USING THE LIBSMI MIB COMPILER
====================================================

Building a JAX sub-agent means writing a set of classes that represent
MIB objects. These classes do not have to be written from scratch. You
can use a MIB compiler that reads an SMI MIB file and creates JAX
compliant Java source files which can then be extended to make the
objects behave as expected. This MIB compiler is not part of JAX
itself. Instead it is part of the libsmi software distribution, that
is also freely available. Please get at least version 0.2.5 of libsmi
and install it as described in the libsmi README file:

	http://www.ibr.cs.tu-bs.de/projects/libsmi/
	ftp://ftp.ibr.cs.tu-bs.de/local/libsmi/


EXAMPLES
========

Two examples are included in this package. The first one is a very simple
MIB implementation with all its required source files included. The second
one is more of a real world example: it adds WWW-MIB support to the W3C
Jigsaw Web server and is supplied as a patch against the original Jigsaw
2.1.1 sources that can be retrieved from

	http://www.w3.org/Jigsaw/

After unpacking the archive apply the patch:

	$ patch -p0 < jigsaw.patch

then go to the Jigsaw directory and read the the file README.JAX.
NOTE: Since Jax 0.0.10, the Jigsaw example is slightly outdated. It
does not catch some exceptions thrown by some classes of the 0.0.10
jax package.

To try out the simple example, look at the supplied TUBS-IBR-PING-MIB
example in the examples/ping/ directory. It is an SMIv2 module that
defines some sample objects. The smidump tool which is part of the
libsmi software distribution can be used to compile this MIB to JAX
conformant Java classes that represent the MIB scalar groups, tables,
and notifications. If libsmi (version 0.2.5 or higher) is installed
properly on your system, type:

	$ smidump -f jax ./TUBS-IBR-PING-MIB

This creates some Java source files, if they do not yet exist:

PingEntry.java		An entry of the PING-MIB::pingEntry row.
PingEntryImpl.java	Inherited from PingEntry. To be extended
			so that it implements the objects of the row.
PingNoResponse.java	A PING-MIB::noResponse notification.
PingStatistics.java	The group of scalars under PING-MIB::pingStatistics.
PingStatisticsImpl.java Inherited from PingStatistics. To be extended
			so that it implements the scalar objects.
PingTable.java		The PING-MIB::pingTable.

Note that usually only the *Impl classes are intended to be extended
manually so that they implement the MIB objects.

Finally PingTest.java represents a simple example of an JAX main
applicaton that connects to an AgentX master agent, instantiates and
registers a PingTable, some rows in this table, the scalar group
PingStatisticsImpl, and a PingNoResponse notification. Then it throws
the PingNoResponse once, waits for 90 seconds and finally unregisters
its subtree from the master agents and quits.

To compile these source files you may simply compile the PingTest.java
file which implicitly compiles all the other classes:

	$ javac -classpath ../../jax.jar:. PingTest.java

To run the sub-agent you have to have a running master agent accepting
AgentX connections on a TCP socket, e.g. the NET-SNMP 4.2 AgentX master.
The you can start the sub-agent:

	$ java -classpath ../../jax.jar:. PingTest [master [master-port]]

That's it. If you encounter any problems, please check whether your
AgentX master works as expected and look at the Makefile. It contains
some targets to build and run the TUBS-IBR-PING-MIB example.

To get familiar with the code of this example, you should

1. read the TUBS-IBR-PING-MIB to understand which objects shall be
   implemented and how they should behave,
2. read the main program PingTest.java to understand how to write the
   main sub-agent code, e.g. for instrumenting existent applications,
3. read the PingStatisticsImpl.java class to understand how to implement
   scalar objects.
4. read the PingEntryImpl.java class to understand how to implement
   objects of a table row. How rows are created during runtime can be
   seen in the main programm PingTest.java.


Good Luck!