NAME
Javacyc.java

ABSTRACT
A Java interface for Pathway Tools software. Pathway Tools software
needs to run a special socket server program for Javacyc to work.

SYNOPSIS
Javacyc is a Java interface for Pathway Tools software.
	Javacyc cyc = new Javacyc("ARA");
	ArrayList pathways = cyc.allPathways();

VERSION
Version 0.2 August 1, 2004

HISTORY
Version History:
	0.1 June 6, 2003 initial version
	0.2 August 1, 2004 fixed a socket close bug in the C code

INSTALLATION
The Javacyc class uses native methods in order to access AF_UNIX sockets for
interprocess communication.  Javacyc can be installed by using the included
makefile.

If you choose not to use the makefile, below is an example of how to 
compile Javacyc.  The example assumes that the path to the Java directory is
/usr/java and that the platform is solaris:
	javac UnixDomainSocket.java
	javah UnixDomainSocket
	gcc -c -fPIC -I/usr/java/include -I/usr/java/include/solaris/ UnixDomainSoceket.c
	gcc -shared -o libunixdomainsocket.so UnixDomainSocket.o
	javac Javacyc.java

IMPORTANT NOTE:  In order for Javacyc to work, ensure that the environment
variable, LD_LIBRARY_PATH, includes the directory where libunixdomainsocket.so
is located.

DESCRIPTION
Javacyc is a Java class for accessing internal Pathway Tools functions.
For a description of what the individual functions do, please refer to the
Pathway Tools documentation at http://bioinformatics.ai.sri.com/ptools .

Note that optional parameters of all functions are not supported in Javacyc.

Limitations:
Javacyc does not implement GFP objects in Java.  It sends snippets of code to 
Pathway Tools through a socket connection.  Only one connection may be opened
at any given time.  The returned values are of type boolean, String, ArrayList,
and ArrayLists that contain ArrayLists for functions that return multiple
lists.  A list of available functions is given below.

GFP functions: (More information on these functions can be found at:
http://www.ai.sri.com/~gfp/spec/paper/node63.html )
	get-slot-values
	get-slot-value
	get-class-slot-slotvalue
	get-class-all-instances
	instance-all-instance-of-p
	member-slot-value-p
	current-kb
	put-slot-values
	put-slot-value
	add-slot-value
	replace-slot-value
	remove-slot-value
	coercible-to-frame-p
	class-all-type-of-p
	get-instance-direct-types
	get-instance-all-types
	get-frame-slots
	put-instance-types
	save-kb
	revert-kb
	find-indexed-frame

Pathway Tools functions: (More information on these functions can be found at
http://bioinformatics.ai.sri.com/ptools/ptools-fns.html)
	select-organism
	all-pathways
	all-orgs
	all-rxns
	genes-of-reaction
	substrates-of-reaction
	products-of-reaction
	enzymes-of-reaction
	reaction-reactants-and-products
	get-predecessors
	get-successors
	get-reaction-list
	genes-of-pathway
	enzymes-of-pathway
	compounds-of-pathway
	substrates-of-pathway
	all-transcription-factors
	transcription-factor?
	all-cofactors
	all-modulators
	monomers-of-protein
	components-of-protein
	genes-of-protein
	reactions-of-enzyme
	enzyme?
	transporter?
	containers-of
	modified-forms
	modified-containers
	top-containers
	reactions-of-protein
	regulon-of-protein
	transcription-units-of-protein
	regulator-proteins-of-transcription-unit
	enzymes-of-gene
	all-products-of-gene
	reactions-of-gene
	pathways-of-gene
	chromosome-of-gene
	transcription-units-of-gene
	transcription-unit-promoter
	transcription-unit-genes
	transcription-unit-binding-sites
	transcription-unit-transcription-factors
	transcription-unit-terminators
	all-transported-chemicals
	reactions-of-compounds
	full-enzyme-name
	enzyme-activity-name

EXAMPLE
/**
   A program to test Javacyc.
*/

import java.util.ArrayList;
import java.io.*;

public class JavacycTest
{
    public static void printLists(ArrayList list)
    {
	for (int i = 0; i < list.size(); i++)
	{
	    Object obj = list.get(i);
	    if (obj instanceof String)
	    {
		String str = (String)obj;
		System.out.println(str);
	    }
	    else if (obj instanceof ArrayList)
	    {
		System.out.println("*begin inner list*");
		ArrayList aList = (ArrayList)obj;
		printLists(aList);
		System.out.println("*end inner list*");
	    }
	    else
	    {
		System.out.println("WARNING THIS SHOULD NOT HAPPEN!");
	    }
	}
    }

    public static void main(String[] args) throws IOException
    {
	Javacyc cyc = new Javacyc("ARA");
	BufferedReader in = new BufferedReader(
	   new InputStreamReader(System.in));

	// test a function that returns a boolean
        System.out.println("Testing a function that returns a boolean: "
			   + "coercible-to-frame-p");
	System.out.print("Enter a value for frame: ");
	String thing = in.readLine();
	boolean result1 = cyc.coercibleToFrameP(thing);
	if (result1)
	{
	    System.out.println("The result: true\n");
	}
	else
	{
	    System.out.println("The result: false\n");
	}

	// test a function that returns a string
	System.out.println("Testing a function that returns a string: "
			   + "full-enzyme-name");
	System.out.print("Enter a value for enzyme: ");
	String enzyme = in.readLine();
	String result2 = cyc.fullEnzymeName(enzyme);
	System.out.println("The result: " + result2 +"\n");

	// test a function that returns an ArrayList
	System.out.println("Testing a function that returns an ArrayList: "
			   + "genes-of-pathway 'PWY-581");
	ArrayList result3 = cyc.genesOfPathway("PWY-581");
	System.out.println("The returned values: ");
	for (int i = 0; i < result3.size(); i++)
	{
	    String rxn = (String)result3.get(i);
	    System.out.println(rxn);
	}

	// test a function that returns multiple lists
	System.out.println("\nTesting a function that returns multiple"
			   + " lists: reaction-reactants-and-products");
	System.out.print("Enter a value for reaction: ");
	String rxn = in.readLine();
	System.out.print("Enter a value for pathway: ");
	String pwy = in.readLine();
	ArrayList result4 = cyc.reactionReactantsAndProducts(rxn, pwy);
	System.out.println("The returned values: ");
	printLists(result4);
    }
}

TROUBLESHOOTING
Please send bug reports and comments to curator@arabidopsis.org

LICENSE
Javacyc, a Java interface for Pathway Tools software
Copyright (c) 2003 by Thomas Yan, The Arabidopsis Information Resource (TAIR)
and the Carnegie Institution of Washingtion.

This library is free software; you can redistribute it and/or
modify it under the terms of version 2.1 of the GNU Lesser General 
Public License as published by the Free Software Foundation.

This library 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
Lesser General Public License for more details:

http://www.opensource.org/licenses/lgpl-license.html
http://www.gnu.org/copyleft/lesser.html

To obtain a written copy of the GNU Lesser General Public License,
please write to the Free Software Foundation, Inc., 59 Temple Place, 
Suite 330, Boston, MA  02111-1307 USA


Javacyc uses native methods to access AF_UNIX sockets provided by J-BUDS, 
which was released by Echogent Systems under the GNU Lesser General Public 
License.  See the JBUDS_COPYRIGHT for details.

AUTHOR
Thomas Yan

ACKNOWLEDGMENTS
Many thanks to Lukas Mueller and Danny Yoo.