Skip to content

Commit 9c0ef31

Browse files
mp911demp911de
committed
Documentation
1 parent e143291 commit 9c0ef31

File tree

1 file changed

+152
-3
lines changed

1 file changed

+152
-3
lines changed

‎src/main/antora/modules/ROOT/pages/property-paths.adoc‎

Lines changed: 152 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,125 @@
1+
[[property-paths]]
2+
= Property Paths
3+
4+
This chapter covers the concept of property paths.
5+
Property paths are a form of navigation through domain classes to apply certain aspects in the context of interacting with the model.
6+
Application code provides property paths to data access components to express intents such as selection of properties within a query, forming predicates, or applying sorting.
7+
A property path originates from a owning type and can consist of one to many segments.
8+
9+
In Spring Data, the classes that form the backbone of your persistent domain model and that are accessed through Spring Data called entities.
10+
An entry point for the object graph is called aggregate root in alignment with domain-driven design.
11+
12+
[TIP]
13+
====
14+
Spring Data considers domain types to be entities, more specifically aggregates.
15+
So you will see the term "entity" used throughout the documentation that can be interchanged with the term "domain type" or "aggregate".
16+
17+
As you might have noticed in the introduction it already hinted towards domain-driven concepts.
18+
We consider domain objects in the sense of DDD.
19+
Domain objects have identifiers (otherwise these would be identity-less value objects), and we somehow need to refer to identifiers when working with certain patterns to access data.
20+
Referring to identifiers will become more meaningful as we talk about repositories and query methods.
21+
====
22+
23+
[[property-path-overview]]
24+
== Property Path Overview
25+
26+
Let's start from a domain model, consider the simple domain model consisting of `Person` and `Address` classes with a couple of properties each:
27+
28+
.Domain model
29+
[tabs]
30+
======
31+
Java::
32+
+
33+
[source,java,role="primary"]
34+
----
35+
class Person {
36+
String firstname, lastname;
37+
int age;
38+
Address address;
39+
List<Address> previousAddresses;
40+
41+
String getFirstname() { … }; // other property accessors omitted for brevity
42+
43+
}
44+
45+
class Address {
46+
String city, street;
47+
48+
// accessors omitted for brevity
49+
50+
}
51+
----
52+
53+
Kotlin::
54+
+
55+
[source,kotlin,role="secondary"]
56+
----
57+
class Person {
58+
var firstname: String? = null
59+
var lastname: String? = null
60+
var age: Int = 0
61+
var address: Address? = null
62+
var previousAddresses: List<Address> = emptyList()
63+
}
64+
65+
class Address {
66+
var city: String? = null
67+
var street: String? = null
68+
}
69+
----
70+
======
71+
72+
Property paths let you express references to properties using dot-path notation, for example when declaring sort orders:
73+
74+
.Sorting
75+
[source,java]
76+
----
77+
Sort.by("firstname", "lastname")
78+
----
79+
80+
Dot-path notation addresses individual properties that are separated by a dot `.`.
81+
Methods accepting a `String` property path typically allow usage of single-segment property paths (i.e. reference to a top-level property) or multi-segment properties unless otherwise indicated.
82+
83+
Dot-path traversal into properties considers the component type of array and collection properties allowing references into the actual type for a simple navigation across collection-like types.
84+
85+
----
86+
Sort.by("address.city") <1>
87+
88+
Sort.by("previousAddresses") <2>
89+
90+
Sort.by("previousAddresses.city") <3>
91+
----
92+
93+
<1> Sort by the `city` of the `address` object.
94+
<2> Sort by the `Person.previousAddresses` collection.
95+
Applicable for technologies that support sorting by arrays or lists
96+
<3> Sort by the `city` of any previous address.
97+
98+
String-based property paths are simple and widely applicable because they do not require additional dependencies.
99+
There are various tradeoffs to consider:
100+
101+
* Simple and flexible: Generalized and simple usage by expressing a property reference as string literal or constant.
102+
* Untyped: String paths do not carry compile-time type information and do not have a dependency on the underlying domain type.
103+
* Context-less: Without the associated domain type, string literals are easy to miss when renaming or refactoring the model.
104+
105+
For better refactoring safety and stronger type consistency, prefer type-safe property references that associate property paths with type information, enabling IDE refactoring and compiler validation.
106+
<<type-safe-property-references>> shows how to use method references to express property paths in a type-safe manner.
107+
108+
NOTE: For advanced usage: Property paths are translated to javadoc:org.springframework.data.core.PropertyPath[], read more about <<property-path-internals>>.
109+
110+
[[property-path-internals]]
111+
=== Property Path Internals
112+
113+
The `org.springframework.data.core` package is the basis for Spring Data's navigation across domain classes.
114+
The javadoc:org.springframework.data.core.TypeInformation[] inteface provides type introspection capable of resolving the type of a property. javadoc:org.springframework.data.core.PropertyPath[] represents a textual navigation path through a domain class.
115+
Together they provide:
116+
117+
* Type introspection and resolution of generics
118+
* Creation and validation of property paths
119+
* Actual type resolution for properties that hold a objects of an actual type such as collections and maps
120+
1121
[[type-safe-property-references]]
2-
= Type-safe Property References
122+
== Type-safe Property References
3123

4124
Type-safe property references address a common source of friction in data access code: The reliance on literal, dot-separated property path strings.
5125
Such stringly-typed references are fragile during refactoring difficult to identify as they often lack context.
@@ -9,12 +129,28 @@ A property path is a simple, transportable representation of object navigation.
9129
When expressed as a method-reference the compiler participates in validation and IDEs provide meaningful refactoring support.
10130
The result is code that reads naturally, fails fast on renames, and integrates cleanly with existing query and sorting abstractions, for example:
11131

12-
[source,java]
132+
[tabs]
133+
======
134+
Java::
135+
+
136+
[source,java,role="primary"]
13137
----
14138
TypedPropertyPath.of(Person::getAddress)
15139
.then(Address::getCity);
16140
----
17141
142+
Kotlin::
143+
+
144+
[source,kotlin,role="secondary"]
145+
----
146+
TypedPropertyPath.of<Person, Address>(Person::address)
147+
.then(Address::city);
148+
149+
// Kotlin Exension
150+
KTypedPropertyPath.of(Person::address).then(Address::city)
151+
----
152+
======
153+
18154
The expression above constructs a path equivalent to `address.city` while remaining resilient to refactoring.
19155
Property resolution is performed by inspecting the supplied method references; any mismatch becomes visible at compile time.
20156

@@ -29,10 +165,23 @@ Sort.by("address.city", "address.street")
29165
You can also use it inline for operations like sorting:
30166

31167
.Type-safe Property Path
32-
[source,java]
168+
[tabs]
169+
======
170+
Java::
171+
+
172+
[source,java,role="primary"]
33173
----
34174
Sort.by(Person::getFirstName, Person::getLastName);
175+
176+
----
177+
178+
Kotlin::
179+
+
180+
[source,kotlin,role="secondary"]
181+
----
182+
Sort.by(Person::firstName, Person::lastName);
35183
----
184+
======
36185

37186
`TypedPropertyPath` can integrate seamlessly with query abstractions or criteria builders:
38187

0 commit comments

Comments
 (0)