===== ISAMJ ===== 1. Overview 2. ISAMJ Java 3. ISAMJ Native 4. ISAMJ Deliverables 5. Documentation 6. Installation 7. Troubleshooting ======== OVERVIEW ======== ISAMJ is a product from LegacyJ that bridges Java technology to the ISAM interface. As ISAM is defined for native code (primarily C), a bridge is necessary to connect Java to the native code. This bridge would normally be done through JNI (Java Native Interface), but ISAMJ provides that bridge so no native coding is required. Using ISAMJ, Java accesses ISAM as if it were just another Java API, while allowing the original native code ISAM to execute and access the original ISAM data. ISAMJ is in two parts: the Java side and the JNI native side. The Java side remains the same regardless of platform. The same Java interfaces and Java classes are accessed on any platform from Windows to Solaris. The JNI piece is unique to each platform. ========== ISAMJ Java ========== The ISAMJ Java side has two interface layers, a low-level and a high-level interface. The low-level interface closely matches the original ISAM specification, including functions such as isaddindex and iserase. The high-level interface more closely resembles existing Java API's, encapsulating the ISAM function in a more object-oriented framework; classes such as ISAMFile extends File and ISAMRecord which may be extended by user record classes. The low-level functionality is encompassed within the ISAM and ISAMConstants classes. The high-level functionality is encompassed within the ISAMFile, ISAMRecord, ISAMKey, ISAMAudHead, ISAMDictInfo and ISAMConstants classes. ISAMJ Native The ISAMJ native side implements a JNI interface used by the Java side and accesses a native code shared library which implements the ISAM functionality. Java native code must be in shared library/shared object form (.DLL in Windows). The ISAMJ native side accesses this shared library, passing requests and data from the Java side to the native ISAM driver. The native ISAM drivers tested include Informix C-ISAM, Byte Designs D-ISAM and ObjecTrieve. (ObjecTrieve does not provide variable length record support.) ================== ISAMJ Deliverables ================== ISAMJ includes the high- and low-level functionality .class files (Java executables). ISAMJ also includes the native isamj.dll or libisamj.so connector piece. This connector piece is unique to each platform, currently available for Windows and Solaris; other platforms are available upon request. ISAMJ does not include ISAM functionality itself; this must be provided by a third-party (such as Byte Designs D-ISAM). File created and accessed using ISAMJ may be created and accessed using Java programs, while the data is in the original binary datafile format. ISAMJ includes the JavaDoc documentation of the classes, the format most used for Java class documentation and most familiar to Java programmers. ============= Documentation ============= ISAMJ documentation is in JavaDoc format off of the doc directory in the isamj directory. The documentation may be viewed from the doc\index.html file using any modern browser such as Netscape or Internet Explorer. ============ Installation ============ Installation for development consists of unzipping or untarring the distribution file or copying the files from CD to the desired directory. A Java file called 'isamj.jar' and several directories will be created upon extracting the distribution file. The directories will include one named 'docs' and one named after the platform (e.g., 'win32'). In the docs directory are the documentation files in JavaDoc .html format. They may be viewed using any modern browser and are for the development machine only. The isamj.jar file contains the Java .class files necessary for the implementation and access of ISAMJ from Java. This isamj.jar file must be made accessible to the Java Virtual Machine used in development (and later, the JVM used in deployment). This may be done by adding it to the CLASSPATH, as in: (Posix) CLASSPATH=$CLASSPATH:{isamj-directory}/isamj.jar export CLASSPATH or (Windows) set CLASSPATH=%CLASSPATH%;{isamj-directory}\isamj.jar Or it may be done by copying it to the ext (extensions) directory of Java. Also, an IDE (Integrated Development Environment) may have its own method of adding .jar files. The native file (found in a directory named after the platform, such as win32) will be named after isamj with the shared object extension for the platform, such as isamj.dll, libisamj.so, libisamj.sa, or libisamj.sl. This file is known as the ISAMJ shared object. It must be available in the same fashion that native shared object are always made available on the native platform. In Windows, it will look in the PATH and current directory. On other platforms, LD_LIBRARY_PATH must include the directory which contains the file. This shared object may either be the shared object distributed with ISAMJ, or one created by linking together the static object provided with ISAMJ together with the ISAM implementation itself. The following scenarios are available. I. Dynamic Link Libraries The dynamic library approach uses the shared object together with a dynamic library implementation of ISAM. Use this approach when the ISAM distribution is provided in dynamic form, such as ending in .dll, .so or .sl. With this format, no extra linking steps are required since the linking is done dynamically at runtime. ISAMJ attempts to load the ISAM file given by the following names in order: ISAMJ.LIBRARY environment variable contents isamj.library environment variable contents ISAMJ environment variable contents isamj environment variable contents If none of these names is found, then the 'wrap32.dll' is used in Windows and 'libisamj.so' is used on other platforms. If the ISAM implementation cannot be loaded, then in Windows the file 'wrap32.dll' then 'winisam.dll' will be attempted. On other platforms, 'libisam.so', 'libd96.so', 'libisam.sl' then 'libd96.sl' will be attempted. The ISAM implementation must be available during development and deployment as a separate entity. The final setup is visualized as: User Java Classes => ISAMJ Java => ISAMJ Native => ISAM Native Code Impl. II. Static Link Libraries Static link libraries are not available on every platform. When present, there are various static libraries provided: Posix Windows Description slibisam.o sisamj.obj Standard library clibisam.o cisamj.obj + C-ISAM library dlibisam.o disamj.obj + Byte Designs D-ISAM library One of these object files must be linked together with an actual ISAM implementation to form a shared object library (called isamj.dll, libisamj.so or libisamj.sl depending on the normal form for the platform). The final shared dynamic library must be named 'isamj' plus the standard prefix and suffix for dynamic libraries on the platform; Java's load process requires that the library be named exactly. This linking process is highly linker dependent and dependent on the library provided by the ISAM vendor. The ISAM library provided must be capable of being linked into a shared dynamic object. The standard library is sufficient for most needs. The clibisam.o and dlibisam.o provide some additional function and method calls above and beyond the standard. This linking needs to be done only once; after the linked library is created and available, there is no need to relink for further access. The final setup is visualized as: User Java Classes => ISAMJ Java => [ ISAMJ Native + ISAM Native Code Impl. ] =============== Troubleshooting =============== If some troubleshooting is necessary of the connection to ISAM interface, the environment variable DEBUGISAMJ may be set to a non-empty value to create a debug log to stdout. This debug log gives traces information from the native side of ISAMJ. -- Copyright 2001, 2002 LegacyJ Corp. All Rights Reserved.