package com.atlassian.stash.internal.rest.annotations;

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

/**
 * May be applied to {@code Map<String, Object>} REST resource query parameters to allow them to be correctly deserialized.
 * <p>
 * An example REST method would look like this:
 * <code><pre>
 * &#064;Path("/example")
 * &#064;GET
 * public Response someMethod(&#064;OptionalContext Map&lt;String, Object&gt; context) {
 *     if (context.containsKey("myContextKey")) {
 *         // do something with the context data
 *     }
 *
 *     ...
 * }
 * </pre></code>
 * <p>
 * The {@code Map} parameter <i>must have &lt;String, Object&gt; type arguments</i>.
 * <p>
 *
 * @since 3.9
 * @see com.atlassian.stash.internal.rest.inject.OptionalContextInjectableProvider OptionalContextInjectableProvider
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.PARAMETER)
public @interface OptionalContext {
}
