               README for NCSA HDF Java Products Distribution
               ----------------------------------------------

***************************************************************************
  CONTENTS
  --------
  1. Contents of this release

  2. Obtaining the latest version

  3. Installing the HDF Java API and JHV
  3.1 Supported Platforms
  3.2 Software Requirements

  3.3 General Configuration/Installation - Unix
  3.3.1 Overview
  3.3.2 Layout of distribution
  3.3.3 Layout of configuration files
  3.4.4 Running configure
  3.4.5 Compiling, Testing and Installing

  3.5 Installation Location

  4 Platform-specific Notes
  4.1 Windows '95 or Windows NT
  4.2 HPUX
  4.3 Linux
  4.4 Other platforms
  4.4.1  Compiling for a new platform

  5. Man pages (javadoc)

  6. Documentation and Release Notes

  7. HELP

*****************************************************************************


1.  Contents of this release
    ========================

This package contains the complete Java interface for the
HDF 4.1r2 library, and the Java HDF Viewer application.

** Note:  The JHI will not compile with the HDF 4.1.r1 due to a 
slight change in the include files.  Be sure the Makefile points
to the current version of HDF.  **

  Java HDF Interface (JHI) :

       The Java interface for HDF consists of two parts:
            1. Java classes to interface with the standard HDF library, 
               including 'native methods' and support for Java Exceptions, 
               and data conversion.
            2. C-library that uses the Java Native Method Interface
               (JNI) to implement the Java calls to the HDF library.

       Together these provide access to almost all the routines
       of the HDF library.  This interface may be used by any
       Java application that wants to use the HDF library.

       Note that this is an interface to the regular HDF library,
       it is NOT an implementation of HDF written in Java.

       The Java Interface to HDF requires Java JDK 1.1.1 or above.
       This cannot be used with JDK 1.02.

  Java HDF Viewer (JHV):

       The JHV is a Java application to browse HDF files.  The
       JHV uses the Java Interface for HDF.  The JHV is a standalone
       application, it cannot be used as a network loadable applet.

  For more information, see the on-line documentation at:

     http://hdf.ncsa.uiuc.edu/java-hdf-html/

2. Obtaining the latest version
   ============================

    The most recent version of the distribution can be obtained from
    the NCSA ftp archive site at:

       ftp://ftp.ncsa.uiuc.edu/HDF/Java

    To obtain the latest version of Java, see the web pages at:

       http://java.sun.com/products/jdk/jdk-ports.html

3. Installing JHI and JHV
   ======================

    For compiling and installing the Java HDF API and JHV
    on a system, please follow these instructions. 

3.1 Supported Platforms
    ===================

  This product requires Java Development Kit JDK 1.1.1 or above.
  Not all platforms support Java at this level yet, and we have
  not tested all platforms that have JDK 1.1.
  
  For PLATFORM specific NOTES see the section below called
  'Platform-specific Notes'.

  The platforms for which the NCSA Java products have been
  successfully compiled and tested are:

  Platform(OS)            
  ------------           
  Sun4(Solaris 2.5)     
  SGI-Indy(IRIX5.3)    
  SGI-Indy(IRIX6.2)   
  IBM PC - Intel Pentium
     Windows NT/95  
     Linux           
     Solarisx86 (2.5) 

3.2  Software Requirements:
     ======================

  This software must be compiled with the HDF 4.1r2 library.  If
  HDF is already installed, it is probably not necessary to install 
  or compile it again.  However, it is necessary to generate the
  Java loadable version of the HDF library.

  This product requires Java JDK 1.1 or above to compile.  It will
  not work with JDK 1.02.

  To obtain the latest version of Java, see the web pages at:
       http://java.sun.com/products/jdk/1.1/ or
       http://java.sun.com/products/jdk/jdk-ports.html


3.3 General Configuration/Installation - Unix
    =========================================

    3.3.1 Overview
    --------------        
    This distribution uses a gnu 'configure' script to guess the
    correct configuration.

    The configuration script asks for information which is very 
    difficult to automatically determine:

	   1.  The location of the HDF library and include files.
               This may be a compiled distribution, or previously
               installed libraries.
	   2.  The location of the Java Development Kit JDK 1.1.x.
               This varies across different platforms.
	   3.  Where to install HDF Java.  This might not be
	       the same location as the regular HDF library.

    As this is a relatively complex configuration, it is recommended
    that you inspect the Makefiles to make sure they are correct.

   3.3.2 Layout of the distribution
   --------------------------------

   There are eight subdirectories in this directory:

     Config -- contains support for the configure script


     bin    -- the jhv invocation script
     lib    -- the directory for the compiled classes, native libraries
               and icons used for the jhv browser
     samples -- some sample hdf files
     ncsa   -- source codes for the java class packages including ncsa.hdf.awt,
               ncsa.hdf.hdflib, ncsa.hdf.io, ncsa.hdf.jhv, ncsa.hdf.message,
               ncsa.hdf.server and ncsa.hdf.util. The details of these packages
               are in the documentation pages.
     native -- source for the native (C) support for the java classes.
               This includes the Java HDF API (hdflib) and support
               for the jhv (jhvlib).
 

    3.3.3 Layout of configuration files
    -----------------------------------
    The following shows the layout of the files used in the configuration
    of the HDF Java API and JHV distribution.

    $(toplevel)/configure 
                configure.in (gnu -- used to generate 'configure')
                Config/config.guess
                Config/config.sub
                Config/install-sh
                Makefile.in

                native/Makefile.in
                native/hdflib/Makefile.in
                native/jhv/Makefile.in

                bin/jhv.in  (used to generate the 'jhv' script)


    3.3.4 Running configure
    -----------------------
    To build both of the libraries contained in this directory,
    run the ``configure'' script in $(toplevel), e.g.:

	./configure

    If you're using `csh' on an old version of System V, you might need 
    to type `sh ./configure instead to prevent `csh' from trying to 
    execute `configure' itself.

    The configuration is saved in the file 'config.cache'.  You can
    rebuild the Makefiles as many times as you want using this cached 
    configuration.  If you want to change the configuration, delete
    the file 'cache.config' and run 'configure' again.

    3.3.4 Compiling, Testing and Installing
    ---------------------------------------
    To compile the Java HDF library and JHV type:

        make 

    To find out the available make targets type:

        make help

    To install the libraries, utilities, includes and man pages type: e.g.

        make install

    To create the 'javadoc' pages, type:

	make javadocs


    3.3.5 Installation Location
    ---------------------------

    The 'configure' script asks for the location of where to install
    the HDF Java classes, libraries, and support files.
    If you prefer, you can specify the directory so that `make install'
    will install the files directly in it.  This is done by giving
    `configure' the option `--prefix=PATH'.

    eg.  ./configure --prefix=/usr/local/java/hdf

    This will configure the distribution to install the libraries,
    utilities, and doc files in '/usr/local/java/hdf/lib', 
    '/usr/local/java/hdf/lib/classes.zip', '/usr/local/java/hdf/bin', 
    and '/usr/local/java/hdf/docs' respectively.

4.  Platform-specific Notes
    ========================

    4.1 Windows '95 or Windows NT
    -------------------------------
    The NCSA HDF Java products should compile on a Windows '95 or 
    Windows NT machine.  The build procedure depends on your compile
    environment.

    4.2 HPUX
    --------
    The NCSA Java products are not currently available for HPUX.

    Java JDK 1.1 is not available for HPUX 9.0x, only for HPUX 10.20.

    In order to use native code from Java, the library must be compiled
    as a dynamically loadable library.  Unfortunately, no dynamically
    loadable version of HDF is available for HPUX 10.20, so the Java
    HDF products are not available for HPUX systems.

    4.3 Linux
    ---------
    The NCSA Java products require the latest patched release of the
    JDK, JDK 1.1.3v2-1.  See: 
        http://www.blackdown.org/java-linux.html

    4.4 Other Platforms
    -------------------

    The HDF Java products should work for any platform that meets the
    two requirements:

       1.  The HDF 4.2r3 library must run on the platform
       2.  JDK 1.1 or later must be available

    The web page at:

       http://java.sun.com/products/jdk/jdk-ports.html

    lists many platforms which support JDK 1.1, including
    Macintosh, AIX, DEC/OSF, and DEC VMS.  The NCSA Java products 
    should theoretically work on all these platforms, but we have 
    not actually tested them.

    4.4.1  Compiling for a new platform
    -----------------------------------

    The Java HDF Interface links to the HDF library using the Java
    Native Interface.  On most platforms, this requires that the HDF 
    library be linked so that it can be dynamically linked by the
    Java runtime.  The details of how to link the C library are
    platform dependent.

    The compiler switches for the platforms tested at NCSA are in the
    files "configure.in" and "configure".  E.g., for solaris, the 
    following options are set:

	LD=$CC; LDOPT=-G; SLEXT="so";
        COPT=-G; JAVAINC2=$JAVAINC/solaris ; JAVATARG=solaris;;

    For this platform, the linker program is set, the options (in 
    this case '-G' generates a dynamic library), and the shared library
    extension (in this case, the files are called '*.so') and the
    location of the JNI C header files (JAVAINC2). 

    For a new platform, the Makefile needs to be changed to use the
    appropriate settings and paths.  It may be necessary to consult
    the vendor's documentation to determine these parameters.

    It may also be necessary to adjust the JAVAINC, JAVALIB,
    and CLASSPATH variables in the Makefile, so that they
    point to the required Java support on the platform.

5. Man pages (javadoc)
   ===================

    The `javadoc' utility was used to automatically create manual
    pages for the NCSA HDF Java products.  The javadoc pages are
    available on-line at:

       http://hdf.ncsa.uiuc.edu/java-hdf-html/javadocs/

    To generate your own copy of the man pages with 'javadoc', type:
         make javadocs

6. Release notes and Documentation
   ===============================

   Release notes, documentation, and FAQs are available on-line at:

       http://hdf.ncsa.uiuc.edu/java-hdf-html/

   The general HDF 4.1r2 documentation can be found on the NCSA ftp 
   server in the directory /HDF/Documentation/HDF4.1r2/.  The
   HDF home page is at:

      http://hdf.ncsa.uiuc.edu/

7. HELP
   ====
   If you have any questions or comments, there are several mailing
   lists that may help:

       hdf-java@ncsa.uiuc.edu   --  Java and HDF discussion, help, availability
       hdfnews@ncsa.uiuc.edu   --  HDF announcments
       hdfhelp@ncsa.uiuc.edu   --  HDF help, availability

   If you would like to be added to or removed from these email lists, 
   contact us at:

      hdfhelp@ncsa.uiuc.edu


