Foreign.Java.JNI.Safe

Low level interface to the Java Virtual Machine. This module is a very thin wrapper over the Java Native Interface.

Note that all functions that return references (of type Ptr JObjectRef) return global references which you will need to free manually.

This module contains safe bindings, see also Foreign.Java.JNI.Unsafe.

Read the The Java Native Interface - Programmer's Guide and Specification for further information on the Java Native Interface (available at http://www.soi.city.ac.uk/~kloukin/IN2P3/material/jni.pdf, and http://192.9.162.55/docs/books/jni/).

Controlling the virtual machine

data JVM

createVM :: IO (Ptr JVM)

createVM'

Arguments

:: Word32

The number of arguments (like argc)

-> Ptr CString

A char** to the arguments (like argv)

-> IO (Ptr JVM)

Returns a Ptr to the newly running JVM

destroyVM :: Ptr JVM -> IO ()

persistVM :: Ptr JVM -> IO ()

Discovering classes

data JClassRef

findClass :: Ptr JVM -> CString -> IO (Ptr JClassRef)

Object creation

data JConstructorID

data JObjectRef

getConstructorID :: Ptr JVM -> Ptr JClassRef -> CString -> IO (Ptr JConstructorID)

newObject :: Ptr JVM -> Ptr JClassRef -> Ptr JConstructorID -> Ptr JValues -> IO (Ptr JObjectRef)

Method access

data JStaticMethodID

data JMethodID

getStaticMethodID :: Ptr JVM -> Ptr JClassRef -> CString -> CString -> IO (Ptr JStaticMethodID)

getMethodID :: Ptr JVM -> Ptr JClassRef -> CString -> CString -> IO (Ptr JMethodID)

Static method invocation

callStaticVoidMethod :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticMethodID -> Ptr JValues -> IO ()

callStaticBooleanMethod :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticMethodID -> Ptr JValues -> IO Bool

callStaticCharMethod :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticMethodID -> Ptr JValues -> IO Word16

callStaticByteMethod :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticMethodID -> Ptr JValues -> IO Int8

callStaticShortMethod :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticMethodID -> Ptr JValues -> IO Int16

callStaticIntMethod :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticMethodID -> Ptr JValues -> IO Int32

callStaticLongMethod :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticMethodID -> Ptr JValues -> IO Int64

callStaticFloatMethod :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticMethodID -> Ptr JValues -> IO CFloat

callStaticDoubleMethod :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticMethodID -> Ptr JValues -> IO CDouble

callStaticObjectMethod :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticMethodID -> Ptr JValues -> IO (Ptr JObjectRef)

callStaticStringMethod :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticMethodID -> Ptr JValues -> IO CString

Method invocation

callVoidMethod :: Ptr JVM -> Ptr JObjectRef -> Ptr JMethodID -> Ptr JValues -> IO ()

callBooleanMethod :: Ptr JVM -> Ptr JObjectRef -> Ptr JMethodID -> Ptr JValues -> IO Bool

callCharMethod :: Ptr JVM -> Ptr JObjectRef -> Ptr JMethodID -> Ptr JValues -> IO Word16

callByteMethod :: Ptr JVM -> Ptr JObjectRef -> Ptr JMethodID -> Ptr JValues -> IO Int8

callShortMethod :: Ptr JVM -> Ptr JObjectRef -> Ptr JMethodID -> Ptr JValues -> IO Int16

callIntMethod :: Ptr JVM -> Ptr JObjectRef -> Ptr JMethodID -> Ptr JValues -> IO Int32

callLongMethod :: Ptr JVM -> Ptr JObjectRef -> Ptr JMethodID -> Ptr JValues -> IO Int64

callFloatMethod :: Ptr JVM -> Ptr JObjectRef -> Ptr JMethodID -> Ptr JValues -> IO CFloat

callDoubleMethod :: Ptr JVM -> Ptr JObjectRef -> Ptr JMethodID -> Ptr JValues -> IO CDouble

callObjectMethod :: Ptr JVM -> Ptr JObjectRef -> Ptr JMethodID -> Ptr JValues -> IO (Ptr JObjectRef)

callStringMethod :: Ptr JVM -> Ptr JObjectRef -> Ptr JMethodID -> Ptr JValues -> IO CString

Field access

data JFieldID

data JStaticFieldID

getFieldID :: Ptr JVM -> Ptr JClassRef -> CString -> CString -> IO (Ptr JFieldID)

getStaticFieldID :: Ptr JVM -> Ptr JClassRef -> CString -> CString -> IO (Ptr JStaticFieldID)

Static getters

getStaticBooleanField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> IO Bool

getStaticCharField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> IO Word16

getStaticByteField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> IO Int8

getStaticShortField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> IO Int16

getStaticIntField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> IO Int32

getStaticLongField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> IO Int64

getStaticFloatField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> IO CFloat

getStaticDoubleField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> IO CDouble

getStaticObjectField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> IO (Ptr JObjectRef)

getStaticStringField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> IO CString

Static setters

setStaticBooleanField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> Bool -> IO ()

setStaticCharField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> Word16 -> IO ()

setStaticByteField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> Int8 -> IO ()

setStaticShortField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> Int16 -> IO ()

setStaticIntField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> Int32 -> IO ()

setStaticLongField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> Int64 -> IO ()

setStaticFloatField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> CFloat -> IO ()

setStaticDoubleField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> CDouble -> IO ()

setStaticObjectField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> Ptr JObjectRef -> IO ()

setStaticStringField :: Ptr JVM -> Ptr JClassRef -> Ptr JStaticFieldID -> CString -> IO ()

Member getters

getBooleanField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> IO Bool

getCharField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> IO Word16

getByteField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> IO Int8

getShortField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> IO Int16

getIntField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> IO Int32

getLongField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> IO Int64

getFloatField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> IO CFloat

getDoubleField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> IO CDouble

getObjectField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> IO (Ptr JObjectRef)

getStringField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> IO CString

Member setters

setBooleanField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> Bool -> IO ()

setCharField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> Word16 -> IO ()

setByteField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> Int8 -> IO ()

setShortField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> Int16 -> IO ()

setIntField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> Int32 -> IO ()

setLongField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> Int64 -> IO ()

setFloatField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> CFloat -> IO ()

setDoubleField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> CDouble -> IO ()

setObjectField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> Ptr JObjectRef -> IO ()

setStringField :: Ptr JVM -> Ptr JObjectRef -> Ptr JFieldID -> CString -> IO ()

Argument passing

data JValues

data JArg where

Constructors

BooleanA :: Bool -> JArg

CharA :: Word16 -> JArg

ByteA :: Int8 -> JArg

ShortA :: Int16 -> JArg

IntA :: Int32 -> JArg

LongA :: Int64 -> JArg

FloatA :: Float -> JArg

DoubleA :: Double -> JArg

StringA :: String -> JArg

ObjectA :: Maybe JObject -> JArg

ArrayA :: Maybe (JArray e) -> JArg

mkJValues :: Ptr JVM -> [JArg] -> IO (Ptr JValues)

Create a JValues Array which can be used for argument passing to a multi parameter method. You need to free the Ptr object manually using free.

This method is implemented using calloc internally. See the native implementation of newJValues.

newJValues :: CInt -> IO (Ptr JValues)

setJValueByte :: Ptr JValues -> CInt -> Int8 -> IO ()

setJValueShort :: Ptr JValues -> CInt -> Int16 -> IO ()

setJValueInt :: Ptr JValues -> CInt -> Int32 -> IO ()

setJValueLong :: Ptr JValues -> CInt -> Int64 -> IO ()

setJValueFloat :: Ptr JValues -> CInt -> CFloat -> IO ()

setJValueDouble :: Ptr JValues -> CInt -> CDouble -> IO ()

setJValueObject :: Ptr JValues -> CInt -> Ptr JObjectRef -> IO ()

setJValueString :: Ptr JVM -> Ptr JValues -> CInt -> CString -> IO ()

Releasing resources

releaseJObjectRef :: Ptr JVM -> Ptr JObjectRef -> IO ()

releaseJClassRef :: Ptr JVM -> Ptr JClassRef -> IO ()

releaseJThrowableRef :: Ptr JVM -> Ptr JThrowableRef -> IO ()

release :: ReleaseGlobalReference a => FunPtr (Ptr a -> IO ())

release is a special function which can be used to create a ForeignPtr. A ForeignPtr does not carry a reference to a virtual machine (no Ptr JVM), thus this function will lookup the current virtual machine or do nothing if it can not find one. It is realised as a FunPtr as this is what newForeignPtr expects.

Special data types

String handling

data JChars

data JBytes

newJString :: Ptr JVM -> CString -> IO (Ptr JObjectRef)

charsFromJString :: Ptr JVM -> Ptr JObjectRef -> IO (Ptr JChars)

bytesFromJString :: Ptr JVM -> Ptr JObjectRef -> IO (Ptr JBytes)

releaseJChars :: Ptr JVM -> Ptr JObjectRef -> CString -> IO ()

releaseJBytes :: Ptr JVM -> Ptr JObjectRef -> CString -> IO ()

jStringToCString :: Ptr JVM -> Ptr JObjectRef -> CString -> IO ()

Array handling

getArrayLength :: Ptr JVM -> Ptr JObjectRef -> IO Int32

Reflection

getObjectClass :: Ptr JVM -> Ptr JObjectRef -> IO (Ptr JClassRef)

isInstanceOf :: Ptr JVM -> Ptr JObjectRef -> Ptr JClassRef -> IO Bool

Exception handling

data JThrowableRef

exceptionCheck :: Ptr JVM -> IO Bool

Checks whether an exception has occured in the virtual machine or not.

exceptionOccurred :: Ptr JVM -> IO (Ptr JThrowableRef)

Checks whether an exception occured and return that exception. If no exception occured, the returned pointer will be the nullPtr. This method will return a local reference only, so beware that the obtained Ptr will not be valid for too long.

exceptionOccurredClear :: Ptr JVM -> IO (Ptr JThrowableRef)

Checks whether an exception occured and return that exception. If no exception occured, the returned pointer will be the nullPtr. This method will also call exceptionClear which means that it can not be called twice. This method will return a global reference - as opposed to exceptionOccurred, which will return a local reference only.

exceptionClear :: Ptr JVM -> IO ()

exceptionDescribe :: Ptr JVM -> IO ()

Debugging

getDebugStatus :: IO Bool

setDebugStatus :: Bool -> IO ()

libjvm initialization

getLibjvmPath :: IO CString

Returns the path to libjvm that is used by this library. Note that this will return the nullPtr if the library has not yet been initialized. The library is lazily initialized the first time that runJava' is used. runJava is implemented in terms of runJava, as is initJava.

You are not allowed to invoke free on the returned cstring.

getCompiledLibjvmPath :: IO CString

Returns the path to libjvm with which this library has been compiled. This is guaranteed to never return nullPtr.

You are not allowed to invoke free on the returned cstring.

setLibjvmPath :: CString -> IO ()

Sets the path to libjvm. Note that this will only have an effect if the library has not yet been initialized, that is before any of the following functions is used: runJava, runJava', and initJava.

Do not invoke free on the cstring passed to this function, as this function will not set a copy but the object given. It is only ever used once during the lifecycle of your application.

registerCallbacks :: Ptr JVM -> Ptr JClassRef -> IO Bool

Workarounds for certain platforms

runCocoaMain :: IO ()