michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: package org.mozilla.gecko.mozglue.generatorannotations;
michael@0: 
michael@0: import java.lang.annotation.Retention;
michael@0: import java.lang.annotation.RetentionPolicy;
michael@0: 
michael@0: /**
michael@0:  * This annotation is used to tag methods that are to have wrapper methods generated in the android
michael@0:  * bridge. Such methods will be protected from destruction by Proguard, and allow us to avoid writing
michael@0:  * by hand large amounts of boring boilerplate.
michael@0:  * An annotated Java method will have a corresponding method generated in the android bridge.
michael@0:  * By default, the name of the generated method will be the same as the name of the Java method, with
michael@0:  * the first letter in upper case. The stubName property may be used to specify a custom name for the
michael@0:  * generated method stub.
michael@0:  *
michael@0:  * allowMultithreaded should be used as sparingly as possible - the resulting code will allow the
michael@0:  * Java method to be invoked from the C side from multiple threads. Often, this isn't what is wanted
michael@0:  * and may lead to subtle bugs.
michael@0:  */
michael@0: @Retention(RetentionPolicy.RUNTIME)
michael@0: public @interface WrapElementForJNI {
michael@0:     // Optional parameter specifying the name of the generated method stub. If omitted, the name
michael@0:     // of the Java method will be used.
michael@0:     String stubName() default "";
michael@0: 
michael@0:     // Optional parameter specifying if the generated method should be a static member of AndroidBridge
michael@0:     // By default, an instance member is produced. This is almost always what is wanted.
michael@0:     boolean generateStatic() default false;
michael@0: 
michael@0:     /**
michael@0:      * If set, the generated method stub will support being called from any thread via the use of
michael@0:      * GetJNIForThread. This is rarely useful, at time of writing, as well as possibly risky.
michael@0:      * See information in AndroidBridge.cpp regarding GetJNIForThread.
michael@0:      *
michael@0:      * Did I mention use of this function is discouraged?
michael@0:      */
michael@0:     boolean allowMultithread() default false;
michael@0: 
michael@0:     /**
michael@0:      * If set, the generated stub will not handle uncaught exceptions.
michael@0:      * Any exception must be handled or cleared by the code calling the stub.
michael@0:      */
michael@0:     boolean noThrow() default false;
michael@0: }