Package posix

Posix for Java.

See:
Description

Interface Summary

SignalListener

An interface to listen for a posix signal event.

Class Summary

CPtr	Read and write memory reachable through a C ptr.
CPtr.Struct	Compute the offsets of a C struct one member at a time.
Errno	Report error codes returned by posix calls.
File	Extend java.io.File with posix features.
IPC	The base class of the SysV derived posix IPC methods.
IPC.Perm	Permission structure for SysV IPC resources.
LockFile	A simple unix style lock file.
Malloc	Make C memory allocated with the malloc posix call available to Java.
MsgQ	Represent a posix message queue.
MsgQ.msqid_ds
Passwd	POSIX style access to the unix passwd file.
SemSet	Represent a posix semaphore set.
SemSet.semid_ds
SharedMem	A Posix shared memory segment.
SharedMem.shmid_ds
Signal	A posix signal.
SignalEvent	An event thrown when a posix signal is trapped.
Stat	File status record for posix systems.
TestPasswd	Test Passwd behavior.

Exception Summary

AlignmentException	Report an access to C memory that violates platform dependent alignment restrictions.
IPCException	Report unexpected errors with posix IPC calls.

Package posix Description

Posix for Java.

Why Posix for Java?

A frequently asked question on Java newsgroups is "How do I use unix signals (or messages or environment variables or ...) in Java?" The answer is, you can't with standard Java. Equivalent features are in Java. For example, Properties instead of environment variables or Sockets instead of the various forms of unix IPC.

However, sometimes it is necessary to interface with code written for the unix environment - and that code can't be rewritten to use Sockets. In those cases, it would be nice to have simple access to the Posix API without everyone having to reinvent the wheel.

One solution is the posix package. This package provides access to the posix API from Java. It uses a JNI library which should be portable to other posix systems. I started this package with the intent of making it reusable by others. However, it only has the classes I have needed for my own projects at present :-). I am making the source and docs public so that others can reuse what I have so far and so that I can collect any additions added by others.

There is another posix API for Java used by the Jython project: jnios. I will be looking at incorporating features from that package, or getting rid of my own entirely. I will not get rid of 'posix' if the jnios package requires jython.

SysV IPC

There is fairly complete support for IPC. The MsgQ class wraps message queues, and SemSet wraps semaphores.

The SharedMem class wraps an ipc shared memory segment. Attaching a SharedMem returns a CPtr which allows safe and portable access to C format structures in the shared memory. (You can only trash stuff in the share memory, not anywhere else.) Similarly, Malloc safely allocates and accesses blocks of C memory which can be passed to C apis and are not garbage collected.

The Passwd class

The Passwd class provides read only access to files in the unix /etc/passwd format. It is a pure Java implementation.

The Stat function

The Stat class provides the most common fields from stat.h and a stat() method to fill them in. The File class extends java.io.File to provide additional attributes such as lastAccessed().

The Posix Signal API for Java

The Signal class models posix signals, converting them to Java Event notifications. Common posix signals are provided as preinitialized static Signal objects. Because the JVM uses signals internally, I do not export the API for trapping any signal. The ones I provide I believe are safe.

Signal Event implementation

A single Java Thread listens for signals by executing sigwait() through JNI to wait on a semaphore. The JNI code actually spawns another non-Java thread to call sigwait, because that thread must be cancelled in order to change the set of signals handled by Java. The Java Signal Thread generates a SignalEvent for each signal.

This implementation should be portable to any pthreads platform. It uses mutexes and condition variables - which the JVM would also have to use. Currently, there is a small window during which a signal will take the default action when calling Signal.setAction(). Set up your SignalListeners at startup, and there should be no problem.

Further Information

The JNI source is in C++. The C++ is used as a "better C". In particular, there are no static initializers, RTTI, or exceptions used since there is no standard JVM support for C++. (Only these C++ features require special runtime support.) We currently use gcc-3.4.6 on Centos4 with Sun JDK 1.5.0_16, and gcc-2.7.2 on AIX with the IBM JDK 1.1.6.4.