View Full Version : What is the @Path annotation in PropertyAccess<T>?

20 Jan 2012, 8:03 AM
I'm looking at the checkbox table demo here: http://sencha.com/examples-dev/#ExamplePlace:checkboxgrid.

In the source code the child interface of PropertyAccess<Stock> has an @Path annotation on the ModelKeyProvider<Stock> method key(). The annotation value is "symbol" which is also a method in the in the interface.

What does this annotation do? It doesn't appear to be related to sorting. Is it basically telling the grid the method to call to return the "key" of the row? I.e., for identification, and/or what's returned when I ask "what row is selected?" Does this identifier have to be unique?



Colin Alworth
22 Jan 2012, 1:55 PM
@Path is part of the Editor framework, and is used in the same way as it is in that built-in piece of GWT functionality. That is, instead of having the method be named exactly for the property that is to be called, it can be named anything you want, and the annotation contains the actual property or path to the property.

One use case is two methods that access the same property in two different ways. Lets say you had this model object, and wanted access to the `name` property as a model key, as a label, and as a value provider (model key for to use this object in a store, label provider for to easily draw this item in a chart or listview, valueprovider to let a grid modify the property - these are the three basic interfaces that PropertyAccess can build for you). This declaration of PersonPropertyAccess is not valid, as all the methods have the same name, only different return types - not valid java:

public class Person {
public String getName()...
public void setName(String name)...

interface PersonPropertyAccess extends PropertyAccess<Person> {
// wont compile!
LabelProvider<Person> name();
ValueProvider<Person, String> name();
ModelKeyProvider<Person> name();

With the path annotation, you can have different methods that access the same property, with different names:

interface PersonPropertyAccess extends PropertyAccess<Person> {
// valid
LabelProvider<Person> nameLabel();
ValueProvider<Person, String> nameValueProvider();
ModelKeyProvider<Person> nameKey();

The goal is to allow developers to write readable PropertyAccess types that are able to use the same property in different ways.

A second use case is to access nested properties. If Company has a property 'owner' of type Person, and Person has 'name' (as above), sometimes you might want to access the company's owner's name. This can be expressed as the path "owner.name":

public class Company {
public Person getOwner()...
public void setOwner(Person owner)...
interface CompanyProperties extends PropertyAccess<Company> {
ValueProvider<Company, String> ownersName();
and will generate code that allows you to get company.getOwner().getName(), and when trying to set, will call company.getOwner().setName(newName). As in the first example, the method name no longer matters to get correct generated code, and can be any method name that makes sense to the developers.