org.dellroad.stuff.vaadin8.ProvidesProperty Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of dellroad-stuff-vaadin8 Show documentation
DellRoad Stuff classes related to Vaadin 8.x.
The newest version!

/*
 * Copyright (C) 2022 Archie L. Cobbs. All rights reserved.
 */

package org.dellroad.stuff.vaadin8;

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

/**
 * Provides the information necessary to auto-generate a {@link com.vaadin.data.PropertyDefinition} based on the
 * annotated getter method.
 *
 * 
 * 
 * 
 *
 * 
 * {@link ProvidesProperty @ProvidesProperty} method annotations can be used to automatically generate a
 * {@link com.vaadin.data.PropertySet}'s using a {@link ProvidesPropertyScanner}. The resulting
 * {@link com.vaadin.data.PropertySet} can then be provided to {@link com.vaadin.ui.Grid#withPropertySet Grid.withPropertySet()}
 * for example.
 *
 * 

 * This annotation indicates that a read-only Vaadin {@link com.vaadin.data.PropertyDefinition} having the type
 * equal to the method's return type is accessible by reading that method. Annotated methods must have zero parameters.
 *
 * 

 * For example:
 * 

 * // Container backing object class
 * public class User {
 *
 *     public static final String USERNAME_PROPERTY = "username";
 *     public static final String REAL_NAME_PROPERTY = "realName";
 *
 *     private String username;
 *     private String realName;
 *
 *     public String getUsername() {
 *         return this.username;
 *     }
 *     public void setUsername(String username) {
 *         this.username = username;
 *     }
 *
 *     @ProvidesProperty                     // property name "realName" is implied
 *     public String getRealName() {
 *         return this.realName;
 *     }
 *     public void setRealName(String realName) {
 *         this.realName = realName;
 *     }
 *
 *     @ProvidesProperty(USERNAME_PROPERTY)  // display usernames in fixed-width font
 *     private Label usernameProperty() {
 *         return new Label("<code>" + StringUtil.escapeHtml(this.username) + "</code>", ContentMode.HTML);
 *     }
 * }
 *
 * // Build Grid showing users with auto-generated properties
 * Grid<User> grid = Grid.withPropertySet(new ProvidesPropertyScanner(User.class).getPropertySet());
 * grid.setVisibleColumns(User.USERNAME_PROPERTY, User.REAL_NAME_PROPERTY);
 * ...
 * 
 *
 * 
 * Some details regarding {@link ProvidesProperty @ProvidesProperty} annotations:
 *  

 *  Only non-void methods taking zero parameters are supported; {@link ProvidesProperty @ProvidesProperty}
 *      annotations on other methods are ignored
 *  Protected, package private, and private methods are supported.
 *  {@link ProvidesProperty @ProvidesProperty} annotations declared in super-types (including interfaces) are supported
 *  If a method and the superclass or superinterface method it overrides are both annotated with
 *      {@link ProvidesProperty @ProvidesProperty}, then the overridding method's annotation takes precedence.
 *  
If two methods with different names are annotated with {@link ProvidesProperty @ProvidesProperty} for the same
 *      {@linkplain #value property name}, then the declaration in the class which is a sub-type of the other
 *      wins (if the two classes are equal or not comparable, an exception is thrown). This allows subclasses
 *      to "override" which method supplies a given property.
 *  
 *
 * @see ProvidesPropertyScanner
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.METHOD, ElementType.FIELD })
@Documented
public @interface ProvidesProperty {

    /**
     * Get the name of the Vaadin property.
     *
     * 
     * If this is left unset (empty string), then the bean property name of the annotated bean property "getter" method is used.
     *
     * @return property name
     */
    String value() default "";

    /**
     * Get the caption for the Vaadin property.
     *
     * 
     * If this is left unset (empty string), then the name of the property is used.
     *
     * @return property caption
     */
    String caption() default "";
}