1 /*
2  * Copyright (C) 2017 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package androidx.room;
18 
19 import java.lang.annotation.ElementType;
20 import java.lang.annotation.Retention;
21 import java.lang.annotation.RetentionPolicy;
22 import java.lang.annotation.Target;
23 
24 /**
25  * A convenience annotation which can be used in a Pojo to automatically fetch relation entities.
26  * When the Pojo is returned from a query, all of its relations are also fetched by Room.
27  *
28  * <pre>
29  * {@literal @}Entity
30  * public class Pet {
31  *     {@literal @} PrimaryKey
32  *     int id;
33  *     int userId;
34  *     String name;
35  *     // other fields
36  * }
37  * public class UserNameAndAllPets {
38  *   public int id;
39  *   public String name;
40  *   {@literal @}Relation(parentColumn = "id", entityColumn = "userId")
41  *   public List&lt;Pet&gt; pets;
42  * }
43  *
44  * {@literal @}Dao
45  * public interface UserPetDao {
46  *     {@literal @}Query("SELECT id, name from User")
47  *     public List&lt;UserNameAndAllPets&gt; loadUserAndPets();
48  * }
49  * </pre>
50  * <p>
51  * The type of the field annotated with {@code Relation} must be a {@link java.util.List} or
52  * {@link java.util.Set}. By default, the {@link Entity} type is inferred from the return type.
53  * If you would like to return a different object, you can specify the {@link #entity()} property
54  * in the annotation.
55  * <pre>
56  * public class User {
57  *     int id;
58  *     // other fields
59  * }
60  * public class PetNameAndId {
61  *     int id;
62  *     String name;
63  * }
64  * public class UserAllPets {
65  *   {@literal @}Embedded
66  *   public User user;
67  *   {@literal @}Relation(parentColumn = "id", entityColumn = "userId", entity = Pet.class)
68  *   public List&lt;PetNameAndId&gt; pets;
69  * }
70  * {@literal @}Dao
71  * public interface UserPetDao {
72  *     {@literal @}Query("SELECT * from User")
73  *     public List&lt;UserAllPets&gt; loadUserAndPets();
74  * }
75  * </pre>
76  * <p>
77  * In the example above, {@code PetNameAndId} is a regular Pojo but all of fields are fetched
78  * from the {@code entity} defined in the {@code @Relation} annotation (<i>Pet</i>).
79  * {@code PetNameAndId} could also define its own relations all of which would also be fetched
80  * automatically.
81  * <p>
82  * If you would like to specify which columns are fetched from the child {@link Entity}, you can
83  * use {@link #projection()} property in the {@code Relation} annotation.
84  * <pre>
85  * public class UserAndAllPets {
86  *   {@literal @}Embedded
87  *   public User user;
88  *   {@literal @}Relation(parentColumn = "id", entityColumn = "userId", entity = Pet.class,
89  *           projection = {"name"})
90  *   public List&lt;String&gt; petNames;
91  * }
92  * </pre>
93  * <p>
94  * Note that {@code @Relation} annotation can be used only in Pojo classes, an {@link Entity} class
95  * cannot have relations. This is a design decision to avoid common pitfalls in {@link Entity}
96  * setups. You can read more about it in the main Room documentation. When loading data, you can
97  * simply work around this limitation by creating Pojo classes that extend the {@link Entity}.
98  * <p>
99  * Note that the {@code @Relation} annotated field cannot be a constructor parameter, it must be
100  * public or have a public setter.
101  */
102 @Target(ElementType.FIELD)
103 @Retention(RetentionPolicy.CLASS)
104 public @interface Relation {
105     /**
106      * The entity to fetch the item from. You don't need to set this if the entity matches the
107      * type argument in the return type.
108      *
109      * @return The entity to fetch from. By default, inherited from the return type.
110      */
entity()111     Class entity() default Object.class;
112 
113     /**
114      * Reference field in the parent Pojo.
115      * <p>
116      * If you would like to access to a sub item of a {@link Embedded}d field, you can use
117      * the {@code .} notation.
118      * <p>
119      * For instance, if you have a {@link Embedded}d field named {@code user} with a sub field
120      * {@code id}, you can reference it via {@code user.id}.
121      * <p>
122      * This value will be matched against the value defined in {@link #entityColumn()}.
123      *
124      * @return The field reference in the parent object.
125      */
parentColumn()126     String parentColumn();
127 
128     /**
129      * The field path to match in the {@link #entity()}. This value will be matched against the
130      * value defined in {@link #parentColumn()}.
131      */
entityColumn()132     String entityColumn();
133 
134     /**
135      * If sub fields should be fetched from the entity, you can specify them using this field.
136      * <p>
137      * By default, inferred from the the return type.
138      *
139      * @return The list of columns to be selected from the {@link #entity()}.
140      */
projection()141     String[] projection() default {};
142 }
143