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
17package android.arch.persistence.room;
18
19import java.lang.annotation.ElementType;
20import java.lang.annotation.Retention;
21import java.lang.annotation.RetentionPolicy;
22import 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 *     int userId;
32 *     String name;
33 *     // other fields
34 * }
35 * public class UserNameAndAllPets {
36 *   public int id;
37 *   public String name;
38 *   {@literal @}Relation(parentColumn = "id", entityColumn = "userId")
39 *   public List&lt;Pet&gt; pets;
40 * }
41 *
42 * {@literal @}Dao
43 * public interface UserPetDao {
44 *     {@literal @}Query("SELECT id, name from User WHERE age &gt; :minAge")
45 *     public List&lt;UserNameAndAllPets&gt; loadUserAndPets(int minAge);
46 * }
47 * </pre>
48 * <p>
49 * The type of the field annotated with {@code Relation} must be a {@link java.util.List} or
50 * {@link java.util.Set}. By default, the {@link Entity} type is inferred from the return type.
51 * If you would like to return a different object, you can specify the {@link #entity()} property
52 * in the annotation.
53 * <pre>
54 * public class User {
55 *     int id;
56 *     // other fields
57 * }
58 * public class PetNameAndId {
59 *     int id;
60 *     String name;
61 * }
62 * public class UserAllPets {
63 *   {@literal @}Embedded
64 *   public User user;
65 *   {@literal @}Relation(parentColumn = "id", entityColumn = "userId", entity = Pet.class)
66 *   public List<PetNameAndId> pets;
67 * }
68 * {@literal @}Dao
69 * public interface UserPetDao {
70 *     {@literal @}Query("SELECT * from User WHERE age &gt; :minAge")
71 *     public List&lt;UserAllPets&gt; loadUserAndPets(int minAge);
72 * }
73 * </pre>
74 * <p>
75 * In the example above, {@code PetNameAndId} is a regular but all of fields are fetched
76 * from the {@code entity} defined in the {@code @Relation} annotation (<i>Pet</i>).
77 * {@code PetNameAndId} could also define its own relations all of which would also be fetched
78 * automatically.
79 * <p>
80 * If you would like to specify which columns are fetched from the child {@link Entity}, you can
81 * use {@link #projection()} property in the {@code Relation} annotation.
82 * <pre>
83 * public class UserAndAllPets {
84 *   {@literal @}Embedded
85 *   public User user;
86 *   {@literal @}Relation(parentColumn = "id", entityColumn = "userId", entity = Pet.class,
87 *           projection = {"name"})
88 *   public List<String> petNames;
89 * }
90 * </pre>
91 * <p>
92 * Note that {@code @Relation} annotation can be used only in Pojo classes, an {@link Entity} class
93 * cannot have relations. This is a design decision to avoid common pitfalls in {@link Entity}
94 * setups. You can read more about it in the main Room documentation. When loading data, you can
95 * simply work around this limitation by creating Pojo classes that extend the {@link Entity}.
96 *
97 * Note that the {@code @Relation} annotated field cannot be a constructor parameter, it must be
98 * public or have a public setter.
99 */
100@Target(ElementType.FIELD)
101@Retention(RetentionPolicy.CLASS)
102public @interface Relation {
103    /**
104     * The entity to fetch the item from. You don't need to set this if the entity matches the
105     * type argument in the return type.
106     *
107     * @return The entity to fetch from. By default, inherited from the return type.
108     */
109    Class entity() default Object.class;
110
111    /**
112     * Reference field in the parent Pojo.
113     * <p>
114     * If you would like to access to a sub item of a {@link Embedded}d field, you can use
115     * the {@code .} notation.
116     * <p>
117     * For instance, if you have a {@link Embedded}d field named {@code user} with a sub field
118     * {@code id}, you can reference it via {@code user.id}.
119     * <p>
120     * This value will be matched against the value defined in {@link #entityColumn()}.
121     *
122     * @return The field reference in the parent object.
123     */
124    String parentColumn();
125
126    /**
127     * The field path to match in the {@link #entity()}. This value will be matched against the
128     * value defined in {@link #parentColumn()}.
129     */
130    String entityColumn();
131
132    /**
133     * If sub fields should be fetched from the entity, you can specify them using this field.
134     * <p>
135     * By default, inferred from the the return type.
136     *
137     * @return The list of columns to be selected from the {@link #entity()}.
138     */
139    String[] projection() default {};
140}
141