|
|
Hibernate example source code file (collection_mapping.pot)
This example Hibernate source code file (collection_mapping.pot) is included in the DevDaily.com
"Java Source Code
Warehouse" project. The intent of this project is to help you "Learn Java by Example" TM.
The Hibernate collection_mapping.pot source code
# SOME DESCRIPTIVE TITLE.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: http://bugs.kde.org\n"
"POT-Creation-Date: 2010-07-20 21:02+0000\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <kde-i18n-doc@kde.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: application/x-xml2pot; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#. Tag: title
#: collection_mapping.xml:31
#, no-c-format
msgid "Collection mapping"
msgstr ""
#. Tag: title
#: collection_mapping.xml:34
#, no-c-format
msgid "Persistent collections"
msgstr ""
#. Tag: para
#: collection_mapping.xml:36
#, no-c-format
msgid "Naturally Hibernate also allows to persist collections. These persistent collections can contain almost any other Hibernate type, including: basic types, custom types, components and references to other entities. The distinction between value and reference semantics is in this context very important. An object in a collection might be handled with \"value\" semantics (its life cycle fully depends on the collection owner), or it might be a reference to another entity with its own life cycle. In the latter case, only the \"link\" between the two objects is considered to be a state held by the collection."
msgstr ""
#. Tag: para
#: collection_mapping.xml:46
#, no-c-format
msgid "As a requirement persistent collection-valued fields must be declared as an interface type (see <xref linkend=\"example.collection.mapping.annotations\"/>). The actual interface might be java.util.Set, java.util.Collection, java.util.List, java.util.Map, java.util.SortedSet, java.util.SortedMap or anything you like (\"anything you like\" means you will have to write an implementation of org.hibernate.usertype.UserCollectionType)."
msgstr ""
#. Tag: para
#: collection_mapping.xml:57
#, no-c-format
msgid "Notice how in <xref linkend=\"example.collection.mapping.annotations\"/> the instance variable parts was initialized with an instance of HashSet. This is the best way to initialize collection valued properties of newly instantiated (non-persistent) instances. When you make the instance persistent, by calling persist(), Hibernate will actually replace the HashSet with an instance of Hibernate's own implementation of Set. Be aware of the following error:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:68
#, no-c-format
msgid "Hibernate uses its own collection implementations"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:70
#, no-c-format
msgid ""
"Cat cat = new DomesticCat();\n"
"Cat kitten = new DomesticCat();\n"
"....\n"
"Set kittens = new HashSet();\n"
"kittens.add(kitten);\n"
"cat.setKittens(kittens);\n"
"session.persist(cat);\n"
"\n"
"kittens = cat.getKittens(); // Okay, kittens collection is a Set\n"
"(HashSet) cat.getKittens(); // Error!"
msgstr ""
#. Tag: para
#: collection_mapping.xml:73
#, no-c-format
msgid "The persistent collections injected by Hibernate behave like <literal>HashMap, HashSet, TreeMap, TreeSet or ArrayList, depending on the interface type."
msgstr ""
#. Tag: para
#: collection_mapping.xml:78
#, no-c-format
msgid "Collections instances have the usual behavior of value types. They are automatically persisted when referenced by a persistent object and are automatically deleted when unreferenced. If a collection is passed from one persistent object to another, its elements might be moved from one table to another. Two entities cannot share a reference to the same collection instance. Due to the underlying relational model, collection-valued properties do not support null value semantics. Hibernate does not distinguish between a null collection reference and an empty collection."
msgstr ""
#. Tag: para
#: collection_mapping.xml:89
#, no-c-format
msgid "Use persistent collections the same way you use ordinary Java collections. However, ensure you understand the semantics of bidirectional associations (see <xref linkend=\"collections-bidirectional\"/>)."
msgstr ""
#. Tag: title
#: collection_mapping.xml:97
#, no-c-format
msgid "How to map collections"
msgstr ""
#. Tag: para
#: collection_mapping.xml:99
#, no-c-format
msgid "Using annotations you can map <classname>Collections, Lists, Maps and Sets of associated entities using @OneToMany and @ManyToMany. For collections of a basic or embeddable type use @ElementCollection. In the simplest case a collection mapping looks like this:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:107
#, no-c-format
msgid "Collection mapping using @OneToMany and @JoinColumn"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:109
#, no-c-format
msgid ""
"@Entity\n"
"public class Product {\n"
"\n"
" private String serialNumber;\n"
" private Set<Part> parts = new HashSet<Part>();\n"
"\n"
" @Id\n"
" public String getSerialNumber() { return serialNumber; }\n"
" void setSerialNumber(String sn) { serialNumber = sn; }\n"
" \n"
" @OneToMany\n"
" @JoinColumn(name=\"PART_ID\")\n"
" public Set<Part> getParts() { return parts; }\n"
" void setParts(Set parts) { this.parts = parts; }\n"
"}\n"
"\n"
"\n"
"@Entity\n"
"public class Part {\n"
" ...\n"
"}"
msgstr ""
#. Tag: para
#: collection_mapping.xml:112
#, no-c-format
msgid "Product describes a unidirectional relationship with Part using the join column PART_ID. In this unidirectional one to many scenario you can also use a join table as seen in <xref linkend=\"example-one-to-many-with-join-table\"/>."
msgstr ""
#. Tag: title
#: collection_mapping.xml:118
#, no-c-format
msgid "Collection mapping using @OneToMany and @JoinTable"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:121
#, no-c-format
msgid ""
"@Entity\n"
"public class Product {\n"
"\n"
" private String serialNumber;\n"
" private Set<Part> parts = new HashSet<Part>();\n"
"\n"
" @Id\n"
" public String getSerialNumber() { return serialNumber; }\n"
" void setSerialNumber(String sn) { serialNumber = sn; }\n"
" \n"
" @OneToMany\n"
" @JoinTable(\n"
" name=\"PRODUCT_PARTS\",\n"
" joinColumns = @JoinColumn( name=\"PRODUCT_ID\"),\n"
" inverseJoinColumns = @JoinColumn( name=\"PART_ID\")\n"
" )\n"
" public Set<Part> getParts() { return parts; }\n"
" void setParts(Set parts) { this.parts = parts; }\n"
"}\n"
"\n"
"\n"
"@Entity\n"
"public class Part {\n"
" ...\n"
"}"
msgstr ""
#. Tag: para
#: collection_mapping.xml:124
#, no-c-format
msgid "Without describing any physical mapping (no <classname>@JoinColumn or @JoinTable), a unidirectional one to many with join table is used. The table name is the concatenation of the owner table name, _, and the other side table name. The foreign key name(s) referencing the owner table is the concatenation of the owner table, _, and the owner primary key column(s) name. The foreign key name(s) referencing the other side is the concatenation of the owner property name, _, and the other side primary key column(s) name. A unique constraint is added to the foreign key referencing the other side table to reflect the one to many."
msgstr ""
#. Tag: para
#: collection_mapping.xml:135
#, no-c-format
msgid "Lets have a look now how collections are mapped using Hibernate mapping files. In this case the first step is to chose the right mapping element. It depends on the type of interface. For example, a <literal><set> element is used for mapping properties of type Set."
msgstr ""
#. Tag: title
#: collection_mapping.xml:142
#, no-c-format
msgid "Mapping a Set using <set>"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:144
#, no-c-format
msgid ""
"<class name=\"Product\">\n"
" <id name=\"serialNumber\" column=\"productSerialNumber\"/>\n"
" <set name=\"parts\">\n"
" <key column=\"productSerialNumber\" not-null=\"true\"/>\n"
" <one-to-many class=\"Part\"/>\n"
" </set>\n"
"</class>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:147
#, no-c-format
msgid "In <xref linkend=\"example.collections.set\"/> a one-to-many association links the Product and Part entities. This association requires the existence of a foreign key column and possibly an index column to the Part table. This mapping loses certain semantics of normal Java collections:"
msgstr ""
#. Tag: para
#: collection_mapping.xml:156
#, no-c-format
msgid "An instance of the contained entity class cannot belong to more than one instance of the collection."
msgstr ""
#. Tag: para
#: collection_mapping.xml:161
#, no-c-format
msgid "An instance of the contained entity class cannot appear at more than one value of the collection index."
msgstr ""
#. Tag: para
#: collection_mapping.xml:166
#, no-c-format
msgid "Looking closer at the used <literal><one-to-many> tag we see that it has the following options."
msgstr ""
#. Tag: title
#: collection_mapping.xml:170
#, no-c-format
msgid "options of <one-to-many> element"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:181
#, no-c-format
msgid ""
"<one-to-many\n"
" class=\"ClassName\"\n"
" not-found=\"ignore|exception\"\n"
" entity-name=\"EntityName\"\n"
" node=\"element-name\"\n"
" embed-xml=\"true|false\"\n"
" />"
msgstr ""
#. Tag: para
#: collection_mapping.xml:185
#, no-c-format
msgid "<literal>class (required): the name of the associated class."
msgstr ""
#. Tag: para
#: collection_mapping.xml:190
#, no-c-format
msgid "<literal>not-found (optional - defaults to exception): specifies how cached identifiers that reference missing rows will be handled. ignore will treat a missing row as a null association."
msgstr ""
#. Tag: para
#: collection_mapping.xml:198
#, no-c-format
msgid "<literal>entity-name (optional): the entity name of the associated class, as an alternative to class."
msgstr ""
#. Tag: para
#: collection_mapping.xml:206
#, no-c-format
msgid "The <literal><one-to-many> element does not need to declare any columns. Nor is it necessary to specify the table name anywhere."
msgstr ""
#. Tag: para
#: collection_mapping.xml:211
#, no-c-format
msgid "If the foreign key column of a <literal><one-to-many> association is declared NOT NULL, you must declare the <key> mapping not-null=\"true\" or use a bidirectional association with the collection mapping marked inverse=\"true\". See ."
msgstr ""
#. Tag: para
#: collection_mapping.xml:221
#, no-c-format
msgid "Apart from the <literal><set> tag as shown in , there is also <list>, <map>, <bag>, <array> and <primitive-array> mapping elements. The <map> element is representative:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:229
#, no-c-format
msgid "Elements of the <map> mapping"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:262
#, no-c-format
msgid ""
"<map\n"
" name=\"propertyName\"\n"
" table=\"table_name\"\n"
" schema=\"schema_name\"\n"
" lazy=\"true|extra|false\"\n"
" inverse=\"true|false\"\n"
" cascade=\"all|none|save-update|delete|all-delete-orphan|delete-orphan\"\n"
" sort=\"unsorted|natural|comparatorClass\"\n"
" order-by=\"column_name asc|desc\"\n"
" where=\"arbitrary sql where condition\"\n"
" fetch=\"join|select|subselect\"\n"
" batch-size=\"N\"\n"
" access=\"field|property|ClassName\"\n"
" optimistic-lock=\"true|false\"\n"
" mutable=\"true|false\"\n"
" node=\"element-name|.\"\n"
" embed-xml=\"true|false\"\n"
">\n"
"\n"
" <key .... />\n"
" <map-key .... />\n"
" <element .... />\n"
"</map>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:266
#, no-c-format
msgid "<literal>name: the collection property name"
msgstr ""
#. Tag: para
#: collection_mapping.xml:270
#, no-c-format
msgid "<literal>table (optional - defaults to property name): the name of the collection table. It is not used for one-to-many associations."
msgstr ""
#. Tag: para
#: collection_mapping.xml:276
#, no-c-format
msgid "<literal>schema (optional): the name of a table schema to override the schema declared on the root element"
msgstr ""
#. Tag: para
#: collection_mapping.xml:281
#, no-c-format
msgid "<literal>lazy (optional - defaults to true): disables lazy fetching and specifies that the association is always eagerly fetched. It can also be used to enable \"extra-lazy\" fetching where most operations do not initialize the collection. This is suitable for large collections."
msgstr ""
#. Tag: para
#: collection_mapping.xml:290
#, no-c-format
msgid "<literal>inverse (optional - defaults to false): marks this collection as the \"inverse\" end of a bidirectional association."
msgstr ""
#. Tag: para
#: collection_mapping.xml:296
#, no-c-format
msgid "<literal>cascade (optional - defaults to none): enables operations to cascade to child entities."
msgstr ""
#. Tag: para
#: collection_mapping.xml:302
#, no-c-format
msgid "<literal>sort (optional): specifies a sorted collection with natural sort order or a given comparator class."
msgstr ""
#. Tag: para
#: collection_mapping.xml:308
#, no-c-format
msgid "<literal>order-by (optional): specifies a table column or columns that define the iteration order of the Map, Set or bag, together with an optional asc or desc."
msgstr ""
#. Tag: para
#: collection_mapping.xml:316
#, no-c-format
msgid "<literal>where (optional): specifies an arbitrary SQL WHERE condition that is used when retrieving or removing the collection. This is useful if the collection needs to contain only a subset of the available data."
msgstr ""
#. Tag: para
#: collection_mapping.xml:324
#, no-c-format
msgid "<literal>fetch (optional, defaults to select): chooses between outer-join fetching, fetching by sequential select, and fetching by sequential subselect."
msgstr ""
#. Tag: para
#: collection_mapping.xml:331
#, no-c-format
msgid "<literal>batch-size (optional, defaults to 1): specifies a \"batch size\" for lazily fetching instances of this collection."
msgstr ""
#. Tag: para
#: collection_mapping.xml:337
#, no-c-format
msgid "<literal>access (optional - defaults to property): the strategy Hibernate uses for accessing the collection property value."
msgstr ""
#. Tag: para
#: collection_mapping.xml:343
#, no-c-format
msgid "<literal>optimistic-lock (optional - defaults to true): specifies that changes to the state of the collection results in increments of the owning entity's version. For one-to-many associations you may want to disable this setting."
msgstr ""
#. Tag: para
#: collection_mapping.xml:351
#, no-c-format
msgid "<literal>mutable (optional - defaults to true): a value of false specifies that the elements of the collection never change. This allows for minor performance optimization in some cases."
msgstr ""
#. Tag: para
#: collection_mapping.xml:360
#, no-c-format
msgid "After exploring the basic mapping of collections in the preceding paragraphs we will now focus details like physical mapping considerations, indexed collections and collections of value types."
msgstr ""
#. Tag: title
#: collection_mapping.xml:365
#, no-c-format
msgid "Collection foreign keys"
msgstr ""
#. Tag: para
#: collection_mapping.xml:367
#, no-c-format
msgid "On the database level collection instances are distinguished by the foreign key of the entity that owns the collection. This foreign key is referred to as the <emphasis>collection key column, or columns, of the collection table. The collection key column is mapped by the @JoinColumn annotation respectively the <key> XML element."
msgstr ""
#. Tag: para
#: collection_mapping.xml:374
#, no-c-format
msgid "There can be a nullability constraint on the foreign key column. For most collections, this is implied. For unidirectional one-to-many associations, the foreign key column is nullable by default, so you may need to specify"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:379
#, no-c-format
msgid "@JoinColumn(nullable=false)"
msgstr ""
#. Tag: para
#: collection_mapping.xml:381
#, no-c-format
msgid "<para>or"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:383
#, no-c-format
msgid "<key column=\"productSerialNumber\" not-null=\"true\"/>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:385
#, no-c-format
msgid "The foreign key constraint can use <literal>ON DELETE CASCADE. In XML this can be expressed via:"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:388
#, no-c-format
msgid "<key column=\"productSerialNumber\" on-delete=\"cascade\"/>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:390
#, no-c-format
msgid "In annotations the Hibernate specific annotation @OnDelete has to be used."
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:393
#, no-c-format
msgid "@OnDelete(action=OnDeleteAction.CASCADE)"
msgstr ""
#. Tag: para
#: collection_mapping.xml:395
#, no-c-format
msgid "See <xref lang=\"\" linkend=\"section.key\"/> for more information about the <key> element."
msgstr ""
#. Tag: title
#: collection_mapping.xml:400
#, no-c-format
msgid "Indexed collections"
msgstr ""
#. Tag: para
#: collection_mapping.xml:402
#, no-c-format
msgid "In the following paragraphs we have a closer at the indexed collections <classname>List and Map how the their index can be mapped in Hibernate."
msgstr ""
#. Tag: title
#: collection_mapping.xml:407
#, no-c-format
msgid "Lists"
msgstr ""
#. Tag: para
#: collection_mapping.xml:409
#, no-c-format
msgid "Lists can be mapped in two different ways:"
msgstr ""
#. Tag: para
#: collection_mapping.xml:413
#, no-c-format
msgid "as ordered lists, where the order is not materialized in the database"
msgstr ""
#. Tag: para
#: collection_mapping.xml:418
#, no-c-format
msgid "as indexed lists, where the order is materialized in the database"
msgstr ""
#. Tag: para
#: collection_mapping.xml:423
#, no-c-format
msgid "To order lists in memory, add <literal>@javax.persistence.OrderBy to your property. This annotation takes as parameter a list of comma separated properties (of the target entity) and orders the collection accordingly (eg firstname asc, age desc), if the string is empty, the collection will be ordered by the primary key of the target entity."
msgstr ""
#. Tag: title
#: collection_mapping.xml:432
#, no-c-format
msgid "Ordered lists using <classname>@OrderBy"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:434
#, no-c-format
msgid ""
"@Entity\n"
"public class Customer {\n"
" @Id @GeneratedValue public Integer getId() { return id; }\n"
" public void setId(Integer id) { this.id = id; }\n"
" private Integer id;\n"
"\n"
" @OneToMany(mappedBy=\"customer\")\n"
" @OrderBy(\"number\")\n"
" public List<Order> getOrders() { return orders; }\n"
" public void setOrders(List<Order> orders) { this.orders = orders; }\n"
" private List<Order> orders;\n"
"}\n"
"\n"
"@Entity\n"
"public class Order {\n"
" @Id @GeneratedValue public Integer getId() { return id; }\n"
" public void setId(Integer id) { this.id = id; }\n"
" private Integer id;\n"
"\n"
" public String getNumber() { return number; }\n"
" public void setNumber(String number) { this.number = number; }\n"
" private String number;\n"
"\n"
" @ManyToOne\n"
" public Customer getCustomer() { return customer; }\n"
" public void setCustomer(Customer customer) { this.customer = customer; }\n"
" private Customer number;\n"
"}\n"
"\n"
"-- Table schema\n"
"|-------------| |----------|\n"
"| Order | | Customer |\n"
"|-------------| |----------|\n"
"| id | | id |\n"
"| number | |----------| \n"
"| customer_id |\n"
"|-------------|"
msgstr ""
#. Tag: para
#: collection_mapping.xml:437
#, no-c-format
msgid "To store the index value in a dedicated column, use the <classname>@javax.persistence.OrderColumn annotation on your property. This annotations describes the column name and attributes of the column keeping the index value. This column is hosted on the table containing the association foreign key. If the column name is not specified, the default is the name of the referencing property, followed by underscore, followed by ORDER (in the following example, it would be orders_ORDER)."
msgstr ""
#. Tag: title
#: collection_mapping.xml:448
#, no-c-format
msgid "Explicit index column using <classname>@OrderColumn"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:451
#, no-c-format
msgid ""
"@Entity\n"
"public class Customer {\n"
" @Id @GeneratedValue public Integer getId() { return id; }\n"
" public void setId(Integer id) { this.id = id; }\n"
" private Integer id;\n"
"\n"
" @OneToMany(mappedBy=\"customer\")\n"
" @OrderColumn(name=\"orders_index\")\n"
" public List<Order> getOrders() { return orders; }\n"
" public void setOrders(List<Order> orders) { this.orders = orders; }\n"
" private List<Order> orders;\n"
"}\n"
"\n"
"@Entity\n"
"public class Order {\n"
" @Id @GeneratedValue public Integer getId() { return id; }\n"
" public void setId(Integer id) { this.id = id; }\n"
" private Integer id;\n"
"\n"
" public String getNumber() { return number; }\n"
" public void setNumber(String number) { this.number = number; }\n"
" private String number;\n"
"\n"
" @ManyToOne\n"
" public Customer getCustomer() { return customer; }\n"
" public void setCustomer(Customer customer) { this.customer = customer; }\n"
" private Customer number;\n"
"}\n"
"\n"
"-- Table schema\n"
"|--------------| |----------|\n"
"| Order | | Customer |\n"
"|--------------| |----------|\n"
"| id | | id |\n"
"| number | |----------| \n"
"| customer_id |\n"
"| orders_order |\n"
"|--------------|"
msgstr ""
#. Tag: para
#: collection_mapping.xml:455
#, no-c-format
msgid "We recommend you to convert <classname>the legacy @org.hibernate.annotations.IndexColumn usages to @OrderColumn unless you are making use of the base property. The base property lets you define the index value of the first element (aka as base index). The usual value is 0 or 1. The default is 0 like in Java."
msgstr ""
#. Tag: para
#: collection_mapping.xml:464
#, no-c-format
msgid "Looking again at the Hibernate mapping file equivalent, the index of an array or list is always of type <literal>integer and is mapped using the <list-index> element. The mapped column contains sequential integers that are numbered from zero by default."
msgstr ""
#. Tag: title
#: collection_mapping.xml:471
#, no-c-format
msgid "index-list element for indexed collections in xml mapping"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:481
#, no-c-format
msgid ""
"<list-index\n"
" column=\"column_name\"\n"
" base=\"0|1|...\"/>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:485
#, no-c-format
msgid "<literal>column_name (required): the name of the column holding the collection index values."
msgstr ""
#. Tag: para
#: collection_mapping.xml:490
#, no-c-format
msgid "<literal>base (optional - defaults to 0): the value of the index column that corresponds to the first element of the list or array."
msgstr ""
#. Tag: para
#: collection_mapping.xml:498
#, no-c-format
msgid "If your table does not have an index column, and you still wish to use <literal>List as the property type, you can map the property as a Hibernate <bag>. A bag does not retain its order when it is retrieved from the database, but it can be optionally sorted or ordered."
msgstr ""
#. Tag: title
#: collection_mapping.xml:506
#, no-c-format
msgid "Maps"
msgstr ""
#. Tag: para
#: collection_mapping.xml:508
#, no-c-format
msgid "The question with <classname>Maps is where the key value is stored. There are everal options. Maps can borrow their keys from one of the associated entity properties or have dedicated columns to store an explicit key."
msgstr ""
#. Tag: para
#: collection_mapping.xml:513
#, no-c-format
msgid "To use one of the target entity property as a key of the map, use <literal>@MapKey(name=\"myProperty\"), where myProperty is a property name in the target entity. When using @MapKey without the name attribuate, the target entity primary key is used. The map key uses the same column as the property pointed out. There is no additional column defined to hold the map key, because the map key represent a target property. Be aware that once loaded, the key is no longer kept in sync with the property. In other words, if you change the property value, the key will not change automatically in your Java model."
msgstr ""
#. Tag: title
#: collection_mapping.xml:525
#, no-c-format
msgid "Use of target entity property as map key via <classname>@MapKey"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:528
#, no-c-format
msgid ""
"@Entity\n"
"public class Customer {\n"
" @Id @GeneratedValue public Integer getId() { return id; }\n"
" public void setId(Integer id) { this.id = id; }\n"
" private Integer id;\n"
"\n"
" @OneToMany(mappedBy=\"customer\")\n"
" @MapKey(name=\"number\")\n"
" public Map<String,Order> getOrders() { return orders; }\n"
" public void setOrders(Map<String,Order> order) { this.orders = orders; }\n"
" private Map<String,Order> orders;\n"
"}\n"
"\n"
"@Entity\n"
"public class Order {\n"
" @Id @GeneratedValue public Integer getId() { return id; }\n"
" public void setId(Integer id) { this.id = id; }\n"
" private Integer id;\n"
"\n"
" public String getNumber() { return number; }\n"
" public void setNumber(String number) { this.number = number; }\n"
" private String number;\n"
"\n"
" @ManyToOne\n"
" public Customer getCustomer() { return customer; }\n"
" public void setCustomer(Customer customer) { this.customer = customer; }\n"
" private Customer number;\n"
"}\n"
"\n"
"-- Table schema\n"
"|-------------| |----------|\n"
"| Order | | Customer |\n"
"|-------------| |----------|\n"
"| id | | id |\n"
"| number | |----------| \n"
"| customer_id |\n"
"|-------------|"
msgstr ""
#. Tag: para
#: collection_mapping.xml:531
#, no-c-format
msgid "Alternatively the map key is mapped to a dedicated column or columns. In order to customize the mapping use one of the following annotations:"
msgstr ""
#. Tag: para
#: collection_mapping.xml:537
#, no-c-format
msgid "@<classname>MapKeyColumn if the map key is a basic type. If you don't specify the column name, the name of the property followed by underscore followed by KEY is used (for example orders_KEY)."
msgstr ""
#. Tag: para
#: collection_mapping.xml:544
#, no-c-format
msgid "<classname>@MapKeyEnumerated / @MapKeyTemporal if the map key type is respectively an enum or a Date."
msgstr ""
#. Tag: para
#: collection_mapping.xml:550
#, no-c-format
msgid "<classname>@MapKeyJoinColumn/@MapKeyJoinColumns if the map key type is another entity."
msgstr ""
#. Tag: para
#: collection_mapping.xml:555
#, no-c-format
msgid "<classname>@AttributeOverride/@AttributeOverrides when the map key is a embeddable object. Use key. as a prefix for your embeddable object property names."
msgstr ""
#. Tag: para
#: collection_mapping.xml:562
#, no-c-format
msgid "You can also use <classname>@MapKeyClass to define the type of the key if you don't use generics."
msgstr ""
#. Tag: title
#: collection_mapping.xml:566
#, no-c-format
msgid "Map key as basic type using <classname>@MapKeyColumn"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:569
#, no-c-format
msgid ""
"@Entity\n"
"public class Customer {\n"
" @Id @GeneratedValue public Integer getId() { return id; }\n"
" public void setId(Integer id) { this.id = id; }\n"
" private Integer id;\n"
"\n"
" @OneToMany @JoinTable(name=\"Cust_Order\")\n"
" @MapKeyColumn(name=\"orders_number\")\n"
" public Map<String,Order> getOrders() { return orders; }\n"
" public void setOrders(Map<String,Order> orders) { this.orders = orders; }\n"
" private Map<String,Order> orders;\n"
"}\n"
"\n"
"@Entity\n"
"public class Order {\n"
" @Id @GeneratedValue public Integer getId() { return id; }\n"
" public void setId(Integer id) { this.id = id; }\n"
" private Integer id;\n"
"\n"
" public String getNumber() { return number; }\n"
" public void setNumber(String number) { this.number = number; }\n"
" private String number;\n"
"\n"
" @ManyToOne\n"
" public Customer getCustomer() { return customer; }\n"
" public void setCustomer(Customer customer) { this.customer = customer; }\n"
" private Customer number;\n"
"}\n"
"\n"
"-- Table schema\n"
"|-------------| |----------| |---------------|\n"
"| Order | | Customer | | Cust_Order |\n"
"|-------------| |----------| |---------------|\n"
"| id | | id | | customer_id |\n"
"| number | |----------| | order_id |\n"
"| customer_id | | orders_number |\n"
"|-------------| |---------------|"
msgstr ""
#. Tag: para
#: collection_mapping.xml:573
#, no-c-format
msgid "We recommend you to migrate from <classname>@org.hibernate.annotations.MapKey / @org.hibernate.annotation.MapKeyManyToMany to the new standard approach described above"
msgstr ""
#. Tag: para
#: collection_mapping.xml:579
#, no-c-format
msgid "Using Hibernate mapping files there exists equivalent concepts to the descibed annotations. You have to use <literal><map-key>, <map-key-many-to-many> and <composite-map-key>. <map-key> is used for any basic type, <map-key-many-to-many> for an entity reference and <composite-map-key> for a composite type."
msgstr ""
#. Tag: title
#: collection_mapping.xml:590
#, no-c-format
msgid "map-key xml mapping element"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:601
#, no-c-format
msgid ""
"<map-key\n"
" column=\"column_name\"\n"
" formula=\"any SQL expression\"\n"
" type=\"type_name\"\n"
" node=\"@attribute-name\"\n"
" length=\"N\"/>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:605
#, no-c-format
msgid "<literal>column (optional): the name of the column holding the collection index values."
msgstr ""
#. Tag: para
#: collection_mapping.xml:610
#, no-c-format
msgid "<literal>formula (optional): a SQL formula used to evaluate the key of the map."
msgstr ""
#. Tag: para
#: collection_mapping.xml:615
#, no-c-format
msgid "<literal>type (required): the type of the map keys."
msgstr ""
#. Tag: title
#: collection_mapping.xml:623
#, no-c-format
msgid "map-key-many-to-many"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:634
#, no-c-format
msgid ""
"<map-key-many-to-many\n"
" column=\"column_name\"\n"
" formula=\"any SQL expression\"\n"
" class=\"ClassName\"\n"
"/>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:638
#, no-c-format
msgid "<literal>column (optional): the name of the foreign key column for the collection index values."
msgstr ""
#. Tag: para
#: collection_mapping.xml:643
#, no-c-format
msgid "<literal>formula (optional): a SQ formula used to evaluate the foreign key of the map key."
msgstr ""
#. Tag: para
#: collection_mapping.xml:648
#, no-c-format
msgid "<literal>class (required): the entity class used as the map key."
msgstr ""
#. Tag: title
#: collection_mapping.xml:658
#, no-c-format
msgid "Collections of basic types and embeddable objects"
msgstr ""
#. Tag: para
#: collection_mapping.xml:660
#, no-c-format
msgid "In some situations you don't need to associate two entities but simply create a collection of basic types or embeddable objects. Use the <classname>@ElementCollection for this case."
msgstr ""
#. Tag: title
#: collection_mapping.xml:665
#, no-c-format
msgid "Collection of basic types mapped via <classname>@ElementCollection"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:668
#, no-c-format
msgid ""
"@Entity\n"
"public class User {\n"
" [...]\n"
" public String getLastname() { ...}\n"
"\n"
" @ElementCollection\n"
" @CollectionTable(name=\"Nicknames\", joinColumns=@JoinColumn(name=\"user_id\"))\n"
" @Column(name=\"nickname\")\n"
" public Set<String> getNicknames() { ... } \n"
"}"
msgstr ""
#. Tag: para
#: collection_mapping.xml:671
#, no-c-format
msgid "The collection table holding the collection data is set using the <classname>@CollectionTable annotation. If omitted the collection table name defaults to the concatenation of the name of the containing entity and the name of the collection attribute, separated by an underscore. In our example, it would be User_nicknames."
msgstr ""
#. Tag: para
#: collection_mapping.xml:678
#, no-c-format
msgid "The column holding the basic type is set using the <classname>@Column annotation. If omitted, the column name defaults to the property name: in our example, it would be nicknames."
msgstr ""
#. Tag: para
#: collection_mapping.xml:683
#, no-c-format
msgid "But you are not limited to basic types, the collection type can be any embeddable object. To override the columns of the embeddable object in the collection table, use the <classname>@AttributeOverride annotation."
msgstr ""
#. Tag: title
#: collection_mapping.xml:689
#, no-c-format
msgid "@ElementCollection for embeddable objects"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:691
#, no-c-format
msgid ""
"@Entity\n"
"public class User {\n"
" [...]\n"
" public String getLastname() { ...}\n"
"\n"
" @ElementCollection\n"
" @CollectionTable(name=\"Addresses\", joinColumns=@JoinColumn(name=\"user_id\"))\n"
" @AttributeOverrides({\n"
" @AttributeOverride(name=\"street1\", column=@Column(name=\"fld_street\"))\n"
" })\n"
" public Set<Address> getAddresses() { ... } \n"
"}\n"
"\n"
"@Embeddable\n"
"public class Address {\n"
" public String getStreet1() {...}\n"
" [...]\n"
"}"
msgstr ""
#. Tag: para
#: collection_mapping.xml:694
#, no-c-format
msgid "Such an embeddable object cannot contains a collection itself."
msgstr ""
#. Tag: para
#: collection_mapping.xml:698
#, no-c-format
msgid "in <classname>@AttributeOverride, you must use the value. prefix to override properties of the embeddable object used in the map value and the key. prefix to override properties of the embeddable object used in the map key."
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:704
#, no-c-format
msgid ""
"@Entity\n"
"public class User {\n"
" @ElementCollection\n"
" @AttributeOverrides({\n"
" @AttributeOverride(name=\"key.street1\", column=@Column(name=\"fld_street\")),\n"
" @AttributeOverride(name=\"value.stars\", column=@Column(name=\"fld_note\"))\n"
" })\n"
" public Map<Address,Rating> getFavHomes() { ... }"
msgstr ""
#. Tag: para
#: collection_mapping.xml:708
#, no-c-format
msgid "We recommend you to migrate from <classname>@org.hibernate.annotations.CollectionOfElements to the new @ElementCollection annotation."
msgstr ""
#. Tag: para
#: collection_mapping.xml:714
#, no-c-format
msgid "Using the mapping file approach a collection of values is mapped using the <literal><element> tag. For example:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:718
#, no-c-format
msgid "<element> tag for collection values using mapping files"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:730
#, no-c-format
msgid ""
"<element\n"
" column=\"column_name\"\n"
" formula=\"any SQL expression\"\n"
" type=\"typename\"\n"
" length=\"L\"\n"
" precision=\"P\"\n"
" scale=\"S\"\n"
" not-null=\"true|false\"\n"
" unique=\"true|false\"\n"
" node=\"element-name\"\n"
"/>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:734
#, no-c-format
msgid "<literal>column (optional): the name of the column holding the collection element values."
msgstr ""
#. Tag: para
#: collection_mapping.xml:739
#, no-c-format
msgid "<literal>formula (optional): an SQL formula used to evaluate the element."
msgstr ""
#. Tag: para
#: collection_mapping.xml:744
#, no-c-format
msgid "<literal>type (required): the type of the collection element."
msgstr ""
#. Tag: title
#: collection_mapping.xml:754
#, no-c-format
msgid "Advanced collection mappings"
msgstr ""
#. Tag: title
#: collection_mapping.xml:757
#, no-c-format
msgid "Sorted collections"
msgstr ""
#. Tag: para
#: collection_mapping.xml:759
#, no-c-format
msgid "Hibernate supports collections implementing <literal>java.util.SortedMap and java.util.SortedSet. With annotations you declare a sort comparator using @Sort. You chose between the comparator types unsorted, natural or custom. If you want to use your own comparator implementation, you'll also have to specify the implementation class using the comparator attribute. Note that you need to use either a SortedSet or a SortedMap interface."
msgstr ""
#. Tag: title
#: collection_mapping.xml:770
#, no-c-format
msgid "Sorted collection with @Sort"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:772
#, no-c-format
msgid ""
"@OneToMany(cascade=CascadeType.ALL, fetch=FetchType.EAGER)\n"
"@JoinColumn(name=\"CUST_ID\")\n"
"@Sort(type = SortType.COMPARATOR, comparator = TicketComparator.class)\n"
"public SortedSet<Ticket> getTickets() {\n"
" return tickets;\n"
"}"
msgstr ""
#. Tag: para
#: collection_mapping.xml:775
#, no-c-format
msgid "Using Hibernate mapping files you specify a comparator in the mapping file with <literal><sort>:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:779
#, no-c-format
msgid "Sorted collection using xml mapping"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:781
#, no-c-format
msgid ""
"<set name=\"aliases\"\n"
" table=\"person_aliases\" \n"
" sort=\"natural\">\n"
" <key column=\"person\"/>\n"
" <element column=\"name\" type=\"string\"/>\n"
"</set>\n"
"\n"
"<map name=\"holidays\" sort=\"my.custom.HolidayComparator\">\n"
" <key column=\"year_id\"/>\n"
" <map-key column=\"hol_name\" type=\"string\"/>\n"
" <element column=\"hol_date\" type=\"date\"/>\n"
"</map>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:784
#, no-c-format
msgid "Allowed values of the <literal>sort attribute are unsorted, natural and the name of a class implementing java.util.Comparator."
msgstr ""
#. Tag: para
#: collection_mapping.xml:789
#, no-c-format
msgid "Sorted collections actually behave like <literal>java.util.TreeSet or java.util.TreeMap."
msgstr ""
#. Tag: para
#: collection_mapping.xml:794
#, no-c-format
msgid "If you want the database itself to order the collection elements, use the <literal>order-by attribute of set, bag or map mappings. This solution is implemented using LinkedHashSet or LinkedHashMap and performs the ordering in the SQL query and not in the memory."
msgstr ""
#. Tag: title
#: collection_mapping.xml:802
#, no-c-format
msgid "Sorting in database using order-by"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:804
#, no-c-format
msgid ""
"<set name=\"aliases\" table=\"person_aliases\" order-by=\"lower(name) asc\">\n"
" <key column=\"person\"/>\n"
" <element column=\"name\" type=\"string\"/>\n"
"</set>\n"
"\n"
"<map name=\"holidays\" order-by=\"hol_date, hol_name\">\n"
" <key column=\"year_id\"/>\n"
" <map-key column=\"hol_name\" type=\"string\"/>\n"
" <element column=\"hol_date type=\"date\"/>\n"
"</map>"
msgstr ""
#. Tag: title
#: collection_mapping.xml:808
#, no-c-format
msgid "Note"
msgstr ""
#. Tag: para
#: collection_mapping.xml:810
#, no-c-format
msgid "The value of the <literal>order-by attribute is an SQL ordering, not an HQL ordering."
msgstr ""
#. Tag: para
#: collection_mapping.xml:814
#, no-c-format
msgid "Associations can even be sorted by arbitrary criteria at runtime using a collection <literal>filter():"
msgstr ""
#. Tag: title
#: collection_mapping.xml:818
#, no-c-format
msgid "Sorting via a query filter"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:820
#, no-c-format
msgid "sortedUsers = s.createFilter( group.getUsers(), \"order by this.name\" ).list();"
msgstr ""
#. Tag: title
#: collection_mapping.xml:825
#, no-c-format
msgid "Bidirectional associations"
msgstr ""
#. Tag: para
#: collection_mapping.xml:827
#, no-c-format
msgid "A <emphasis>bidirectional association allows navigation from both \"ends\" of the association. Two kinds of bidirectional association are supported:"
msgstr ""
#. Tag: term
#: collection_mapping.xml:831
#, no-c-format
msgid "one-to-many"
msgstr ""
#. Tag: para
#: collection_mapping.xml:834
#, no-c-format
msgid "set or bag valued at one end and single-valued at the other"
msgstr ""
#. Tag: term
#: collection_mapping.xml:840
#, no-c-format
msgid "many-to-many"
msgstr ""
#. Tag: para
#: collection_mapping.xml:843
#, no-c-format
msgid "set or bag valued at both ends"
msgstr ""
#. Tag: para
#: collection_mapping.xml:848
#, no-c-format
msgid "Often there exists a many to one association which is the owner side of a bidirectional relationship. The corresponding one to many association is in this case annotated by <literal>@OneToMany(mappedBy=...)"
msgstr ""
#. Tag: title
#: collection_mapping.xml:854
#, no-c-format
msgid "Bidirectional one to many with many to one side as association owner"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:857
#, no-c-format
msgid ""
"@Entity\n"
"public class Troop {\n"
" @OneToMany(mappedBy=\"troop\")\n"
" public Set<Soldier> getSoldiers() {\n"
" ...\n"
"}\n"
"\n"
"@Entity\n"
"public class Soldier {\n"
" @ManyToOne\n"
" @JoinColumn(name=\"troop_fk\")\n"
" public Troop getTroop() {\n"
" ...\n"
"}"
msgstr ""
#. Tag: para
#: collection_mapping.xml:860
#, no-c-format
msgid "<classname>Troop has a bidirectional one to many relationship with Soldier through the troop property. You don't have to (must not) define any physical mapping in the mappedBy side."
msgstr ""
#. Tag: para
#: collection_mapping.xml:865
#, no-c-format
msgid "To map a bidirectional one to many, with the one-to-many side as the owning side, you have to remove the <literal>mappedBy element and set the many to one @JoinColumn as insertable and updatable to false. This solution is not optimized and will produce additional UPDATE statements."
msgstr ""
#. Tag: title
#: collection_mapping.xml:872
#, no-c-format
msgid "Bidirectional associtaion with one to many side as owner"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:875
#, no-c-format
msgid ""
"@Entity\n"
"public class Troop {\n"
" @OneToMany\n"
" @JoinColumn(name=\"troop_fk\") //we need to duplicate the physical information\n"
" public Set<Soldier> getSoldiers() {\n"
" ...\n"
"}\n"
"\n"
"@Entity\n"
"public class Soldier {\n"
" @ManyToOne\n"
" @JoinColumn(name=\"troop_fk\", insertable=false, updatable=false)\n"
" public Troop getTroop() {\n"
" ...\n"
"}"
msgstr ""
#. Tag: para
#: collection_mapping.xml:878
#, no-c-format
msgid "How does the mappping of a bidirectional mapping look like in Hibernate mapping xml? There you define a bidirectional one-to-many association by mapping a one-to-many association to the same table column(s) as a many-to-one association and declaring the many-valued end <literal>inverse=\"true\"."
msgstr ""
#. Tag: title
#: collection_mapping.xml:885
#, no-c-format
msgid "Bidirectional one to many via Hibernate mapping files"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:887
#, no-c-format
msgid ""
"<class name=\"Parent\">\n"
" <id name=\"id\" column=\"parent_id\"/>\n"
" ....\n"
" <set name=\"children\" inverse=\"true\">\n"
" <key column=\"parent_id\"/>\n"
" <one-to-many class=\"Child\"/>\n"
" </set>\n"
"</class>\n"
"\n"
"<class name=\"Child\">\n"
" <id name=\"id\" column=\"child_id\"/>\n"
" ....\n"
" <many-to-one name=\"parent\" \n"
" class=\"Parent\" \n"
" column=\"parent_id\"\n"
" not-null=\"true\"/>\n"
"</class>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:890
#, no-c-format
msgid "Mapping one end of an association with <literal>inverse=\"true\" does not affect the operation of cascades as these are orthogonal concepts."
msgstr ""
#. Tag: para
#: collection_mapping.xml:894
#, no-c-format
msgid "A many-to-many association is defined logically using the <literal>@ManyToMany annotation. You also have to describe the association table and the join conditions using the @JoinTable annotation. If the association is bidirectional, one side has to be the owner and one side has to be the inverse end (ie. it will be ignored when updating the relationship values in the association table):"
msgstr ""
#. Tag: title
#: collection_mapping.xml:903
#, no-c-format
msgid "Many to many association via @ManyToMany"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:905
#, no-c-format
msgid ""
"@Entity\n"
"public class Employer implements Serializable {\n"
" @ManyToMany(\n"
" targetEntity=org.hibernate.test.metadata.manytomany.Employee.class,\n"
" cascade={CascadeType.PERSIST, CascadeType.MERGE}\n"
" )\n"
" @JoinTable(\n"
" name=\"EMPLOYER_EMPLOYEE\",\n"
" joinColumns=@JoinColumn(name=\"EMPER_ID\"),\n"
" inverseJoinColumns=@JoinColumn(name=\"EMPEE_ID\")\n"
" )\n"
" public Collection getEmployees() {\n"
" return employees;\n"
" }\n"
" ...\n"
"}"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:907
#, no-c-format
msgid ""
"@Entity\n"
"public class Employee implements Serializable {\n"
" @ManyToMany(\n"
" cascade = {CascadeType.PERSIST, CascadeType.MERGE},\n"
" mappedBy = \"employees\",\n"
" targetEntity = Employer.class\n"
" )\n"
" public Collection getEmployers() {\n"
" return employers;\n"
" }\n"
"}"
msgstr ""
#. Tag: para
#: collection_mapping.xml:910
#, no-c-format
msgid "In this example <classname>@JoinTable defines a name, an array of join columns, and an array of inverse join columns. The latter ones are the columns of the association table which refer to the Employee primary key (the \"other side\"). As seen previously, the other side don't have to (must not) describe the physical mapping: a simple mappedBy argument containing the owner side property name bind the two."
msgstr ""
#. Tag: para
#: collection_mapping.xml:919
#, no-c-format
msgid "As any other annotations, most values are guessed in a many to many relationship. Without describing any physical mapping in a unidirectional many to many the following rules applied. The table name is the concatenation of the owner table name, <keycap>_ and the other side table name. The foreign key name(s) referencing the owner table is the concatenation of the owner table name, _ and the owner primary key column(s). The foreign key name(s) referencing the other side is the concatenation of the owner property name, _, and the other side primary key column(s). These are the same rules used for a unidirectional one to many relationship."
msgstr ""
#. Tag: title
#: collection_mapping.xml:932
#, no-c-format
msgid "Default values for <classname>@ManyToMany (uni-directional)"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:935
#, no-c-format
msgid ""
"@Entity\n"
"public class Store {\n"
" @ManyToMany(cascade = CascadeType.PERSIST)\n"
" public Set<City> getImplantedIn() {\n"
" ...\n"
" }\n"
"}\n"
"\n"
"@Entity\n"
"public class City {\n"
" ... //no bidirectional relationship\n"
"}"
msgstr ""
#. Tag: para
#: collection_mapping.xml:938
#, no-c-format
msgid "A <literal>Store_City is used as the join table. The Store_id column is a foreign key to the Store table. The implantedIn_id column is a foreign key to the City table."
msgstr ""
#. Tag: para
#: collection_mapping.xml:943
#, no-c-format
msgid "Without describing any physical mapping in a bidirectional many to many the following rules applied. The table name is the concatenation of the owner table name, <keycap>_ and the other side table name. The foreign key name(s) referencing the owner table is the concatenation of the other side property name, _, and the owner primary key column(s). The foreign key name(s) referencing the other side is the concatenation of the owner property name, _, and the other side primary key column(s). These are the same rules used for a unidirectional one to many relationship."
msgstr ""
#. Tag: title
#: collection_mapping.xml:955
#, no-c-format
msgid "Default values for <classname>@ManyToMany (bi-directional)"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:958
#, no-c-format
msgid ""
"@Entity\n"
"public class Store {\n"
" @ManyToMany(cascade = {CascadeType.PERSIST, CascadeType.MERGE})\n"
" public Set<Customer> getCustomers() {\n"
" ...\n"
" }\n"
"}\n"
"\n"
"@Entity\n"
"public class Customer {\n"
" @ManyToMany(mappedBy=\"customers\")\n"
" public Set<Store> getStores() {\n"
" ...\n"
" }\n"
"}"
msgstr ""
#. Tag: para
#: collection_mapping.xml:961
#, no-c-format
msgid "A <literal>Store_Customer is used as the join table. The stores_id column is a foreign key to the Store table. The customers_id column is a foreign key to the Customer table."
msgstr ""
#. Tag: para
#: collection_mapping.xml:966
#, no-c-format
msgid "Using Hibernate mapping files you can map a bidirectional many-to-many association by mapping two many-to-many associations to the same database table and declaring one end as <emphasis>inverse."
msgstr ""
#. Tag: para
#: collection_mapping.xml:970
#, no-c-format
msgid "You cannot select an indexed collection."
msgstr ""
#. Tag: para
#: collection_mapping.xml:973
#, no-c-format
msgid "shows a bidirectional many-to-many association that illustrates how each category can have many items and each item can be in many categories:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:979
#, no-c-format
msgid "Many to many association using Hibernate mapping files"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:981
#, no-c-format
msgid ""
"<class name=\"Category\">\n"
" <id name=\"id\" column=\"CATEGORY_ID\"/>\n"
" ...\n"
" <bag name=\"items\" table=\"CATEGORY_ITEM\">\n"
" <key column=\"CATEGORY_ID\"/>\n"
" <many-to-many class=\"Item\" column=\"ITEM_ID\"/>\n"
" </bag>\n"
"</class>\n"
"\n"
"<class name=\"Item\">\n"
" <id name=\"id\" column=\"ITEM_ID\"/>\n"
" ...\n"
"\n"
" <!-- inverse end -->\n"
" <bag name=\"categories\" table=\"CATEGORY_ITEM\" inverse=\"true\">\n"
" <key column=\"ITEM_ID\"/>\n"
" <many-to-many class=\"Category\" column=\"CATEGORY_ID\"/>\n"
" </bag>\n"
"</class>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:984
#, no-c-format
msgid "Changes made only to the inverse end of the association are <emphasis>not persisted. This means that Hibernate has two representations in memory for every bidirectional association: one link from A to B and another link from B to A. This is easier to understand if you think about the Java object model and how a many-to-many relationship in Javais created:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:992
#, no-c-format
msgid "Effect of inverse vs. non-inverse side of many to many associations"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:995
#, no-c-format
msgid ""
"category.getItems().add(item); // The category now \"knows\" about the relationship\n"
"item.getCategories().add(category); // The item now \"knows\" about the relationship\n"
"\n"
"session.persist(item); // The relationship won't be saved!\n"
"session.persist(category); // The relationship will be saved"
msgstr ""
#. Tag: para
#: collection_mapping.xml:998
#, no-c-format
msgid "The non-inverse side is used to save the in-memory representation to the database."
msgstr ""
#. Tag: title
#: collection_mapping.xml:1003
#, no-c-format
msgid "Bidirectional associations with indexed collections"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1005
#, no-c-format
msgid "There are some additional considerations for bidirectional mappings with indexed collections (where one end is represented as a <literal><list> or <map>) when using Hibernate mapping files. If there is a property of the child class that maps to the index column you can use inverse=\"true\" on the collection mapping:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:1013
#, no-c-format
msgid "Bidirectional association with indexed collection"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1015
#, no-c-format
msgid ""
"<class name=\"Parent\">\n"
" <id name=\"id\" column=\"parent_id\"/>\n"
" ....\n"
" <map name=\"children\" inverse=\"true\">\n"
" <key column=\"parent_id\"/>\n"
" <map-key column=\"name\" \n"
" type=\"string\"/>\n"
" <one-to-many class=\"Child\"/>\n"
" </map>\n"
"</class>\n"
"\n"
"<class name=\"Child\">\n"
" <id name=\"id\" column=\"child_id\"/>\n"
" ....\n"
" <property name=\"name\" \n"
" not-null=\"true\"/>\n"
" <many-to-one name=\"parent\" \n"
" class=\"Parent\" \n"
" column=\"parent_id\"\n"
" not-null=\"true\"/>\n"
"</class>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1018
#, no-c-format
msgid "If there is no such property on the child class, the association cannot be considered truly bidirectional. That is, there is information available at one end of the association that is not available at the other end. In this case, you cannot map the collection <literal>inverse=\"true\". Instead, you could use the following mapping:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:1026
#, no-c-format
msgid "Bidirectional association with indexed collection, but no index column"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1029
#, no-c-format
msgid ""
"<class name=\"Parent\">\n"
" <id name=\"id\" column=\"parent_id\"/>\n"
" ....\n"
" <map name=\"children\">\n"
" <key column=\"parent_id\"\n"
" not-null=\"true\"/>\n"
" <map-key column=\"name\" \n"
" type=\"string\"/>\n"
" <one-to-many class=\"Child\"/>\n"
" </map>\n"
"</class>\n"
"\n"
"<class name=\"Child\">\n"
" <id name=\"id\" column=\"child_id\"/>\n"
" ....\n"
" <many-to-one name=\"parent\" \n"
" class=\"Parent\" \n"
" column=\"parent_id\"\n"
" insert=\"false\"\n"
" update=\"false\"\n"
" not-null=\"true\"/>\n"
"</class>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1032
#, no-c-format
msgid "Note that in this mapping, the collection-valued end of the association is responsible for updates to the foreign key."
msgstr ""
#. Tag: title
#: collection_mapping.xml:1037
#, no-c-format
msgid "Ternary associations"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1039
#, no-c-format
msgid "There are three possible approaches to mapping a ternary association. One approach is to use a <literal>Map with an association as its index:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:1044
#, no-c-format
msgid "Ternary association mapping"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1046
#, no-c-format
msgid ""
"@Entity\n"
"public class Company {\n"
" @Id \n"
" int id;\n"
" ...\n"
" @OneToMany // unidirectional\n"
" @MapKeyJoinColumn(name=\"employee_id\")\n"
" Map<Employee, Contract> contracts;\n"
"}\n"
"\n"
"// or\n"
"\n"
"<map name=\"contracts\">\n"
" <key column=\"employer_id\" not-null=\"true\"/>\n"
" <map-key-many-to-many column=\"employee_id\" class=\"Employee\"/>\n"
" <one-to-many class=\"Contract\"/>\n"
"</map>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1049
#, no-c-format
msgid "A second approach is to remodel the association as an entity class. This is the most common approach. A final alternative is to use composite elements, which will be discussed later."
msgstr ""
#. Tag: literal
#: collection_mapping.xml:1055
#, no-c-format
msgid "Using an <idbag>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1057
#, no-c-format
msgid "The majority of the many-to-many associations and collections of values shown previously all map to tables with composite keys, even though it has been suggested that entities should have synthetic identifiers (surrogate keys). A pure association table does not seem to benefit much from a surrogate key, although a collection of composite values <emphasis>might. For this reason Hibernate provides a feature that allows you to map many-to-many associations and collections of values to a table with a surrogate key."
msgstr ""
#. Tag: para
#: collection_mapping.xml:1066
#, no-c-format
msgid "The <literal><idbag> element lets you map a List (or Collection) with bag semantics. For example:"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1070
#, no-c-format
msgid ""
"<idbag name=\"lovers\" table=\"LOVERS\">\n"
" <collection-id column=\"ID\" type=\"long\">\n"
" <generator class=\"sequence\"/>\n"
" </collection-id>\n"
" <key column=\"PERSON1\"/>\n"
" <many-to-many column=\"PERSON2\" class=\"Person\" fetch=\"join\"/>\n"
"</idbag>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1072
#, no-c-format
msgid "An <literal><idbag> has a synthetic id generator, just like an entity class. A different surrogate key is assigned to each collection row. Hibernate does not, however, provide any mechanism for discovering the surrogate key value of a particular row."
msgstr ""
#. Tag: para
#: collection_mapping.xml:1077
#, no-c-format
msgid "The update performance of an <literal><idbag> supersedes a regular <bag>. Hibernate can locate individual rows efficiently and update or delete them individually, similar to a list, map or set."
msgstr ""
#. Tag: para
#: collection_mapping.xml:1082
#, no-c-format
msgid "In the current implementation, the <literal>native identifier generation strategy is not supported for <idbag> collection identifiers."
msgstr ""
#. Tag: title
#: collection_mapping.xml:1103
#, no-c-format
msgid "Collection examples"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1105
#, no-c-format
msgid "This section covers collection examples."
msgstr ""
#. Tag: para
#: collection_mapping.xml:1107
#, no-c-format
msgid "The following class has a collection of <literal>Child instances:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:1111
#, no-c-format
msgid "Example classes <classname>Parent and Child"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1114
#, no-c-format
msgid ""
"public class Parent {\n"
" private long id;\n"
" private Set<Child> children;\n"
"\n"
" // getter/setter\n"
" ...\n"
"}\n"
"\n"
"\n"
"public class Child {\n"
" private long id;\n"
" private String name\n"
"\n"
" \n"
" // getter/setter\n"
" ...\n"
"}"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1117
#, no-c-format
msgid "If each child has, at most, one parent, the most natural mapping is a one-to-many association:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:1121
#, no-c-format
msgid "One to many unidirectional <classname>Parent-Child relationship using annotations"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1124
#, no-c-format
msgid ""
"public class Parent {\n"
" @Id\n"
" @GeneratedValue\n"
" private long id;\n"
"\n"
" @OneToMany\n"
" private Set<Child> children;\n"
"\n"
" // getter/setter\n"
" ...\n"
"}\n"
"\n"
"\n"
"public class Child {\n"
" @Id\n"
" @GeneratedValue\n"
" private long id;\n"
" private String name;\n"
"\n"
" \n"
" // getter/setter\n"
" ...\n"
"}"
msgstr ""
#. Tag: title
#: collection_mapping.xml:1128
#, no-c-format
msgid "One to many unidirectional <classname>Parent-Child relationship using mapping files"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1131
#, no-c-format
msgid ""
"<hibernate-mapping>\n"
"\n"
" <class name=\"Parent\">\n"
" <id name=\"id\">\n"
" <generator class=\"sequence\"/>\n"
" </id>\n"
" <set name=\"children\">\n"
" <key column=\"parent_id\"/>\n"
" <one-to-many class=\"Child\"/>\n"
" </set>\n"
" </class>\n"
"\n"
" <class name=\"Child\">\n"
" <id name=\"id\">\n"
" <generator class=\"sequence\"/>\n"
" </id>\n"
" <property name=\"name\"/>\n"
" </class>\n"
"\n"
"</hibernate-mapping>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1134
#, no-c-format
msgid "This maps to the following table definitions:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:1137
#, no-c-format
msgid "Table definitions for unidirectional <classname>Parent-Child relationship"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1141
#, no-c-format
msgid ""
"create table parent ( id bigint not null primary key )\n"
"create table child ( id bigint not null primary key, name varchar(255), parent_id bigint )\n"
"alter table child add constraint childfk0 (parent_id) references parent"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1144
#, no-c-format
msgid "If the parent is <emphasis>required, use a bidirectional one-to-many association:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:1148
#, no-c-format
msgid "One to many bidirectional <classname>Parent-Child relationship using annotations"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1151
#, no-c-format
msgid ""
"public class Parent {\n"
" @Id\n"
" @GeneratedValue\n"
" private long id;\n"
"\n"
" @OneToMany(mappedBy=\"parent\")\n"
" private Set<Child> children;\n"
"\n"
" // getter/setter\n"
" ...\n"
"}\n"
"\n"
"\n"
"public class Child {\n"
" @Id\n"
" @GeneratedValue\n"
" private long id;\n"
"\n"
" private String name;\n"
" \n"
" @ManyToOne\n"
" private Parent parent;\n"
"\n"
" \n"
" // getter/setter\n"
" ...\n"
"}"
msgstr ""
#. Tag: title
#: collection_mapping.xml:1155
#, no-c-format
msgid "One to many bidirectional <classname>Parent-Child relationship using mapping files"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1158
#, no-c-format
msgid ""
"<hibernate-mapping>\n"
"\n"
" <class name=\"Parent\">\n"
" <id name=\"id\">\n"
" <generator class=\"sequence\"/>\n"
" </id>\n"
" <set name=\"children\" inverse=\"true\">\n"
" <key column=\"parent_id\"/>\n"
" <one-to-many class=\"Child\"/>\n"
" </set>\n"
" </class>\n"
"\n"
" <class name=\"Child\">\n"
" <id name=\"id\">\n"
" <generator class=\"sequence\"/>\n"
" </id>\n"
" <property name=\"name\"/>\n"
" <many-to-one name=\"parent\" class=\"Parent\" column=\"parent_id\" not-null=\"true\"/>\n"
" </class>\n"
"\n"
"</hibernate-mapping>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1161
#, no-c-format
msgid "Notice the <literal>NOT NULL constraint:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:1164
#, no-c-format
msgid "Table definitions for bidirectional <classname>Parent-Child relationship"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1168
#, no-c-format
msgid ""
"create table parent ( id bigint not null primary key )\n"
"create table child ( id bigint not null\n"
" primary key,\n"
" name varchar(255),\n"
" parent_id bigint not null )\n"
"alter table child add constraint childfk0 (parent_id) references parent"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1171
#, no-c-format
msgid "Alternatively, if this association must be unidirectional you can enforce the <literal>NOT NULL constraint."
msgstr ""
#. Tag: title
#: collection_mapping.xml:1175
#, no-c-format
msgid "Enforcing NOT NULL constraint in unidirectional relation using annotations"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1178
#, no-c-format
msgid ""
"public class Parent {\n"
" @Id\n"
" @GeneratedValue\n"
" private long id;\n"
"\n"
" @OneToMany(optional=false)\n"
" private Set<Child> children;\n"
"\n"
" // getter/setter\n"
" ...\n"
"}\n"
"\n"
"\n"
"public class Child {\n"
" @Id\n"
" @GeneratedValue\n"
" private long id;\n"
" private String name;\n"
"\n"
" \n"
" // getter/setter\n"
" ...\n"
"}"
msgstr ""
#. Tag: title
#: collection_mapping.xml:1182
#, no-c-format
msgid "Enforcing NOT NULL constraint in unidirectional relation using mapping files"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1185
#, no-c-format
msgid ""
"<hibernate-mapping>\n"
"\n"
" <class name=\"Parent\">\n"
" <id name=\"id\">\n"
" <generator class=\"sequence\"/>\n"
" </id>\n"
" <set name=\"children\">\n"
" <key column=\"parent_id\" not-null=\"true\"/>\n"
" <one-to-many class=\"Child\"/>\n"
" </set>\n"
" </class>\n"
"\n"
" <class name=\"Child\">\n"
" <id name=\"id\">\n"
" <generator class=\"sequence\"/>\n"
" </id>\n"
" <property name=\"name\"/>\n"
" </class>\n"
"\n"
"</hibernate-mapping>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1188
#, no-c-format
msgid "On the other hand, if a child has multiple parents, a many-to-many association is appropriate."
msgstr ""
#. Tag: title
#: collection_mapping.xml:1192
#, no-c-format
msgid "Many to many <classname>Parent-Child relationship using annotations"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1195
#, no-c-format
msgid ""
"public class Parent {\n"
" @Id\n"
" @GeneratedValue\n"
" private long id;\n"
"\n"
" @ManyToMany\n"
" private Set<Child> children;\n"
"\n"
" // getter/setter\n"
" ...\n"
"}\n"
"\n"
"\n"
"public class Child {\n"
" @Id\n"
" @GeneratedValue\n"
" private long id;\n"
"\n"
" private String name;\n"
"\n"
" \n"
" // getter/setter\n"
" ...\n"
"}"
msgstr ""
#. Tag: title
#: collection_mapping.xml:1199
#, no-c-format
msgid "Many to many <classname>Parent-Child relationship using mapping files"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1202
#, no-c-format
msgid ""
"<hibernate-mapping>\n"
"\n"
" <class name=\"Parent\">\n"
" <id name=\"id\">\n"
" <generator class=\"sequence\"/>\n"
" </id>\n"
" <set name=\"children\" table=\"childset\">\n"
" <key column=\"parent_id\"/>\n"
" <many-to-many class=\"Child\" column=\"child_id\"/>\n"
" </set>\n"
" </class>\n"
"\n"
" <class name=\"Child\">\n"
" <id name=\"id\">\n"
" <generator class=\"sequence\"/>\n"
" </id>\n"
" <property name=\"name\"/>\n"
" </class>\n"
"\n"
"</hibernate-mapping>"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1205
#, no-c-format
msgid "Table definitions:"
msgstr ""
#. Tag: title
#: collection_mapping.xml:1208
#, no-c-format
msgid "Table definitions for many to many releationship"
msgstr ""
#. Tag: programlisting
#: collection_mapping.xml:1210
#, no-c-format
msgid ""
"create table parent ( id bigint not null primary key )\n"
"create table child ( id bigint not null primary key, name varchar(255) )\n"
"create table childset ( parent_id bigint not null,\n"
" child_id bigint not null,\n"
" primary key ( parent_id, child_id ) )\n"
"alter table childset add constraint childsetfk0 (parent_id) references parent\n"
"alter table childset add constraint childsetfk1 (child_id) references child"
msgstr ""
#. Tag: para
#: collection_mapping.xml:1213
#, no-c-format
msgid "For more examples and a complete explanation of a parent/child relationship mapping, see <xref linkend=\"example-parentchild\"/> for more information. Even more complex association mappings are covered in the next chapter."
msgstr ""
Other Hibernate examples (source code examples)
Here is a short list of links related to this Hibernate collection_mapping.pot source code file:
|
The search page
Other Hibernate source code examples at this package level
Click here to learn more about this project
