Repository: flutter
Issue: [pigeon] Option to add checked exceptions to the method signature in generated JAVA interface.
Labels: c: new feature,package,c: proposal,team-ecosystem,p: pigeon,P3,triaged-ecosystem

## Use case

I would like to wrap Android's `AssetManager.list` method which potentially throws a `IOException` (see documentation: https://developer.android.com/reference/android/content/res/AssetManager#list(java.lang.String)). 

What I did is write the following Pigeon interface in Dart:
```dart
@HostApi(dartHostTestHandler: 'TestAssetManagerHostApi')
abstract class AssetManagerHostApi {
  List<String> list(String path);
}
```

This would generate the following JAVA interface:
```java
  /** Generated interface from Pigeon that represents a handler of messages from Flutter.*/
  public interface AssetManagerHostApi {
    List<String> list(String path);

    /** The codec used by AssetManagerHostApi. */
    static MessageCodec<Object> getCodec() {
      return AssetManagerHostApiCodec.INSTANCE;
    }

    /** Sets up an instance of `AssetManagerHostApi` to handle messages through the `binaryMessenger`. */
    static void setup(BinaryMessenger binaryMessenger, AssetManagerHostApi api) {
      {
        BasicMessageChannel<Object> channel =
            new BasicMessageChannel<>(binaryMessenger, "dev.flutter.pigeon.AssetManagerHostApi.list", getCodec());
        if (api != null) {
          channel.setMessageHandler((message, reply) -> {
            Map<String, Object> wrapped = new HashMap<>();
            try {
              ArrayList<Object> args = (ArrayList<Object>)message;
              String pathArg = (String)args.get(0);
              if (pathArg == null) {
                throw new NullPointerException("pathArg unexpectedly null.");
              }
              List<String> output = api.list(pathArg);
              wrapped.put("result", output);
            }
            catch (Error | RuntimeException exception) {
              wrapped.put("error", wrapError(exception));
            }
            reply.reply(wrapped);
          });
        } else {
          channel.setMessageHandler(null);
        }
      }
    }
  }
```

And I added the following implementation:
```java
public class AssetManagerHostApiImpl implements AssetManagerHostApi {

  private final Context context;
  
  public AssetManagerHostApiImpl(Context context) {
    this.context = context;
  }
  
  @Override
  public List<String> list(String path) {
    String[] paths = context.getAssets().list(path);
    return Arrays.asList(paths);
  }
}
```

This won't compile because the `context.getAssets().list(path)` can throw the checked `IOException` and the compiler is complaining that I should either handle the exception or add it to the method signature.

At the moment I can't add the exception to the method signature as this would require me to also update the generated interface (which if I did will get reset each time I regenerate the pigeon interface). Also if I would handle this inside my `list()` implementation I would loose valuable information which I would really like to communicate to Dart.

## Proposal

Have the option to add an attribute to the Dart Pigeon interface which tells the code generator to add the specified checked exception to the methods signature and let the generated catch block convert the exception into an error result.

Something like this:

```dart
@HostApi(dartHostTestHandler: 'TestAssetManagerHostApi')
abstract class AssetManagerHostApi {
  @CheckedException('IOException')
  List<String> list(String path);
}
```

Which will result in the following generated JAVA interface method (note the added `throws IOException` in the method signature):

```java
  /** Generated interface from Pigeon that represents a handler of messages from Flutter.*/
  public interface AssetManagerHostApi {
    List<String> list(String path) throws IOException;
    
    // Rest of the generated JAVA interface...
  }
```

/cc @gaaclarke