org.jsimpledb

Class ReferencePath

java.lang.Object

org.jsimpledb.ReferencePath

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().

See Also:

JSimpleDB.parseReferencePath()

Method Summary

Modifier and Type	Method and Description
int[]	getReferenceFields() Get the storage IDs of the reference fields in this path.
Class<?>	getStartType() Get the Java type of the object at which this path starts.
int	getTargetField() Get the storage ID associated with the target field in the target object type.
Set<TypeToken<?>>	getTargetFieldTypes() Get the Java type(s) corresponding to the field at which this path ends.
int	getTargetSuperField() Get the storage ID associated with the complex field containing the target field a sub-field, in the case that the target field is a sub-field of a complex field.
Class<?>	getTargetType() Get the Java type of the object at which this path ends.
Set<Class<?>>	getTargetTypes() Get the possible Java types of the object at which this path ends.
String	toString() Get the String form of the path associated with this instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getStartType

public Class<?> getStartType()

Get the Java type of the object at which this path starts.

If there are zero reference fields in this path, then this will equal the target object type, or possibly a super-type if the target field exists only in a sub-type.

Returns:

the Java type at which this reference path starts

getTargetType

public Class<?> getTargetType()

Get the Java type of the object at which this path ends.

The returned type will be as narrow as possible while still including all possibilities, but note that it's possible for there to be multiple candidates for the "target type", none of which is a sub-type of any other. To retrieve all such target types, use getTargetTypes(); this method just invokes Util.findLowestCommonAncestorOfClasses() on the result.

Returns:

the Java type at which this reference path ends

getTargetTypes

public Set<Class<?>> getTargetTypes()

Get the possible Java types of the object at which this path ends.

If there are zero reference fields in this path, then this method will return only the Java type of the starting object type, or possibly a sub-type if the target field exists only in a sub-type.

The returned type(s) will be maximally narrow. The set will contain only one element if a unique such type exists, otherwise it will contain multiple mutually incompatible supertypes of the object types at which this path ends.

Returns:

the Java type(s) at which this reference path ends

getTargetFieldTypes

public Set<TypeToken<?>> getTargetFieldTypes()

Get the Java type(s) corresponding to the field at which this path ends.

The returned type(s) will be maximally narrow. The set will contain only one element if a unique such type exists, otherwise it will contain multiple mutually incompatible supertypes of the object types at which this path ends. The latter case can only occur when the field is a reference field, and there are multiple Java model classes compatible with the field's type.

Returns:

the type of the field at which this reference path ends

getTargetField

public int getTargetField()

Get the storage ID associated with the target field in the target object type.

This is just the storage ID of the last field in the path.

Returns:

the storage ID of the field at which this reference path ends

getTargetSuperField

public int getTargetSuperField()

Get the storage ID associated with the complex field containing the target field a sub-field, in the case that the target field is a sub-field of a complex field.

Returns:

target field's complex super-field storage ID, or zero if the target field is not a complex sub-field

getReferenceFields

public int[] getReferenceFields()

Get the storage IDs of the reference fields in this path.

The path may be empty, i.e., zero references are traversed in the path.

Otherwise, the first field is a field in the starting object type and the last field is field in some object type that refers to the target object type.

Returns:

zero or more reference field storage IDs

toString

public String toString()

Get the String form of the path associated with this instance.

Overrides:

toString in class Object