The PIRL Java Packages


PIRL packages:

Conductor -

	An application to manage procedure pipelines. Includes a
	Reference_Resolver for Database and PVL Parameter reference
	resolution. The Maestro sub-package includes applications for remote
	real-time monitoring and management of Conductors.

Messenger -

	A set of classes for managing synchronous and asynchronous network
	message passing between processes. A class that multiplexes a styled
	text Writer via Messengers is included.

Database -

    A simplified interface for access to, and basic management of,
    relational SQL databases.

PVL -

    The PIRL Parameter Value Language package provides for the input,
    output and manipulation of parameters and their data values. A
    PVL_to_DB class is provided to map PVL Parameter Values into
    Database fields for update or insert operations.

Configuration -

    Management of configuration files using PVL syntax. Configuration
    objects are typically used by application programs.

Strings -

    Character string manipulation capabilities used by the other PIRL
    packages.

Viewers -

    Classes for common capabilities associated with GUI viewers, plus GUI
    viewers associated with other PIRL packages.

Image_Tools -

	Classes for obtaining metadata information from JP2 files, plus an
	ImageInputStream implementation for access to files remotely via an
	HTTP server.

Utilities -

	Support classes for abstract data stream connection, system host
	identification, public-private key authentication, styled text
	writing, numerical ranges, logical to canonical pathname mapping,
	and unit test checking.

The package distribution files are available from the PIRL distribution
site (ftp://pirlftp.lpl.arizona.edu/pub/Java/). All of the packages are
contained in a compiled classes jar file (PIRL.jar) or a source code
tarball (PIRL.tar.gz). Files with -N.N.N version extensions, where N.N.N
is the distribution version, are also available; the files without the
extension are links to the files with the most current version.

A Makefile (using gmake syntax) is included in the source code
distribution that can be used to compile the class files. The tarball
unpacks into a subdirectory named PIRL-N.N.N, where N.N.N is the
distribution version. A link to this directory named PIRL is required to
satisfy Java's dependency on filenames being identical to package/class
names. See the Source code build section, below.

The Apps subdirectory of the distribution directory contains wrapper
scripts for the applications of the PIRL Java Packages. The wrappers,
when installed in users' command PATH, can make executing the
applications, including locating runtime dependencies, as easy as if
the applications were a self-contained executables.

The Configs subdirectory of the distribution directory contains
configuration file templates typically used by various applications.

Note: The distribution files containing the PIRL Java Packages do not
include the third party dependency packages (below) which are necessary
to run various applications. These packages are redistributed on the
PIRL Java Packages distribution site.


Documentation:

The documentation is available online from the
http://PIRL.LPL.Arizona.edu/software/PIRL_Java_Packages/ URL. The
javadoc is distributed in the PIRL-javadoc.tar.gz tarball file. The
source code distribution file (PIRL.tar.gz) contains the javadoc HTML
files in the docs subdirectory.


Third party packages:

Java Components For Mathematics -

	A project at Hobart and William Smith Colleges, Java Components for
	Mathematics (http://math.hws.edu/javamath/) is an effort to develop
	a framework of configurable mathematical software components written
	in the Java programming language. A tarball of the complete version
	1.0 distribution is provided (jcm.tar.gz). However, this is a large
	tarball and only the edu.hws.jcm.data package is used by the PIRL
	software, so a jar file for just this package (jcm_data.jar) is
	provided.

JDBC drivers for MySQL -

	Implementations of the JDBC API for the MySQL (www.mysql.com) and
	PostgreSQL (http://www.postgresql.org) relational database servers.

	The MySQL Connector/J package is deemed to be the official driver by
	MySQL and is definitely to be preferred for its performance,
	features and maintenance support. It is provided in both source
	code tarball (mysql-connector.tar.gz) and compiled classes jar
	(mysql-connector.jar) forms.

	The PostgreSQL JDBC Driver (http://jdbc.postgresql.org) is provided
	in both source code tarball (postgresql-jdbc.tar.gz) and compiled
	classes jar (postgresql-jdbc.jar) forms.

SwingX -

	The SwingLabs SwingX project (http://swinglabs.org) provides GUI
	components that extend various JFC Swing package classes. The
	JXTable class is used by Conductor applications. SwingX is provided
	in distribution kit (swingx.tar.gz) and compiled classes jar
	(swingx.jar) forms.

Commons-CLI -

	The Apache Commons CLI package (http://commons.apache.org/cli/)
	provides command line interface parsing. This package is used by the
	Pipeline_Configuration subpackage of the Conductor package.
	Commons-CLI is provided in both source code zip (commons-cli.zip) and
	compiled classes jar (commons-cli.jar) forms.

JavaMail and JavaBeans Activation Framework -

	The JavaX JavaMail package
	(http://www.oracle.com/technetwork/java/javamail/) provides email
	message sending functionality. This package is used by the Notify
	utility of the Conductor pacakge which also requires the
	JavaBeans Activation Framework
	(http://java.sun.com/products/archive/javabeans/jaf11.html) at
	runtime. JavaMail is provided in
	distribution package (javamail.zip) and compiled classes jar
	(javamail.jar) forms; JavaBeans Activation Framework is provided
	in a distribution package (jaf.zip).

	Note: These packages are only required when Notify must use an
	"unfriendly" email server. They may not be required at all, in which
	case a Notify-simple.java implementation is provided that only uses
	JFC classes and worked fine for many years until a "sophisticated"
	email server was encountered. Simply replace Notify.java with
	Notify-simple.java before compiling the Conductor pacakge to get the
	simple version. N.B.: The pre-built PIRL.jar distribution requires
	the additional packages.
	

System requirements:

A Java 1.5, or greater, version of the Java Virtual Machine (JVM) is
required. The PIRL Java Packages software should function correctly with
just the appropriate JVM and the jars files from the distribution -
PIRL.jar, jcm_data.jar, mysql-connector.jar, postgresql-jdbc.jar and
swingx.jar - installed in the Java extensions directory or located in
the users' CLASSPATH.

As of v2.2.0 of the PIRL Java Packages the Conductor application no
longer requires a patch to the JFC Process class implementation.

The Native_Methods.c file in the Conductor package is used to build a
libNative_Methods dynamic library (see the Source code build section)
that provides the Unix process ID of the JVM which is used to uniquely
identify a Conductor instantiation on a host system. While not necessary
to run Conductor it is recommended.


Source code build:

The source code distribution requires the javac compiler from the Java
Software Development Kit (SDK) to build the class files from the java
files. The third party jars, or their class files, are required
dependencies to build the PIRL Java Packages. Check the definitions of
the dependency variables at the beginning of each Makefile to make
site-specific adjustments for their locations. The javadoc utility is
required to build the documentation files. The GNU make (gmake) utility is
required to use the Makefiles included in each package directory. The
Build subdirectory contains a Makefile that will build all the packages
(gmake all) and the javadoc HTML docs files (gmake docs), and each package
directory contains a Makefile that will build just the package.

The GNU C compiler (gcc) is used by the Conductor/Makefile to build the
libNative_Methods dynamic library. The JNI support in the SDK will also
be needed to build the library. The library that is built will be
located in a Conductor subdirectory named <OS>.<platform> where <OS> is
the name of the operating system (e.g. Darwin, Linux or SunOS) and
<platform> is the name of the machine architecture (e.g. i386, powerpc,
x86_64 or sparc). The library must be installed at a location that can
be found at Conductor runtime by the JVM. Typical system locations for
the library are /usr/lib or /usr/local/lib, or it can be located in any
path listed in the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Apple OS X)
environment variable. if not in a standard system location, the
LD_LIBRARY_PATH (DYLD_LIBRARY_PATH for Mac OS X systems) environment
variable can be set to include the pathname to the installation
location.


Copyright:

The PIRL Java Packages are  Copyright (C) 2001 - 2012  Arizona Board of
Regents on behalf of the Planetary Image Research Laboratory, Lunar and
Planetary Laboratory at the University of Arizona. They are distributed
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation. A copy of this license should be included
with the distributed files. If not, see <http://www.gnu.org/licenses/>.

The PIRL Java Packages are is distributed in the hope that they will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.


Contact:

Comments, questions and contributions of code or corrections regarding
the PIRL Java Packages may be sent to the author:

Bradford Castalia                       Castalia@Arizona.edu
Principal Systems Analyst               520-621-2197
Planetary Image Research Laboratory     Department of Planetary Sciences
University of Arizona                   Space Sciences Bldg.
1541 E. University Blvd.                Tucson, Arizona  85721-0063


1.9 2012/04/16 05:51:17
