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