001/* 002 * Copyright (c) 2008, 2009, 2011 Oracle, Inc. All rights reserved. 003 * 004 * This program and the accompanying materials are made available under the 005 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0 006 * which accompanies this distribution. The Eclipse Public License is available 007 * at http://www.eclipse.org/legal/epl-v10.html and the Eclipse Distribution License 008 * is available at http://www.eclipse.org/org/documents/edl-v10.php. 009 */ 010package javax.persistence; 011 012import java.lang.annotation.Retention; 013import java.lang.annotation.Target; 014 015import static java.lang.annotation.ElementType.FIELD; 016import static java.lang.annotation.RetentionPolicy.RUNTIME; 017 018/** 019 * Specifies the table that is used for the mapping of 020 * collections of basic or embeddable types. Applied 021 * to the collection-valued field or property. 022 * <p> 023 * <p>By default, the columns of the collection table that correspond 024 * to the embeddable class or basic type are derived from the 025 * attributes of the embeddable class or from the basic type according 026 * to the default values of the <code>Column</code> annotation. In the case 027 * of a basic type, the column name is derived from the name of the 028 * collection-valued field or property. In the case of an embeddable 029 * class, the column names are derived from the field or property 030 * names of the embeddable class. 031 * <ul> 032 * <li> To override the default properties of the column used for a 033 * basic type, the <code>Column</code> annotation is used on the 034 * collection-valued attribute in addition to the 035 * <code>ElementCollection</code> annotation. 036 * <p> 037 * <li> To override these defaults for an embeddable class, the 038 * <code>AttributeOverride</code> and/or 039 * <code>AttributeOverrides</code> annotations can be used in 040 * addition to the <code>ElementCollection</code> annotation. If the 041 * embeddable class contains references to other entities, the default 042 * values for the columns corresponding to those references may be 043 * overridden by means of the <code>AssociationOverride</code> and/or 044 * <code>AssociationOverrides</code> annotations. 045 * </ul> 046 * <p> 047 * <p> If the <code>CollectionTable</code> annotation is missing, the 048 * default values of the <code>CollectionTable</code> annotation 049 * elements apply. 050 * <p> 051 * <pre> 052 * Example: 053 * 054 * @Embeddable public class Address { 055 * protected String street; 056 * protected String city; 057 * protected String state; 058 * ... 059 * } 060 * 061 * @Entity public class Person { 062 * @Id protected String ssn; 063 * protected String name; 064 * protected Address home; 065 * ... 066 * @ElementCollection // use default table (PERSON_NICKNAMES) 067 * @Column(name="name", length=50) 068 * protected Set<String> nickNames = new HashSet(); 069 * ... 070 * } 071 * 072 * @Entity public class WealthyPerson extends Person { 073 * @ElementCollection 074 * @CollectionTable(name="HOMES") // use default join column name 075 * @AttributeOverrides({ 076 * @AttributeOverride(name="street", 077 * column=@Column(name="HOME_STREET")), 078 * @AttributeOverride(name="city", 079 * column=@Column(name="HOME_CITY")), 080 * @AttributeOverride(name="state", 081 * column=@Column(name="HOME_STATE")) 082 * }) 083 * protected Set<Address> vacationHomes = new HashSet(); 084 * ... 085 * } 086 * </pre> 087 * 088 * @see ElementCollection 089 * @see AttributeOverride 090 * @see AssociationOverride 091 * @see Column 092 * @since Java Persistence 2.0 093 */ 094@Target({FIELD}) 095@Retention(RUNTIME) 096public @interface CollectionTable { 097 098 /** 099 * (Optional) The name of the collection table. If not specified, 100 * it defaults to the concatenation of the name of the containing 101 * entity and the name of the collection attribute, separated by 102 * an underscore. 103 */ 104 String name() default ""; 105 106 /** 107 * (Optional) The catalog of the table. If not specified, the 108 * default catalog is used. 109 */ 110 String catalog() default ""; 111 112 /** 113 * (Optional) The schema of the table. If not specified, the 114 * default schema for the user is used. 115 */ 116 String schema() default ""; 117 118 /** 119 * (Optional) The foreign key columns of the collection table 120 * which reference the primary table of the entity. The default 121 * only applies if a single join column is used. The default is 122 * the same as for <code>JoinColumn</code> (i.e., the 123 * concatenation of the following: the name of the entity; "_"; 124 * the name of the referenced primary key column.) However, if 125 * there is more than one join column, a <code>JoinColumn</code> 126 * annotation must be specified for each join column using the 127 * <code>JoinColumns</code> annotation. In this case, both the 128 * <code>name</code> and the <code>referencedColumnName</code> 129 * elements must be specified in each such 130 * <code>JoinColumn</code> annotation. 131 */ 132 JoinColumn[] joinColumns() default {}; 133 134 /** 135 * (Optional) Unique constraints that are to be placed on the 136 * table. These are only used if table generation is in effect. 137 */ 138 UniqueConstraint[] uniqueConstraints() default {}; 139 140 /** 141 * (Optional) Indexes for the table. These are only used if table generation is in effect. 142 * 143 * @return The indexes 144 */ 145 Index[] indexes() default {}; 146 147 /** 148 * (Optional) Used to specify or control the generation of a foreign key constraint for the columns 149 * corresponding to the joinColumns element when table generation is in effect. If both this element 150 * and the foreignKey element of any of the joinColumns elements are specified, the behavior is undefined. 151 * If no foreign key annotation element is specified in either location, the persistence provider's default 152 * foreign key strategy will apply. 153 * 154 * @since Java Persistence 2.1 155 */ 156 ForeignKey foreignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT); 157}