Foreign.JNI.Unsafe

Low-level bindings to the Java Native Interface (JNI).

Read the JNI spec for authoritative documentation as to what each of the functions in this module does. The names of the bindings in this module were chosen to match the names of the functions in the JNI spec.

All bindings in this module access the JNI via a thread-local variable of type JNIEnv *. If the current OS thread has not yet been "attached" to the JVM, it needs to be attached. See runInAttachedThread.

The String type in this module is the type of JNI strings. See Foreign.JNI.String.

The functions in this module are considered unsafe in opposition to those in Foreign.JNI.Safe, which ensure that local references are not leaked.

JNI functions

VM management

withJVM :: [ByteString] -> IO a -> IO a

Create a new JVM, with the given arguments. Destroy it once the given action completes. Can only be called once. Best practice: use it to wrap your main function.

newJVM :: [ByteString] -> IO JVM

Create a new JVM, with the given arguments. Can only be called once. Best practice: use withJVM instead. Only useful for GHCi.

destroyJVM :: JVM -> IO ()

Deallocate a JVM created using newJVM.

Class loading

defineClass

Arguments

:: Coercible o (J ('Class "java.lang.ClassLoader"))

=> ReferenceTypeName

Class name

-> o

Loader

-> ByteString

Bytecode buffer

-> IO JClass

data JNINativeMethod

Constructors

forall a. JNINativeMethod

Fields

• jniNativeMethodName :: String
• jniNativeMethodSignature :: MethodSignature
• jniNativeMethodFunPtr :: FunPtr a

Instances

Storable JNINativeMethod

Defined in Foreign.JNI.NativeMethod

Methods

sizeOf :: JNINativeMethod -> Int

alignment :: JNINativeMethod -> Int

peekElemOff :: Ptr JNINativeMethod -> Int -> IO JNINativeMethod

pokeElemOff :: Ptr JNINativeMethod -> Int -> JNINativeMethod -> IO ()

peekByteOff :: Ptr b -> Int -> IO JNINativeMethod

pokeByteOff :: Ptr b -> Int -> JNINativeMethod -> IO ()

peek :: Ptr JNINativeMethod -> IO JNINativeMethod

poke :: Ptr JNINativeMethod -> JNINativeMethod -> IO ()

registerNatives :: JClass -> [JNINativeMethod] -> IO ()

String wrappers

data ReferenceTypeName

A reference type name is not just any String, but a fully qualified identifier well-formed by construction.

Instances

Eq ReferenceTypeName

Defined in Foreign.JNI.Internal

Methods

(==) :: ReferenceTypeName -> ReferenceTypeName -> Bool

(/=) :: ReferenceTypeName -> ReferenceTypeName -> Bool

Ord ReferenceTypeName

Defined in Foreign.JNI.Internal

Methods

compare :: ReferenceTypeName -> ReferenceTypeName -> Ordering

(<) :: ReferenceTypeName -> ReferenceTypeName -> Bool

(<=) :: ReferenceTypeName -> ReferenceTypeName -> Bool

(>) :: ReferenceTypeName -> ReferenceTypeName -> Bool

(>=) :: ReferenceTypeName -> ReferenceTypeName -> Bool

max :: ReferenceTypeName -> ReferenceTypeName -> ReferenceTypeName

min :: ReferenceTypeName -> ReferenceTypeName -> ReferenceTypeName

Show ReferenceTypeName

Defined in Foreign.JNI.Internal

Methods

showsPrec :: Int -> ReferenceTypeName -> ShowS

show :: ReferenceTypeName -> String

showList :: [ReferenceTypeName] -> ShowS

data MethodSignature

A string representing a method signature, well-formed by construction.

Instances

Eq MethodSignature

Defined in Foreign.JNI.Internal

Methods

(==) :: MethodSignature -> MethodSignature -> Bool

(/=) :: MethodSignature -> MethodSignature -> Bool

Ord MethodSignature

Defined in Foreign.JNI.Internal

Methods

compare :: MethodSignature -> MethodSignature -> Ordering

(<) :: MethodSignature -> MethodSignature -> Bool

(<=) :: MethodSignature -> MethodSignature -> Bool

(>) :: MethodSignature -> MethodSignature -> Bool

(>=) :: MethodSignature -> MethodSignature -> Bool

max :: MethodSignature -> MethodSignature -> MethodSignature

min :: MethodSignature -> MethodSignature -> MethodSignature

Show MethodSignature

Defined in Foreign.JNI.Internal

Methods

showsPrec :: Int -> MethodSignature -> ShowS

show :: MethodSignature -> String

showList :: [MethodSignature] -> ShowS

data Signature

A string representing a signature, well-formed by construction.

Instances

Eq Signature

Defined in Foreign.JNI.Internal

Methods

(==) :: Signature -> Signature -> Bool

(/=) :: Signature -> Signature -> Bool

Ord Signature

Defined in Foreign.JNI.Internal

Methods

compare :: Signature -> Signature -> Ordering

(<) :: Signature -> Signature -> Bool

(<=) :: Signature -> Signature -> Bool

(>) :: Signature -> Signature -> Bool

(>=) :: Signature -> Signature -> Bool

max :: Signature -> Signature -> Signature

min :: Signature -> Signature -> Signature

Show Signature

Defined in Foreign.JNI.Internal

Methods

showsPrec :: Int -> Signature -> ShowS

show :: Signature -> String

showList :: [Signature] -> ShowS

Exceptions

newtype JVMException

A JNI call may cause a (Java) exception to be raised. This module raises it as a Haskell exception wrapping the Java exception.

Constructors

JVMException JThrowable

Instances

Show JVMException

Defined in Foreign.JNI.Unsafe

Methods

showsPrec :: Int -> JVMException -> ShowS

show :: JVMException -> String

showList :: [JVMException] -> ShowS

Exception JVMException

Defined in Foreign.JNI.Unsafe

Methods

toException :: JVMException -> SomeException

fromException :: SomeException -> Maybe JVMException

displayException :: JVMException -> String

throw :: Coercible o (J a) => o -> IO ()

throwNew :: JClass -> String -> IO ()

Query functions

findClass

Arguments

:: ReferenceTypeName

Class name

-> IO JClass

getFieldID

Arguments

:: JClass

A class object as returned by findClass

-> String

Field name

-> Signature

JNI signature

-> IO JFieldID

getStaticFieldID

Arguments

:: JClass

A class object as returned by findClass

-> String

Field name

-> Signature

JNI signature

-> IO JFieldID

getMethodID

Arguments

:: JClass

A class object as returned by findClass

-> String

Field name

-> MethodSignature

JNI signature

-> IO JMethodID

getStaticMethodID

Arguments

:: JClass

A class object as returned by findClass

-> String

Field name

-> MethodSignature

JNI signature

-> IO JMethodID

getObjectClass :: Coercible o (J ty) => o -> IO JClass

Reference manipulation

newGlobalRef :: Coercible o (J ty) => o -> IO o

Creates a global reference to the object referred to by the given reference.

Arranges for a finalizer to call deleteGlobalRef when the global reference is no longer reachable on the Haskell side.

deleteGlobalRef :: Coercible o (J ty) => o -> IO ()

newGlobalRefNonFinalized :: Coercible o (J ty) => o -> IO o

Like newGlobalRef but it doesn't attach a finalizer to destroy the reference when it is not longer reachable. Use deleteGlobalRefNonFinalized to destroy this reference.

deleteGlobalRefNonFinalized :: Coercible o (J ty) => o -> IO ()

Like deleteGlobalRef but it can be used only on references created with newGlobalRefNonFinalized.

newLocalRef :: Coercible o (J ty) => o -> IO o

deleteLocalRef :: Coercible o (J ty) => o -> IO ()

pushLocalFrame :: Int32 -> IO ()

popLocalFrame :: Coercible o (J ty) => o -> IO o

Field accessor functions

Get fields

getObjectField :: Coercible o (J a) => o -> JFieldID -> IO JObject

getBooleanField :: Coercible o (J a) => o -> JFieldID -> IO Word8

getIntField :: Coercible o (J a) => o -> JFieldID -> IO Int32

getLongField :: Coercible o (J a) => o -> JFieldID -> IO Int64

getCharField :: Coercible o (J a) => o -> JFieldID -> IO Word16

getShortField :: Coercible o (J a) => o -> JFieldID -> IO Int16

getByteField :: Coercible o (J a) => o -> JFieldID -> IO CChar

getDoubleField :: Coercible o (J a) => o -> JFieldID -> IO Double

getFloatField :: Coercible o (J a) => o -> JFieldID -> IO Float

Get static fields

getStaticObjectField :: JClass -> JFieldID -> IO JObject

getStaticBooleanField :: JClass -> JFieldID -> IO Word8

getStaticIntField :: JClass -> JFieldID -> IO Int32

getStaticLongField :: JClass -> JFieldID -> IO Int64

getStaticCharField :: JClass -> JFieldID -> IO Word16

getStaticShortField :: JClass -> JFieldID -> IO Int16

getStaticByteField :: JClass -> JFieldID -> IO CChar

getStaticDoubleField :: JClass -> JFieldID -> IO Double

getStaticFloatField :: JClass -> JFieldID -> IO Float

Set fields

setObjectField :: Coercible o (J a) => o -> JFieldID -> JObject -> IO ()

setBooleanField :: Coercible o (J a) => o -> JFieldID -> Word8 -> IO ()

setIntField :: Coercible o (J a) => o -> JFieldID -> Int32 -> IO ()

setLongField :: Coercible o (J a) => o -> JFieldID -> Int64 -> IO ()

setCharField :: Coercible o (J a) => o -> JFieldID -> Word16 -> IO ()

setShortField :: Coercible o (J a) => o -> JFieldID -> Int16 -> IO ()

setByteField :: Coercible o (J a) => o -> JFieldID -> CChar -> IO ()

setDoubleField :: Coercible o (J a) => o -> JFieldID -> Double -> IO ()

setFloatField :: Coercible o (J a) => o -> JFieldID -> Float -> IO ()

Set static fields

setStaticObjectField :: JClass -> JFieldID -> JObject -> IO ()

setStaticBooleanField :: JClass -> JFieldID -> Word8 -> IO ()

setStaticIntField :: JClass -> JFieldID -> Int32 -> IO ()

setStaticLongField :: JClass -> JFieldID -> Int64 -> IO ()

setStaticCharField :: JClass -> JFieldID -> Word16 -> IO ()

setStaticShortField :: JClass -> JFieldID -> Int16 -> IO ()

setStaticByteField :: JClass -> JFieldID -> CChar -> IO ()

setStaticDoubleField :: JClass -> JFieldID -> Double -> IO ()

setStaticFloatField :: JClass -> JFieldID -> Float -> IO ()

Method invocation

callObjectMethod :: Coercible o (J a) => o -> JMethodID -> [JValue] -> IO JObject

callBooleanMethod :: Coercible o (J a) => o -> JMethodID -> [JValue] -> IO Bool

callIntMethod :: Coercible o (J a) => o -> JMethodID -> [JValue] -> IO Int32

callLongMethod :: Coercible o (J a) => o -> JMethodID -> [JValue] -> IO Int64

callCharMethod :: Coercible o (J a) => o -> JMethodID -> [JValue] -> IO Word16

callShortMethod :: Coercible o (J a) => o -> JMethodID -> [JValue] -> IO Int16

callByteMethod :: Coercible o (J a) => o -> JMethodID -> [JValue] -> IO CChar

callDoubleMethod :: Coercible o (J a) => o -> JMethodID -> [JValue] -> IO Double

callFloatMethod :: Coercible o (J a) => o -> JMethodID -> [JValue] -> IO Float

callVoidMethod :: Coercible o (J a) => o -> JMethodID -> [JValue] -> IO ()

callStaticObjectMethod :: JClass -> JMethodID -> [JValue] -> IO JObject

callStaticVoidMethod :: JClass -> JMethodID -> [JValue] -> IO ()

callStaticBooleanMethod :: JClass -> JMethodID -> [JValue] -> IO Bool

callStaticIntMethod :: JClass -> JMethodID -> [JValue] -> IO Int32

callStaticLongMethod :: JClass -> JMethodID -> [JValue] -> IO Int64

callStaticCharMethod :: JClass -> JMethodID -> [JValue] -> IO Word16

callStaticShortMethod :: JClass -> JMethodID -> [JValue] -> IO Int16

callStaticByteMethod :: JClass -> JMethodID -> [JValue] -> IO CChar

callStaticDoubleMethod :: JClass -> JMethodID -> [JValue] -> IO Double

callStaticFloatMethod :: JClass -> JMethodID -> [JValue] -> IO Float

Object construction

newObject :: JClass -> MethodSignature -> [JValue] -> IO JObject

newString :: Ptr Word16 -> Int32 -> IO JString

newObjectArray :: Int32 -> JClass -> IO JObjectArray

newBooleanArray :: Int32 -> IO JBooleanArray

newByteArray :: Int32 -> IO JByteArray

newCharArray :: Int32 -> IO JCharArray

newShortArray :: Int32 -> IO JShortArray

newIntArray :: Int32 -> IO JIntArray

newLongArray :: Int32 -> IO JLongArray

newFloatArray :: Int32 -> IO JFloatArray

newDoubleArray :: Int32 -> IO JDoubleArray

Array manipulation

getArrayLength :: Coercible o (JArray a) => o -> IO Int32

getStringLength :: JString -> IO Int32

data ArrayCopyFailed

Thrown when GetPrimitiveTypeArrayElements returns a null pointer, because it wanted to copy the array contents but couldn't. In this case the JVM doesn't throw OutOfMemory according to the JNI spec.

Constructors

ArrayCopyFailed

Instances

Show ArrayCopyFailed

Defined in Foreign.JNI.Unsafe

Methods

showsPrec :: Int -> ArrayCopyFailed -> ShowS

show :: ArrayCopyFailed -> String

showList :: [ArrayCopyFailed] -> ShowS

Exception ArrayCopyFailed

Defined in Foreign.JNI.Unsafe

Methods

toException :: ArrayCopyFailed -> SomeException

fromException :: SomeException -> Maybe ArrayCopyFailed

displayException :: ArrayCopyFailed -> String

data NullPointerException

A null reference is found where a non-null reference was expected.

Constructors

NullPointerException

Instances

Show NullPointerException

Defined in Foreign.JNI.Unsafe

Methods

showsPrec :: Int -> NullPointerException -> ShowS

show :: NullPointerException -> String

showList :: [NullPointerException] -> ShowS

Exception NullPointerException

Defined in Foreign.JNI.Unsafe

Methods

toException :: NullPointerException -> SomeException

fromException :: SomeException -> Maybe NullPointerException

displayException :: NullPointerException -> String

getBooleanArrayElements :: JBooleanArray -> IO (Ptr Word8)

getByteArrayElements :: JByteArray -> IO (Ptr CChar)

getCharArrayElements :: JCharArray -> IO (Ptr Word16)

getShortArrayElements :: JShortArray -> IO (Ptr Int16)

getIntArrayElements :: JIntArray -> IO (Ptr Int32)

getLongArrayElements :: JLongArray -> IO (Ptr Int64)

getFloatArrayElements :: JFloatArray -> IO (Ptr Float)

getDoubleArrayElements :: JDoubleArray -> IO (Ptr Double)

getStringChars :: JString -> IO (Ptr Word16)

getBooleanArrayRegion :: JBooleanArray -> Int32 -> Int32 -> Ptr Word8 -> IO ()

getByteArrayRegion :: JByteArray -> Int32 -> Int32 -> Ptr CChar -> IO ()

getCharArrayRegion :: JCharArray -> Int32 -> Int32 -> Ptr Word16 -> IO ()

getShortArrayRegion :: JShortArray -> Int32 -> Int32 -> Ptr Int16 -> IO ()

getIntArrayRegion :: JIntArray -> Int32 -> Int32 -> Ptr Int32 -> IO ()

getLongArrayRegion :: JLongArray -> Int32 -> Int32 -> Ptr Int64 -> IO ()

getFloatArrayRegion :: JFloatArray -> Int32 -> Int32 -> Ptr Float -> IO ()

getDoubleArrayRegion :: JDoubleArray -> Int32 -> Int32 -> Ptr Double -> IO ()

setBooleanArrayRegion :: JBooleanArray -> Int32 -> Int32 -> Ptr Word8 -> IO ()

setByteArrayRegion :: JByteArray -> Int32 -> Int32 -> Ptr CChar -> IO ()

setCharArrayRegion :: JCharArray -> Int32 -> Int32 -> Ptr Word16 -> IO ()

setShortArrayRegion :: JShortArray -> Int32 -> Int32 -> Ptr Int16 -> IO ()

setIntArrayRegion :: JIntArray -> Int32 -> Int32 -> Ptr Int32 -> IO ()

setLongArrayRegion :: JLongArray -> Int32 -> Int32 -> Ptr Int64 -> IO ()

setFloatArrayRegion :: JFloatArray -> Int32 -> Int32 -> Ptr Float -> IO ()

setDoubleArrayRegion :: JDoubleArray -> Int32 -> Int32 -> Ptr Double -> IO ()

releaseBooleanArrayElements :: JBooleanArray -> Ptr Word8 -> IO ()

releaseByteArrayElements :: JByteArray -> Ptr CChar -> IO ()

releaseCharArrayElements :: JCharArray -> Ptr Word16 -> IO ()

releaseShortArrayElements :: JShortArray -> Ptr Int16 -> IO ()

releaseIntArrayElements :: JIntArray -> Ptr Int32 -> IO ()

releaseLongArrayElements :: JLongArray -> Ptr Int64 -> IO ()

releaseFloatArrayElements :: JFloatArray -> Ptr Float -> IO ()

releaseDoubleArrayElements :: JDoubleArray -> Ptr Double -> IO ()

releaseStringChars :: JString -> Ptr Word16 -> IO ()

getObjectArrayElement :: forall a o. (IsReferenceType a, Coercible o (J a)) => JArray a -> Int32 -> IO o

setObjectArrayElement :: forall a o. (IsReferenceType a, Coercible o (J a)) => JArray a -> Int32 -> o -> IO ()

Thread management

attachCurrentThreadAsDaemon :: IO ()

detachCurrentThread :: IO ()

runInAttachedThread :: IO a -> IO a

Attaches the calling thread to the JVM, runs the given IO action and then detaches the thread.

If the thread is already attached no attaching and detaching is performed.

data ThreadNotAttached

A JNI call is made from a thread not attached to the JVM.

Constructors

ThreadNotAttached

Instances

Show ThreadNotAttached

Defined in Foreign.JNI.Unsafe

Methods

showsPrec :: Int -> ThreadNotAttached -> ShowS

show :: ThreadNotAttached -> String

showList :: [ThreadNotAttached] -> ShowS

Exception ThreadNotAttached

Defined in Foreign.JNI.Unsafe

Methods

toException :: ThreadNotAttached -> SomeException

fromException :: SomeException -> Maybe ThreadNotAttached

displayException :: ThreadNotAttached -> String

NIO support

data DirectBufferFailed

Constructors

DirectBufferFailed

Instances

Show DirectBufferFailed

Defined in Foreign.JNI.Unsafe

Methods

showsPrec :: Int -> DirectBufferFailed -> ShowS

show :: DirectBufferFailed -> String

showList :: [DirectBufferFailed] -> ShowS

Exception DirectBufferFailed

Defined in Foreign.JNI.Unsafe

Methods

toException :: DirectBufferFailed -> SomeException

fromException :: SomeException -> Maybe DirectBufferFailed

displayException :: DirectBufferFailed -> String

newDirectByteBuffer :: Ptr CChar -> Int64 -> IO JByteBuffer

getDirectBufferAddress :: JByteBuffer -> IO (Ptr CChar)

getDirectBufferCapacity :: JByteBuffer -> IO Int64