Struct jni::JNIEnv [] [src]

#[repr(C)]
pub struct JNIEnv<'a> { /* fields omitted */ }

FFI-compatible JNIEnv struct. You can safely use this as the JNIEnv argument to exported methods that will be called by java. This is where most of the magic happens. All methods on this object are wrappers around JNI functions, so the documentation on their behavior is still pretty applicable.

Since we're calling into the JVM with this, many methods also have the potential to cause an exception to get thrown. If this is the case, an Err result will be returned with the error kind JavaException. Note that this will not clear the exception - it's up to the caller to decide whether to do so or to let it continue being thrown.

Because null pointers are a thing in Java, this also converts them to an Err result with the kind NullPtr. This may occur when either a null argument is passed to a method or when a null would be returned. Where applicable, the null error is changed to a more applicable error type, such as MethodNotFound.

Methods

impl<'a> JNIEnv<'a>
[src]

[src]

Get the java version that we're being executed from. This is encoded and will need to be checked against constants from the sys module.

TODO: convert this to something more usable.

[src]

Define a new java class. See the JNI docs for more details - I've never had occasion to use this and haven't researched it fully.

[src]

Look up a class by name.

Example

let class: JClass<'a> = env.find_class("java/lang/String");

[src]

Get the superclass for a particular class. As with find_class, takes a descriptor.

[src]

Tests whether class1 is assignable from class2.

[src]

Raise an exception from an existing object. This will continue being thrown in java unless exception_clear is called.

Examples

let _ = env.throw(("java/lang/Exception", "something bad happened"));

Defaulting to "java/lang/Exception":

let _ = env.throw("something bad happened");

[src]

Create and throw a new exception from a class descriptor and an error message.

Example

let _ = env.throw_new("java/lang/Exception", "something bad happened");

[src]

Check whether or not an exception is currently in the process of being thrown. An exception is in this state from the time it gets thrown and not caught in a java function until exception_clear is called.

[src]

Print exception information to the console.

[src]

Clear an exception in the process of being thrown. If this is never called, the exception will continue being thrown when control is returned to java.

[src]

Abort the JVM with an error message.

[src]

Check to see if an exception is being thrown. This only differs from exception_occurred in that it doesn't return the actual thrown exception.

[src]

Create a new instance of a direct java.nio.ByteBuffer.

[src]

Returns the starting address of the memory of the direct java.nio.ByteBuffer.

[src]

Returns the capacity of the direct java.nio.ByteBuffer.

[src]

Turns an object into a global ref. This has the benefit of removing the lifetime bounds since it's guaranteed to not get GC'd by java. It releases the GC pin upon being dropped.

[src]

Deletes the local reference.

Local references are valid for the duration of a native method call. They are freed automatically after the native method returns. Each local reference costs some amount of Java Virtual Machine resource. Programmers need to make sure that native methods do not excessively allocate local references. Although local references are automatically freed after the native method returns to Java, excessive allocation of local references may cause the VM to run out of memory during the execution of a native method.

[src]

Allocates a new object from a class descriptor without running a constructor.

[src]

Look up a method by class descriptor, name, and signature.

Example

let method_id: JMethodID = env.get_method_id(
    "java/lang/String", "substring", "(II)Ljava/lang/String;",
);

[src]

Look up a static method by class descriptor, name, and signature.

Example

let method_id: JMethodID = env.get_static_method_id(
    "java/lang/String", "valueOf", "(I)Ljava/lang/String;",
);

[src]

Look up the field ID for a class/name/type combination.

Example

let field_id = env.get_field_id("com/my/Class", "intField", "I");

[src]

Get the class for an object.

[src]

Call a static method in an unsafe manner. This does nothing to check whether the method is valid to call on the class, whether the return type is correct, or whether the number of args is valid for the method.

Under the hood, this simply calls the CallStatic<Type>MethodA method with the provided arguments.

[src]

Call an object method in an unsafe manner. This does nothing to check whether the method is valid to call on the object, whether the return type is correct, or whether the number of args is valid for the method.

Under the hood, this simply calls the Call<Type>MethodA method with the provided arguments.

[src]

Calls an object method safely. This comes with a number of lookups/checks. It

  • Parses the type signature to find the number of arguments and return type
  • Looks up the JClass for the given object.
  • Looks up the JMethodID for the class/name/signature combination
  • Ensures that the number of args matches the signature
  • Calls call_method_unsafe with the verified safe arguments.

Note: this may cause a java exception if the arguments are the wrong type, in addition to if the method itself throws.

[src]

Calls a static method safely. This comes with a number of lookups/checks. It

  • Parses the type signature to find the number of arguments and return type
  • Looks up the JMethodID for the class/name/signature combination
  • Ensures that the number of args matches the signature
  • Calls call_method_unsafe with the verified safe arguments.

Note: this may cause a java exception if the arguments are the wrong type, in addition to if the method itself throws.

[src]

Create a new object using a constructor. This is done safely using checks similar to those in call_static_method.

[src]

Create a new object using a constructor. Arguments aren't checked because of the JMethodID usage.

[src]

Cast a JObject to a JMap. This won't throw exceptions or return errors in the event that the object isn't actually a map, but the methods on the resulting map object will.

[src]

Get a JavaStr from a JString. This allows conversions from java string objects to rust strings.

This entails a call to GetStringUTFChars and only decodes java's modified UTF-8 format on conversion to a rust-compatible string.

[src]

Get a pointer to the character array beneath a JString. This is in Java's modified UTF-8 and will leak memory if release_string_utf_chars is never called.

[src]

Unpin the array returned by get_string_utf_chars.

[src]

Create a new java string object from a rust string. This requires a re-encoding of rusts real UTF-8 strings to java's modified UTF-8 format.

[src]

Get the length of a java array

[src]

Construct a new array holding objects in class element_class. All elements are initially set to initial_element.

This function returns a local reference, that must not be allocated excessively. See Java documentation for details.

[src]

Returns an element of the jobjectArray array.

[src]

Sets an element of the jobjectArray array.

[src]

Create a new java byte array from a rust byte slice.

[src]

Converts a java byte array to a rust vector of bytes.

[src]

Create a new java boolean array of supplied length.

[src]

Create a new java byte array of supplied length.

[src]

Create a new java char array of supplied length.

[src]

Create a new java short array of supplied length.

[src]

Create a new java int array of supplied length.

[src]

Create a new java long array of supplied length.

[src]

Create a new java float array of supplied length.

[src]

Create a new java double array of supplied length.

[src]

Copy elements of the java boolean array from the start index to the buf slice.

[src]

Copy elements of the java byte array from the start index to the buf slice.

[src]

Copy elements of the java char array from the start index to the buf slice.

[src]

Copy elements of the java short array from the start index to the buf slice.

[src]

Copy elements of the java int array from the start index to the buf slice.

[src]

Copy elements of the java long array from the start index to the buf slice.

[src]

Copy elements of the java float array from the start index to the buf slice.

[src]

Copy elements of the java double array from the start index to the buf slice.

[src]

Copy the contents of the buf slice to the java boolean array at the start index.

[src]

Copy the contents of the buf slice to the java byte array at the start index.

[src]

Copy the contents of the buf slice to the java char array at the start index.

[src]

Copy the contents of the buf slice to the java short array at the start index.

[src]

Copy the contents of the buf slice to the java int array at the start index.

[src]

Copy the contents of the buf slice to the java long array at the start index.

[src]

Copy the contents of the buf slice to the java float array at the start index.

[src]

Copy the contents of the buf slice to the java double array at the start index.

[src]

Get a field without checking the provided type against the actual field.

[src]

Set a field without any type checking.

[src]

Get a field. Requires an object class lookup and a field id lookup internally.

[src]

Set a field. Does the same lookups as get_field and ensures that the type matches the given value.

[src]

Surrenders ownership of a rust object to Java. Requires an object with a long field to store the pointer. The Rust value will be wrapped in a Mutex since Java will be controlling where it'll be used thread-wise. Unsafe because it leaks memory if take_rust_field is never called (so be sure to make a finalizer).

DO NOT make a copy of the object containing one of these fields. If you've set up a finalizer to pass it back to Rust upon being GC'd, it will point to invalid memory and will likely attempt to be deallocated again.

[src]

Gets a lock on a Rust value that's been given to a Java object. Java still retains ownership and take_rust_field will still need to be called at some point. Checks for a null pointer, but assumes that the data it ponts to is valid for T.

[src]

Take a Rust field back from Java. Makes sure that the pointer is non-null, but still assumes that the data it points to is valid for T. Sets the field to a null pointer to signal that it's empty.

This will return an error in the event that there's an outstanding lock on the object.

[src]

Lock a Java object. The MonitorGuard that this returns is responsible for ensuring that it gets unlocked.

[src]

Returns underlying sys::JNIEnv interface.

Trait Implementations

impl<'a> From<*mut JNIEnv> for JNIEnv<'a>
[src]

[src]

Performs the conversion.