Typed Exceptions

[mahesh-hegde]

Status Quo:

• Any exception in JNI would be thrown as JniException. Since resource management of references is hard with exceptional control flow, we serialize the exception message and stack trace into a string and throw it as a single type JniException in dart.

Problems with this approach:

• It's hard to catch specific exception in this way. Let's say I only want to catch IOException, there's no way to do this except inspecting the string representation.
• Some exception types carry additional information along with the message, which will be lost.

Implementation options

1. Exceptions as first-class JNI objects:

   • Map each Exception to a JObject subclass, as we did before.
   • keep a central registry at package:jni which maps qualfiied name (FQN) of Java Exception types to their constructors. This is required because we must decide the type of JThrowable when we are rethrowing it in Dart.
   • Provide convenience methods to obtain stack trace.

2. Generate marker exception classes which correspond to Java exception types.

   • These are not JObject subclasses, and hold no JNI references. Can directly subclass current JniException. All functionality would be in JniException, and subclass is just a marker.
   • But still need a central registry to look up the FQN of the exception object and throw appropriate type.
   • Pro: resource management. Con: lose access to specialized methods of few exception types.

[mahesh-hegde]

I have an initial design for this.

Initial Design:

Exceptions will be mapped to instances of JObject subclasses corresponding to the class of the exception.

If the corresponding exception class is not available (i.e neither generated as a binding, nor linked from another JNIgen module using config), it will be mapped to a generic JNIException consisting of a stack trace and error message obtained from toString().

However, we need to override toString on these types, because we want to print Java stack trace on error.

So we create an intermediate class, JExceptionObject which overrides toString, and also ensure all classes directly or indirectly extending Exception or Error in Java inherit this.

This analysis, of whether a type is exception type, may prove to be impossible at times. We add another condition.

A type will be mapped as subclass of JExceptionObject iff either

1. It's provably a subclass of Java Exception type Throwable.

OR

2. It's names ends in Exception or Error.

this can be configured as regex from YAML.

exceptions:
  exception_types:
    - ".*Problem"
    - com.company.MyCustomErrorTypeWithCustomSuffix
  name_heuristic: false ## disable mapping based on suffix alone (`Exception` or `Error`).

Marker types

Let's say we bind a library, we want to catch java.io.FileNotFoundException to distinguish it from other exceptions. But java.io.FileNotFoundException is not in the set of bindings to be generated.

In such cases we give an option to specify exception marker types, which extend the generic JException with no overridden functionality.

exceptions:
  generate_markers:
    - 'java.io.FileNotFoundException'

Resource management

This design opts for keeping JObjects in Exception objects, which is useful to access properties of custom exception types. For instance URISyntaxException gives getIndex() and getInput().

Also I believe this aligns with our objective of being faithful to source Java API as much as possible, without adding additional abstraction on dart side.

Due to keeping the JObject reference, it's on the caller to dispose the JExceptionObject so obtained. I suppose NativeFinalizer is sufficient to take care of this.

implementation

Mapping of exceptions thrown in Java, to wrapper / marker types in Dart is a dynamic process. Only once an exception is thrown, we get to determine what's the type of the exception.

I think here's a choice we need to make:

1. Maintain a central registry mapping from class FQN (can be implemented as a package:jni function). Upon library initialization, which happens upon first access of a library symbol (and already involves loading the DLL), register the mapping from FQN -> Exception class constructor.

   But this design is not "correct". If you get a libraryB.Exception before ever accessing libraryB, you will get a generic JException

2. Make the library initialization explicit. This will end up requiring the user to register each JNI binding library before using them. We can just use a function of this form. ¹

Jni.initializeLibraries([
  libraryA.init,
  libraryB.init,
  libraryC.init,
]);

3. Any other ideas?

cc: @dcharkes @HosseinYousefi @mkustermann

Footnotes

1. For migration & ease of use, we can always add a check on first access. ↩

[dcharkes]

Maintain a central registry mapping from class FQN (can be implemented as a package:jni function). Upon library initialization, which happens upon first access of a library symbol (and already involves loading the DLL), register the mapping from FQN -> Exception class constructor.

• keep a central registry at package:jni which maps qualfiied name (FQN) of Java Exception types to their constructors. This is required because we must decide the type of JThrowable when we are rethrowing it in Dart.

Could you elaborate why do we need this for exceptions, but not for return values of methods?

[mahesh-hegde]

Could you elaborate why do we need this for exceptions, but not for return values of methods?

For return values, the mapping is statically known. If I have a method getTitle, I statically know it returns a java.lang.String.

In contrast, any type of exception can get thrown during execution of any method. Once you get an exception result from a method, let's say called, openConfigurationFile(), all you have is a jthrowable a.k.a Pointer<Void>.

To differentiate whether it's a say FileNotFoundException, URISyntaxException, IllegalArgumentException, or OutOfMemoryError, we must do a runtime check, to find out what is the class of the jthrowable we got.

But we want to distinguish exceptions based on their source type, so that we can, for example, only catch FileNotFoundException and retry. So this check is necessary.

Feel free to correct me if you can think of a way around it.

[dcharkes]

I was thinking that if we have the list of classes that we generate for already, then we can't we use that list of classes? Is it because we only know the fully qualified name and thus only what wrapper to instantiate at runtime?

This is actually somewhat similar to if B extends A, a method returns A statically but B at runtime, we return a JNIgen generated A to the user and the Dart is B check would fail, even though the backing object in Java is a B. Or am I mistaken?

If I understand you correctly, one way to fix both these issues is to construct a Map<String fullyQualifiedName, JObject Function() constructor> so that we can instantiate the a Dart object of the right type. And constructing this map requires some kind of global init.

[mahesh-hegde]

This is actually somewhat similar to if B extends A, a method returns A statically but B at runtime, we return a JNIgen generated A to the user and the Dart is B check would fail, even though the backing object in Java is a B. Or am I mistaken?

Yeah this is similar. The static return type of method is A, and to instantiate B with a runtime check is not a good abstraction. This should be rather solved with a helper method [#266]. Anyway A is precise enough for most use case.

In case of exceptions though, only type we statically know is Throwable, which is very imprecise. Since exception handling is much rarer than method return, and we need more precision than this, using a runtime check for concrete type could be a good idea.

If I understand you correctly, one way to fix both these issues is to construct a Map<String fullyQualifiedName, JObject Function() constructor> so that we can instantiate the a Dart object of the right type. And constructing this map requires some kind of global init.

Right.

[dcharkes]

I'd say that if we solve it for exceptions, we should consider doing the same for normal objects (unless it's prohibitively expensive, then maybe we should add a castToRuntimeType or something).

I assume we wouldn't need this for checked exceptions, because we know the list of exceptions then. (That is, if our parsers see that data.)

But this design is not "correct". If you get a libraryB.Exception before ever accessing libraryB, you will get a generic JException

We could potentially detect with the library imports that one library is using another one.
Or we should make it such that in their init function someone can call another init function.
I think we should try to avoid having the end user having to list the transitive closure of all JNIgen-generated packages.

[mahesh-hegde]

unless it's prohibitively expensive

We should consider tree shaking for a small set of exception types vs all types? Keeping MyClass.fromRef in a map implies it can be called dynamically.

Besides, Its overhead will surely exceed that of method call itself. I don't think you can do it without a JNI method call to getClass() then getName(). Even if we find a way to do getClassName in below snippet with 1 JNI call, the strings result in some more calls. (I am not aware of any integer based "primary key" ID mechanism for classes, so we have to use FQN).

JObjectPtr className = getClassName(reference);
String name = className.toDartString(deleteOriginal: true);
A Function(JObjectPtr) constructor = registry.lookup(name);
return constructor(reference);

Subtyping complicates it further. If you return a private subtype of B called Bx, you should either traverse Bx's parents until you obtain a known class, which will be even more expensive to do on happy path. (I am not sure we should do it on exception path either, it depends on how pervasive private subtypes are).

castToRuntimeType

We can add an instanceOf(type) and isSameType(otherJobject) instead. #639 .

Or we should make it such that in their init function someone can call another init function.

Why didn't I think of this 😃 This should solve the problem. Thanks.

I assume we wouldn't need this for checked exceptions, because we know the list of exceptions then. (That is, if our parsers see that data.

For the functions which throw checked exceptions, we still need to do some matching to check the type.

I think you meant something like this.

// Serial matchiing
final exception = result.exception
if (JNIEnv.isAssignable(exception, Exception1_jclass)) {
  return Exception1.fromRef(exception);
} else if (JNIEnv.isAssignable(exception, Exception2_jclass)) {
  return Exception2.fromRef ...
} else if (...) {
...
...
...
} else {
  // Could be an unchecked exception not mentioned in the signature.
  return exceptionFromLookup(exception);
}

This is cumbersome, and more generated code. Not to mention now we have to handle the lifecycle of Exception1_jclass etc..

Another thing is if you have a method declared as throws IOException, but want to catch a more specific one like FileNotFoundException, this is not helpful.

So I think we should rather use the same mechanism for both.

Even with a method having single checked exception, you can still have other unchecked exceptions from 10 methods deep.

Is there a better way you thought of with checked exceptions?

[HosseinYousefi]

We know which exceptions can be thrown from a method, right?

void f() throws IOException, URISyntaxException, IllegalArgumentException {
  // ...
}

Can we throw something like Union3<IOException, URISyntaxException, IllegalArgumentException>, and then if the exception is found to be IOException, you can check if e.instanceOf(FileNotFoundException.type) to get a more exact type.

[mahesh-hegde]

I am aiming for a usage like:

on (FileNotFoundException) catch e {

}

Maybe this is not essential at all, as you said.

[mahesh-hegde]

We know which exceptions can be thrown from a method, right?

Technicaly, we know a subset of them. All exceptions declared in method signature AND any unchecked exception.

[HosseinYousefi]

I am aiming for a usage like:

on (FileNotFoundException) catch e {

}

Maybe this is not essential at all, as you said.

If we write code like on X catch e then surely we know X. Probably we can write code that uses X.type instead and provide nice enough helper methods on the thrown object.

try {
  Foo.bar();
} on JException catch (e) {
  if (e.instanceOf(X.type)) {
    e.castTo(X.type, deleteOriginal: true).usefulMethod();
  }
}

Do you think it's worth the complications to change the above code to this?

try {
  Foo.bar();
} on X catch (e) {
  e.usefulMethod();
}