Package org.dellroad.stuff.vaadin7

Annotation Type ProvidesPropertySort

@Retention(RUNTIME)
@Target({METHOD,FIELD})
@Documented
public @interface ProvidesPropertySort

Declares that a Java method provides either a Comparable value or a Comparator that should be used to determine property sort ordering in a Java class whose instances back the items in a Container.

@ProvidesProperty and @ProvidesPropertySort method annotations can be used to automatically generate a list of PropertyDefs and a PropertyExtractor using a ProvidesPropertyScanner. This happens automatically when using the appropriate constructors of the various Container classes in this package.

This annotation is used in conjunction with the @ProvidesProperty annotation when the value returned by the @ProvidesProperty-annotated method is not Comparable or does not naturally sort as desired. By declaring a @ProvidesPropertySort-annotated method for a property, any arbitrary sorting function can be supplied.

If the annotated method returns a Comparator, then the return value will be used to sort property values; otherwise, the annotated method must return a sub-type of Comparable, in which case the returned value determines how that instance's property value sorts (with null values sorting first). If the method returns neither a Comparator nor a Comparable, an exception is thrown during scanning.

Here is a typical situation where @ProvidesPropertySort is needed: you have a String property containing a formatted Date, but the way the Date strings are formatted does not sort in chronological order. This will usually be the case unless your Date strings are formatted like 2013-03-12, etc.

To address this problem, define a @ProvidesPropertySort-annotated method that provides a properly sorting Comparable value corresponding to the associated property. For example:

 // Container backing object class
 public class User {

     private Date birthday;

     @ProvidesPropertySort             // property name "birthday" is implied by method name
     public Date getBirthday() {
         return this.birthday;
     }
     public void setBirthday(Date birthday) {
         this.birthday = birthday;
     }

     @ProvidesProperty("birthday")     // the actual property value is returned here
     private Label birthdayProperty() {
         return new Label(new SimpleDateFormat("MM/dd/yyyy").format(this.birthday));
     }
 

Alternately, have the @ProvidesPropertySort-annotated method return a Comparator, for example, if you wanted to sort null values last instead of first:

     @ProvidesPropertySort("birthday")
     private static Comparator<User> birthdayComparator() {
         return new Comparator<User>(User user1, User user2) {
              final Date date1 = user1.getBirthday();
              final Date date2 = user2.getBirthday();
              if (date1 == null && date2 != null)
                  return 1;
              if (date1 != null && date2 == null)
                  return -1;
              if (date1 == null && date2 == null)
                  return 0;
              return date1.compareTo(date2);
         };
     }
 

Note that the returned Comparator compares backing instances, not property values, and that methods returning Comparator may be declared static. The returned Comparator may be cached by the implementation.

Some details regarding @ProvidesPropertySort annotations on methods:

• Only non-void methods taking zero parameters are supported; @ProvidesPropertySort annotations on other methods are ignored
• Protected, package private, and private methods are supported.
• @ProvidesPropertySort annotations on interface methods are supported
• If a method and the superclass or superinterface method it overrides are both annotated with @ProvidesPropertySort, then the overridding method's annotation takes precedence.
• If two methods with different names are annotated with @ProvidesPropertySort for the same property name, then the declaration in the class which is a sub-type of the other wins (if the two methods are delcared in the same class, an exception is thrown). This allows subclasses to "override" which method supplies the sort value for a given property.

See Also:

ProvidesProperty, ProvidesPropertyScanner

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	value	Get the name of the Vaadin property.

Element Detail

value

String value

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.

Returns:

property name

Default:

""