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 * Can be used as an annotation on a field of an {@link Entity} or {@code Pojo} to signal that 26 * nested fields (i.e. fields of the annotated field's class) can be referenced directly in the SQL 27 * queries. 28 * <p> 29 * If the container is an {@link Entity}, these sub fields will be columns in the {@link Entity}'s 30 * database table. 31 * <p> 32 * For example, if you have 2 classes: 33 * <pre> 34 * public class Coordinates { 35 * double latitude; 36 * double longitude; 37 * } 38 * public class Address { 39 * String street; 40 * {@literal @}Embedded 41 * Coordinates coordinates; 42 * } 43 * </pre> 44 * Room will consider {@code latitude} and {@code longitude} as if they are fields of the 45 * {@code Address} class when mapping an SQLite row to {@code Address}. 46 * <p> 47 * So if you have a query that returns {@code street, latitude, longitude}, Room will properly 48 * construct an {@code Address} class. 49 * <p> 50 * If the {@code Address} class is annotated with {@link Entity}, its database table will have 3 51 * columns: {@code street, latitude, longitude} 52 * <p> 53 * If there is a name conflict with the fields of the sub object and the owner object, you can 54 * specify a {@link #prefix()} for the items of the sub object. Note that prefix is always applied 55 * to sub fields even if they have a {@link ColumnInfo} with a specific {@code name}. 56 * <p> 57 * If sub fields of an embedded field has {@link PrimaryKey} annotation, they <b>will not</b> be 58 * considered as primary keys in the owner {@link Entity}. 59 * <p> 60 * When an embedded field is read, if all fields of the embedded field (and its sub fields) are 61 * {@code null} in the {@link android.database.Cursor Cursor}, it is set to {@code null}. Otherwise, 62 * it is constructed. 63 * <p> 64 * Note that even if you have {@link TypeConverter}s that convert a {@code null} column into a 65 * {@code non-null} value, if all columns of the embedded field in the 66 * {@link android.database.Cursor Cursor} are null, the {@link TypeConverter} will never be called 67 * and the embedded field will not be constructed. 68 * <p> 69 * You can override this behavior by annotating the embedded field with 70 * {@link androidx.annotation.NonNull}. 71 */ 72 @Target(ElementType.FIELD) 73 @Retention(RetentionPolicy.CLASS) 74 public @interface Embedded { 75 /** 76 * Specifies a prefix to prepend the column names of the fields in the embedded fields. 77 * <p> 78 * For the example above, if we've written: 79 * <pre> 80 * {@literal @}Embedded(prefix = "foo_") 81 * Coordinates coordinates; 82 * </pre> 83 * The column names for {@code latitude} and {@code longitude} will be {@code foo_latitude} and 84 * {@code foo_longitude} respectively. 85 * <p> 86 * By default, prefix is the empty string. 87 * 88 * @return The prefix to be used for the fields of the embedded item. 89 */ prefix()90 String prefix() default ""; 91 } 92