Tutorial: using Java on MPE/iX

Contents

I. Theoretical Stuff

A. The Java Language

B. The Java Virtual Machine

C. The Java Platform

D. How does Java measure up?

II. Practical Stuff

A. Obtaining Java

B. Installing Java

C. Java Directory Structure

D. Java Components

E. Using Java

F. Where to go for more info

III. Java and Databases

IV. The Java Native Interface

I. Theoretical stuff

I-A. The Java language

I-B. The Java virtual machine

I-C. The Java platform

I-D. So how does 'Java' measure up to the claims?

I-D-1. Java performance

I-D-2. Java security

I-D-3. Java portability

II. Practical stuff

II-A. Obtaining Java

II-B. Installing Java

shell/iX> gunzip TARFILE

shell/iX> tar -xovf TARFILE
or
shell/iX> mover -x TRUCK     

export SYSNAME=hp3000     

export PATH=$PATH:/usr/local/java/latest/bin
setenv HPPATH "!hppath,/usr/local/java/latest/lib/PA-RISC/green_threads"

export CLASSPATH=$CLASSPATH:(add your stuff here)
setenv CLASSPATH "/usr/local/java/latest/lib/classes.zip:\
   (add your stuff here)"

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:(add your stuff here)
setenv LD_LIBRARY_PATH "/usr/local/java/latest/lib/PA-RISC/green_threads:
(add your stuff here)"

export THREADS_FLAG=green

export DISPLAY=sysname:0.0
setenv DISPLAY "sysname:0.0"     

II-C. Java directory structure

shell/iX> ln -s /usr/local/java/jdk1.1.2 /usr/local/java/latest
or
:NEWLINK /usr/local/java/latest, /usr/local/java/jdk1.1.2     

II-D. Java components

II-D-1. Programs

II-D-2. Shell scripts

To run          You can type           Or:
javac           javac foo.java         java sun.tools.javac.Main foo.java
appletviewer    appletviewer foo.html  java sun.applet.AppletViewer foo.html
javadoc         javadoc foo.class      java sun.tools.javadoc.Main foo.class    

II-D-3. Classes

II-D-4. Libraries

II-E. Using Java

II-E-1. Writing Java programs

public class HelloWorld
{
  public static void main(String[] args)
  {
    System.out.println("Hello, World!");
  }
}     

II-E-2. Compiling a program

javac HelloWorld.java        

II-E-3. Executing a program

java HelloWorld     

II-E-4. Hey, what about that just-in-time compiler?

II-E-5. Cross-platform Java development

II-F. Where to go for more info

III. Java and databases

JDBC

J/SQL

ADBC

TurboIMAGE class library for Java and C++

IV. The Java native interface (JNI)

Step 1: include a native method declaration in the Java class

private native void DBOPEN (
  byte base[], String pass, short mode, DBStatus status);

Step 2: include a static call to load the XL which contains the C code.

static {
  System.loadLibrary("TurboIMAGE");
}     

package TurboIMAGE;

/** This class is used to represent a TurboIMAGE database.
 *
 * @version X.00.10, for JDK 1.1, April 1997
 * @author  Mike Yawn
 */
public class Database {

   // Intrinsic Parameters
   byte[]   basename = new byte[26];
   String   password = new String(";");
   String   dummy    = new String(" ");  // an ignored parameter
   DBStatus status = new DBStatus();

   static {
      // Note actual library name is libTurboIMAGE[_g].sl
      System.loadLibrary("TurboIMAGE");
   }

   /** Constructor to create database object, given a
    *  local database root file name.  If the first two
    *  characters you pass are not blanks, this routine
    *  will add blanks to the beginning of the name.  If
    *  the last character is not a semicolon, this routine
    *  will add one.  Filename should be in MPE syntax.
    * @param dbRootFile The name of the database root file.
    */
   public Database(String dbRootFile){
      int endchar = dbRootFile.length();
      if (dbRootFile.startsWith("  ")){
        basename = dbRootFile.getBytes();
      } else {
             basename[0] = ' '; basename[1] = ' ';
             for (int i=0; i<endchar; i++) {
                 basename[i+2] = (byte) dbRootFile.charAt(i);
             }
             endchar += 2;
      }
      if((basename[endchar-1] != ';') &&
         (basename[endchar-1] != ' ')) {
         basename[endchar]= ';'; 
      }
   }

   /** Set the database password.  Will add trailing semicolon
     * if not specified by the user.  If this method is not
     * called prior to an open call, the creator password will
     * be used as a default */
   public void setPassword(String pass){
      if(pass.endsWith(";")) {
         password = new String(pass);
      } else {
        password = new String(pass + ";");
      }
   }

   /** Open the database with explicit mode.
    *  Numeric mode parameters will be more familiar to long-time
    *  users of the TurboIMAGE intrinsic calls.  Additional calls
    *  are available that use mnemonics to describe the open mode,
    *  which is more self-documenting.
    * 
    * @param mode   16-bit numeric value for open mode
    */
   public void open(short mode) throws IMAGEException {
      DBOPEN(basename, password, mode, status);
   }

   // Stubs that call TurboIMAGE Intrinsics
   private native void DBOPEN(byte base[], String pass, short mode,
                              DBStatus status);

// main method allows this class to be tested independently.
// In actual usage, this class' main method is never executed.
public static void main(String[] argv) {
    Database testdb;
    String   testname;
    String   testpass;
    Byte     modein;
    Short    testmode;

    java.io.DataInputStream ins = 
      new java.io.DataInputStream(System.in);
    try {
       System.out.print("Enter database name :");
       testname = ins.readLine();
       System.out.print("Enter password      :");
       testpass = ins.readLine();;
       System.out.print("Enter mode          :");
       testmode = new Short(ins.readLine());
         // above may throw NumberFormatException
       testdb   = new Database(testname);
       testdb.setPassword(testpass);
       testdb.open(testmode.shortValue());
       System.out.println("now open: " + testname);
    } catch (Exception e) {
        System.out.println("Database main: " + e);
    }
  }
}     

Step 3: compile the class

Step 4: run javah to create C headers

javah -jni TurboIMAGE.Database     

/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
/* Header for class TurboIMAGE_Database */

#ifndef _Included_TurboIMAGE_Database
#define _Included_TurboIMAGE_Database
#ifdef __cplusplus
extern "C"
#endif
/*
 * Class:   TurboIMAGE_Database
 * Method:  DBOPEN
 * Signature: ([BLjava/lang/String;SLTurboIMAGE/DBStatus;)
 */
JNIEXPORT void JNICALL Java_TurboIMAGE_Database_DBOPEN
  (JNIEnv *, jobject, jbyteArray, jstring, jshort, jobject);

#ifdef __cplusplus
}
#endif
#endif     

Step 5: write the C implementation

#include "TurboIMAGE.h"                    
/* function to throw exceptions based on TurboIMAGE errors */                   
void ThrowException(JNIEnv *env, char * intrinsic, void *CStatus)
{          
  char message[100];                                               
  short msglen;                                                       
  jclass IEClass;

  /* first report & clear any pending exception */ 
  (*env)->ExceptionDescribe(env);  
  (*env)->ExceptionClear(env);                    
  /* now see what our problem is */  
  dberror(CStatus, message, &msglen); 
  message[msglen] = '\0'; /* needs null terminator */ 
  /* and throw an exception to report it */ 
  IEClass=(*env)->FindClass(env, "TurboIMAGE/IMAGEException"); 
  (*env)->ThrowNew(env, IEClass, message);                     
} 

//**********************************************************
//********** TurboIMAGE Database Implementation ************
//**********************************************************
/* Function to call DBOPEN */ 
JNIEXPORT void JNICALL
Java_TurboIMAGE_Database_DBOPEN(JNIEnv    *env,
                jobject    this, 
                jbyteArray j_basename,
                jstring    j_password,
                jshort     j_mode,
                jobject    j_status) { 

  int i;

  // JNI types for accessing DBStatus 
  jfieldID         f_halfword;
  jobject          p_halfword; 
  jshort          *a_halfword;  
  jclass           c_DBStatus; 
                                                                      
  // Get JNI fields into C types  
  jbyte *base = (*env)->GetByteArrayElements(env, j_basename, 0);
  const char *pass = (*env)->GetStringUTFChars(env, j_password, 0); 

  c_DBStatus = (*env)->GetObjectClass(env, j_status); 
  f_halfword = (*env)->GetFieldID(env, c_DBStatus, "halfword", "[S");
  p_halfword = (*env)->GetObjectField(env, j_status, f_halfword); 
  a_halfword = (*env)->GetShortArrayElements(env, p_halfword, 0);  

  dbopen(base, pass, &j_mode, a_halfword);

  if (a_halfword[0] < 0){
    ThrowException(env, "DBOPEN", a_halfword); 
    return; 
  } 

  (*env)->ReleaseByteArrayElements(env, j_basename, base, 0); 
  (*env)->ReleaseStringUTFChars(env, j_password, pass);            
  (*env)->ReleaseShortArrayElements(env, p_halfword, a_halfword, 0);
}     

Step 6: compile the C code and place in an XL

shell/iX> gcc -I/usr/local/java/latest/include 
          -I/usr/local/java/latest/include/mpe 
          -c -o DatabaseImpl.o DatabaseImpl.c

shell/iX> callci linkedit
LinkEdit> buildxl ./libTurboIMAGE.sl;limit=10
LinkEdit> addxl ./DatabaseImpl.o ./libTurboIMAGE.sl     

LinkEdit> exit     

Step 7: test the Java class

shell/iX> java Database