|
| 1 | +[[projections]] |
| 2 | += Projections |
| 3 | + |
| 4 | +[[projections.general-remarks]] |
| 5 | +== General remarks |
| 6 | + |
| 7 | +As stated above, projections come in two flavors: Interface and DTO based projections. |
| 8 | +In Spring Data Neo4j both types of projections have a direct influence which properties and relationships are transferred |
| 9 | +over the wire. |
| 10 | +Therefore, both approaches can reduce the load on your database in case you are dealing with nodes and entities containing |
| 11 | +lots of properties which might not be needed in all usage scenarios in your application. |
| 12 | + |
| 13 | +For both interface and DTO based projections, Spring Data Neo4j will use the repository's domain type for building the |
| 14 | +query. All annotations on all attributes that might change the query will be taken in consideration. |
| 15 | +The domain type is the type that has been defined through the repository declaration |
| 16 | +(Given a declaration like `interface TestRepository extends CrudRepository<TestEntity, Long>` the domain type would be |
| 17 | +`TestEntity`). |
| 18 | + |
| 19 | +Interface based projections will always be dynamic proxies to the underlying domain type. The names of the accessors defined |
| 20 | +on such interfaces (like `getName`) must resolve to properties (here: `name`) that are present on the projected entity. |
| 21 | +Whether those properties have accessors or not on the domain type is not relevant, as long as they can be accessed through |
| 22 | +the common Spring Data infrastructure. The later is ensure already, as the domain type wouldn't be a persistent entity in |
| 23 | +the first place. |
| 24 | + |
| 25 | +DTO based projections are somewhat more flexible when used with custom queries. While the standard query is derived from |
| 26 | +the original domain type and therefore only the properties and relationship beeing defined there can be used, custom queries |
| 27 | +can add additional properties. |
| 28 | + |
| 29 | +The rules are as follows: First, the properties of the domain type are used to populate the DTO. In case the DTO declare |
| 30 | +additional properties - via accessors or fields - Spring Data Neo4j looks in the resulting record for matching properties. |
| 31 | +Properties must match exactly by name and can be of simple types (as defined in `org.springframework.data.neo4j.core.convert.Neo4jSimpleTypes`) |
| 32 | +or of known persistent entites. Collections of those are supported, but no maps. |
| 33 | + |
| 34 | +=== A full example |
| 35 | + |
| 36 | +Given the following entities, projections and the corresponding repository: |
| 37 | + |
| 38 | +[[projections.simple-entity]] |
| 39 | +[source,java] |
| 40 | +.A simple entity |
| 41 | +---- |
| 42 | +@Node |
| 43 | +class TestEntity { |
| 44 | + @Id @GeneratedValue private Long id; |
| 45 | +
|
| 46 | + private String name; |
| 47 | +
|
| 48 | + @Property("a_property") // <.> |
| 49 | + private String aProperty; |
| 50 | +} |
| 51 | +---- |
| 52 | +<.> This property has a different name in the Graph |
| 53 | + |
| 54 | +[[projections.simple-entity-extended]] |
| 55 | +[source,java] |
| 56 | +.A derived entity, inheriting from `TestEntity` |
| 57 | +---- |
| 58 | +@Node |
| 59 | +class ExtendedTestEntity extends TestEntity { |
| 60 | +
|
| 61 | + private String otherAttribute; |
| 62 | +} |
| 63 | +---- |
| 64 | + |
| 65 | +[[projections.simple-entity-interface-projected]] |
| 66 | +[source,java] |
| 67 | +.Interface projection of `TestEntity` |
| 68 | +---- |
| 69 | +interface TestEntityInterfaceProjection { |
| 70 | +
|
| 71 | + String getName(); |
| 72 | +} |
| 73 | +---- |
| 74 | + |
| 75 | +[[projections.simple-entity-dto-projected]] |
| 76 | +[source,java] |
| 77 | +.DTO projection of `TestEntity`, including one additional attribute |
| 78 | +---- |
| 79 | +class TestEntityDTOProjection { |
| 80 | +
|
| 81 | + private String name; |
| 82 | +
|
| 83 | + private Long numberOfRelations; // <.> |
| 84 | +
|
| 85 | + public String getName() { |
| 86 | + return name; |
| 87 | + } |
| 88 | +
|
| 89 | + public void setName(String name) { |
| 90 | + this.name = name; |
| 91 | + } |
| 92 | +
|
| 93 | + public Long getNumberOfRelations() { |
| 94 | + return numberOfRelations; |
| 95 | + } |
| 96 | +
|
| 97 | + public void setNumberOfRelations(Long numberOfRelations) { |
| 98 | + this.numberOfRelations = numberOfRelations; |
| 99 | + } |
| 100 | +} |
| 101 | +---- |
| 102 | +<.> This attribute doesn't exist on the projected entity |
| 103 | + |
| 104 | +A repository for `TestEntity` is shown below and it will behave as explained with the listing. |
| 105 | + |
| 106 | +[[projections.simple-entity-repository]] |
| 107 | +[source,java] |
| 108 | +.A repository for the `TestEntity` |
| 109 | +---- |
| 110 | +interface TestRepository extends CrudRepository<TestEntity, Long> { // <.> |
| 111 | +
|
| 112 | + List<TestEntity> findAll(); // <.> |
| 113 | +
|
| 114 | + List<ExtendedTestEntity> findAllExtendedEntites(); // <.> |
| 115 | +
|
| 116 | + List<TestEntityInterfaceProjection> findAllInterfaceProjections(); // <.> |
| 117 | +
|
| 118 | + List<TestEntityDTOProjection> findAllDTOProjections(); // <.> |
| 119 | +
|
| 120 | + @Query("MATCH (t:TestEntity) - [r:RELATED_TO] -> () RETURN t, COUNT(r) AS numberOfRelations") // <.> |
| 121 | + List<TestEntityDTOProjection> findAllDTOProjectionsWithCustomQuery(); |
| 122 | +} |
| 123 | +---- |
| 124 | +<.> The domain type of the repository is `TestEntity` |
| 125 | +<.> Methods returning one or more `TestEntity` will just return instances of it, as it matches the domain type |
| 126 | +<.> Methods returning one or more instances of class that extend the domain type will just return instances |
| 127 | + of the extending class. The domain type of the method in question will the extended class, which |
| 128 | + still satifies the domain type of the repository itself |
| 129 | +<.> This method returns an interface projection, the return type of the method is therefore different |
| 130 | + from the repository's domain type. The interface can only access properties defined in the domain type |
| 131 | +<.> This method returns a DTO projection. Executing it will cause SDN to issue a warning, as the DTO defines |
| 132 | + `numberOfRelations` as additional attribute, which is not in the contract of the domain type. |
| 133 | + The annotated attribute `aProperty` in `TestEntity` will be correctly translated to `a_property` in the query. |
| 134 | + As above, the return type is different from the repositories domain type. |
| 135 | +<.> This method also returns a DTO projection. However, no warning will be issued, as the query contains a fitting |
| 136 | + value for the additional attributes defined in the projection. |
0 commit comments