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<Pet> pets; 40 * } 41 * 42 * {@literal @}Dao 43 * public interface UserPetDao { 44 * {@literal @}Query("SELECT id, name from User WHERE age > :minAge") 45 * public List<UserNameAndAllPets> 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 > :minAge") 71 * public List<UserAllPets> 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