/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

package org.mozilla.gecko.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * This annotation is used to tag methods that are to have wrapper methods generated.
 * Such methods will be protected from destruction by ProGuard, and allow us to avoid
 * writing by hand large amounts of boring boilerplate.
 */
@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.CONSTRUCTOR})
@Retention(RetentionPolicy.RUNTIME)
public @interface WrapForJNI {
    /**
     * Skip this member when generating wrappers for a whole class.
     */
    boolean skip() default false;

    /**
     * Optional parameter specifying the name of the generated method stub. If omitted,
     * the capitalized name of the Java method will be used.
     */
    String stubName() default "";

    /**
     * Action to take if member access returns an exception.
     * - "abort" will cause a crash if there is a pending exception.
     * - "ignore" will not handle any pending exceptions; it is then the caller's
     *   responsibility to handle exceptions.
     * - "nsresult" will clear any pending exceptions and return an error code; not
     *   supported for native methods.
     */
    String exceptionMode() default "abort";

    /**
     * The thread that the method will be called from.
     * One of "any", "gecko", or "ui". Not supported for fields.
     */
    String calledFrom() default "any";

    /**
     * The thread that the method call will be dispatched to.
     * - "current" indicates no dispatching; only supported value for fields,
     *   constructors, non-native methods, and non-void native methods.
     * - "gecko" indicates dispatching to the Gecko XPCOM (nsThread) event queue.
     * - "gecko_priority" indicates dispatching to the Gecko widget
     *   (nsAppShell) event queue; in most cases, events in the widget event
     *   queue (aka native event queue) are favored over events in the XPCOM
     *   event queue.
     * - "proxy" indicates dispatching to a proxy function as a function object; see
     *   widget/jni/Natives.h.
     */
    String dispatchTo() default "current";

    /**
     * Generate a getter instead of a literal. Only supported for static final fields.
     */
    boolean noLiteral() default false;
}
