public class ReferencePath
extends Object

Reference paths.

A Reference path consists of:

• A starting Java object type,
• A final target object type and target field within that type, and
• An intermediate chain of zero or more reference fields through which an instance of the target type can be reached from an instance of the starting type.

Reference paths can be described by the combination of (a) the starting Java object type, and (b) the path of reference fields and final target field in a String form consisting of field names separated by period (".") characters. All of the fields except the last must be reference fields.

For example, path "parent.age" starting from object type Person might refer to the age of the parent of a Person.

When a complex field appears in a reference path, both the name of the complex field and the specific sub-field being traversed should appear, e.g., "mymap.key.somefield". For set and list fields, the (only) sub-field is named "element", while for map fields the sub-fields are named "key" and "value".

Fields of Sub-Types

In some cases, a field may not exist in a Java object type, but it does exist in a some sub-type of that type. For example:

 @JSimpleClass(storageId = 10)
 public class Person {

     @JSimpleSetField(storageId = 11)
     public abstract Set<Person> getFriends();

     @OnChange("friends.element.name")
     private void friendNameChanged(SimpleFieldChange<NamedPerson, String> change) {
         // ... do whatever
     }
 }

 @JSimpleClass(storageId = 20)
 public class NamedPerson extends Person {

     @JSimpleField(storageId = 21)
     public abstract String getName();
     public abstract void setName(String name);
 }
 

Here the path "friends.element.name" is technically incorrect because "friends.element" has type Person, and "name" is a field of NamedPerson, not Person. However, this will still work as long as there is no ambiguity, i.e., in this example, there are no other sub-types of Person with a field named "name". Note also in the example above the SimpleFieldChange parameter to the method friendNameChanged() necessarily has generic type NamedPerson, not Person.

In cases where multiple sub-types of a common super-type type have fields with the same name but different storage IDs, the storage ID may be explicitly specified as a suffix, for example, "name#123".

Reference paths are created via JSimpleDB.parseReferencePath().