Skip to content

Home

Jump to bottom
Alexander-- edited this page Apr 6, 2017 · 19 revisions

Processor options

To modify the behavior of aidl2 annotation processor you can pass following processor options to it:

  • aidl2_log_to_files enables logging to log file. If you specify a filename, that location will be used, otherwise expect a processor.log to be created inside directory with generated source files
  • aidl2_dontwarn suppresses all aidl2-specific warnings/errors (about passing Object as parameter etc.) Standard Javac wanrnings/errors and errors, caused by incorrect interface definition, won't be affected.

Miscalleous features

You can perform "oneway" Binder transactions by annotating a method with @OneWay.

You can name your interface differently from canonical AIDL name by passing string parameter to @AIDL

Annotating a method with @SuppresWarnings will carry the annotation over to generated classes (please create an issue, if you'd like for other annotations to be transplanted the same way).

In addition to marshalling data a code generated by Google's AIDL tool writes interface descriptor to Parcel and veryfies it during each transaction. You can pass true to insecure parameter of @AIDL to stop AIDL2 from doing that too (but make sure to read about the purpose of that feature first).

You can annotate a metod or parameter with @NotNull/@NonNull annotations to prevent extra null checks and reduce amount of space, taken by parameters, especially arrays/collections in Parcel. Doing so also has an effect of crashing with NullPointerException if the other side does pass a null value to you. Effect of annotations is applied recursivly: annotating a method as @NotNull will mark it's parameters as non-null by default, annotating a List parameter will apply the same qualifier to it's contents.

You can use custom transaction ids for individual via the @Call annotation.

Stability of generated code

Note: this section is directed towards people, who may want to distribute IPC stubs in libraries. If you simply use AIDL2 for IPC communications within a single app, you can safely ignore everything written here.

Like the aidl tool this library attempts to keep generated code stable and cross-compatible between library versions and even separate compiler invocations.

Many subtle changes to the way user's Java code is written will affect runtime ABI of generated code:

  1. Marking a type as secure/insecure
  2. Marking individual methods and parameters as nullable/non-null
  3. Changing order of methods
  4. Making one of involved types final/abstract
  5. Adding/removing constructor of involved Collection type

Furthermore, the library itself is still unstable and the way types are written to Parcel may change.

It is recommended that you bundle both sides of generated code (server and client stubs) in same library package to avoid ABI compatibility issues.

AIDL2 will try to help you by calculating a rough "hash" of library interface and checking it at runtime, but don't rely on that too much: the hashing is imperfect and does not account for internal structure of Parcelable classes and other non-primitive arguments. You can disable it using aidl2_use_versioning processor argument.

Limitations/Known Issues

Following features of aidl tool are not (yet?) supported:

  • Pure out and inout parameters
  • Generating C++ code

Aidl2 might run under Eclipse Java compiler, but some features will not work (in particular generics and wildcards in method parameters are buggy due to limitations of Eclipse compiler).

In addition there is a number of known limitations, that aren't currently on roadmap:

  • Checked exceptions are pretty much not supported.

  • JDK 6 may work, but isn't supported, since it is no longer supported by it's creator and developers of Javapoet.

  • Nullability annotations on types and type arguments (aka Java 8 type annotations, don't mix up with ordinary parameter annotations) are supported, but won't have any effect on generated code without JDK 9 (see https://github.com/chdir/aidl2/issues/2).

  • Due to permissive nature of AIDL2 interfaces it may be possible to (accidentally) serialize an inner/anonymous class or lambda. All usual caveats of serializing such classes will apply. This applies only to subtypes of Serializable/Externalizable.

  • Some of generated files may contain redundant casts due to limitations of Java compilers or way AIDL2 handles certain types. You are highly unlikely to see those unless you use complex generic types.

  • Generated implementations of interfaces, containing intersection types, may fail to compile with source versions before Java 8.

    // this will fail to compile with JDK 7
<T extends Parcelable & Runnable> void methodWithIntersectionArgument(T param);

    This is because implementing those requires support for either advanced type inference or casts to intersection, both of which didn't exist until Java 8.

  • Nonsential intersection types like Boolean & Runnable aren't detected. I believe, that handling those should be responsibility of compiler.

Clone this wiki locally