package org.ovirt.engine.ui.common.idhandler;

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

/**
 * Indicates that the given field will have its DOM element ID set by an {@link ElementIdHandler} implementation.
 * <p>
 * Semantics of this annotation for different types are shown in the following table:
 * <p>
 *
 * <blockquote>
 * <table border="1" cellpadding="5" cellspacing="0">
 * <thead>
 * <tr>
 * <th>Field Type</th>
 * <th>Semantics</th>
 * </tr>
 * </thead> <tbody>
 * <tr>
 * <td>{@link HasElementId}</td>
 * <td>call {@link HasElementId#setElementId setElementId} (used with custom UI object types)</td>
 * </tr>
 * <tr>
 * <td>{@link com.google.gwt.user.client.ui.UIObject}</td>
 * <td>access element through {@linkplain com.google.gwt.user.client.ui.UIObject#getElement getElement} and set its ID using {@link com.google.gwt.user.client.Element#setId
 * setId}</td>
 * </tr>
 * <tr>
 * <td>{@link com.google.gwt.user.client.Element}</td>
 * <td>set element ID using {@link com.google.gwt.user.client.Element#setId setId}</td>
 * </tr>
 * </tbody>
 * </table>
 * </blockquote>
 *
 * <p>
 * Since {@link ElementIdHandler} implementations access field values directly through field declarations, annotated
 * fields should not be {@code private}.
 *
 * @see ElementIdHandler
 * @see HasElementId
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface WithElementId {

    /**
     * Overrides the default field ID that is part of the resulting DOM element ID.
     * <p>
     * When not specified, the name of the annotated field will be taken as the field ID value.
     *
     * @return Custom field ID or an empty string to use the default value.
     */
    String value() default "";

    /**
     * If {@code true}, declared type of the given field will be recursively processed with regard to
     * {@literal @WithElementId} fields. If {@code false}, no further action will be taken on the field type.
     *
     * @return {@code true} if the field type should be recursively processed with regard to {@literal @WithElementId}
     *         fields, {@code false} otherwise.
     */
    boolean processType() default true;

}