Skip to content

Home

Jump to bottom
AlexanderR edited this page May 10, 2016 · 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

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.

Stability of generated code

Unlike the aidl tool this library does not currently offer any gurantees, that generated code will remain stable and cross-compatible between library versions and even separate compiler invocations.

Many subtle changes to the way user's Java code is written can 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 anytime.

Naturally, you are expected to include generated code in library package, so those qualities of generated code are irrelevant.

Limitations/Known Issues

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

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

Aidl2 won't work with Google's Jack and other compilers incompatible with post-Java 5 language. It is not tested for compatibility with Eclipse Java compiler, but any feedback is welcome.

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 are supported, but won't work, because Android standard library does not have ElementType.TYPE_USE and ElementType.TYPE_PARAMETER.

  • 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