← Back to branch summary

~raginggoblin/infolog/infolog

« back to all changes in this revision

Viewing changes to InfologServer/lib/hibernate-distribution-3.3.2.GA/project/documentation/manual/src/main/docbook/pot/content/persistent_classes.pot

  • Committer: Raging Goblin
  • Date: 2013-11-16 16:51:32 UTC
  • Revision ID: raging_goblin-20131116165132-weujnptzc88uy4ah
Mavenized the project, now using shared project InfologSync

Show diffs side-by-side

added added

removed removed

Lines of Context:
InfologServer/lib/hibernate-distribution-3.3.2.GA/project/documentation/manual/src/main/docbook/pot/content/persistent_classes.pot
1
 
# SOME DESCRIPTIVE TITLE.
2
 
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
3
 
#
4
 
#, fuzzy
5
 
msgid ""
6
 
msgstr ""
7
 
"Project-Id-Version: PACKAGE VERSION\n"
8
 
"Report-Msgid-Bugs-To: http://bugs.kde.org\n"
9
 
"POT-Creation-Date: 2009-06-10 21:02+0000\n"
10
 
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
11
 
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
12
 
"Language-Team: LANGUAGE <kde-i18n-doc@kde.org>\n"
13
 
"MIME-Version: 1.0\n"
14
 
"Content-Type: application/x-xml2pot; charset=UTF-8\n"
15
 
"Content-Transfer-Encoding: 8bit\n"
16
 
 
17
 
#. Tag: title
18
 
#: persistent_classes.xml:29
19
 
#, no-c-format
20
 
msgid "Persistent Classes"
21
 
msgstr ""
22
 
 
23
 
#. Tag: para
24
 
#: persistent_classes.xml:31
25
 
#, no-c-format
26
 
msgid "Persistent classes are classes in an application that implement the entities of the business problem (e.g. Customer and Order in an E-commerce application). Not all instances of a persistent class are considered to be in the persistent state. For example, an instance can instead be transient or detached."
27
 
msgstr ""
28
 
 
29
 
#. Tag: para
30
 
#: persistent_classes.xml:38
31
 
#, no-c-format
32
 
msgid "Hibernate works best if these classes follow some simple rules, also known as the Plain Old Java Object (POJO) programming model. However, none of these rules are hard requirements. Indeed, Hibernate3 assumes very little about the nature of your persistent objects. You can express a domain model in other ways (using trees of <literal>Map</literal> instances, for example)."
33
 
msgstr ""
34
 
 
35
 
#. Tag: title
36
 
#: persistent_classes.xml:47
37
 
#, no-c-format
38
 
msgid "A simple POJO example"
39
 
msgstr ""
40
 
 
41
 
#. Tag: para
42
 
#: persistent_classes.xml:49
43
 
#, no-c-format
44
 
msgid "Most Java applications require a persistent class representing felines. For example:"
45
 
msgstr ""
46
 
 
47
 
#. Tag: programlisting
48
 
#: persistent_classes.xml:53
49
 
#, no-c-format
50
 
msgid ""
51
 
      "<![CDATA[package eg;\n"
52
 
      "import java.util.Set;\n"
53
 
      "import java.util.Date;\n"
54
 
      "\n"
55
 
      "public class Cat {\n"
56
 
      "    private Long id; // identifier\n"
57
 
      "\n"
58
 
      "    private Date birthdate;\n"
59
 
      "    private Color color;\n"
60
 
      "    private char sex;\n"
61
 
      "    private float weight;\n"
62
 
      "    private int litterId;\n"
63
 
      "\n"
64
 
      "    private Cat mother;\n"
65
 
      "    private Set kittens = new HashSet();\n"
66
 
      "\n"
67
 
      "    private void setId(Long id) {\n"
68
 
      "        this.id=id;\n"
69
 
      "    }\n"
70
 
      "    public Long getId() {\n"
71
 
      "        return id;\n"
72
 
      "    }\n"
73
 
      "\n"
74
 
      "    void setBirthdate(Date date) {\n"
75
 
      "        birthdate = date;\n"
76
 
      "    }\n"
77
 
      "    public Date getBirthdate() {\n"
78
 
      "        return birthdate;\n"
79
 
      "    }\n"
80
 
      "\n"
81
 
      "    void setWeight(float weight) {\n"
82
 
      "        this.weight = weight;\n"
83
 
      "    }\n"
84
 
      "    public float getWeight() {\n"
85
 
      "        return weight;\n"
86
 
      "    }\n"
87
 
      "\n"
88
 
      "    public Color getColor() {\n"
89
 
      "        return color;\n"
90
 
      "    }\n"
91
 
      "    void setColor(Color color) {\n"
92
 
      "        this.color = color;\n"
93
 
      "    }\n"
94
 
      "\n"
95
 
      "    void setSex(char sex) {\n"
96
 
      "        this.sex=sex;\n"
97
 
      "    }\n"
98
 
      "    public char getSex() {\n"
99
 
      "        return sex;\n"
100
 
      "    }\n"
101
 
      "\n"
102
 
      "    void setLitterId(int id) {\n"
103
 
      "        this.litterId = id;\n"
104
 
      "    }\n"
105
 
      "    public int getLitterId() {\n"
106
 
      "        return litterId;\n"
107
 
      "    }\n"
108
 
      "\n"
109
 
      "    void setMother(Cat mother) {\n"
110
 
      "        this.mother = mother;\n"
111
 
      "    }\n"
112
 
      "    public Cat getMother() {\n"
113
 
      "        return mother;\n"
114
 
      "    }\n"
115
 
      "    void setKittens(Set kittens) {\n"
116
 
      "        this.kittens = kittens;\n"
117
 
      "    }\n"
118
 
      "    public Set getKittens() {\n"
119
 
      "        return kittens;\n"
120
 
      "    }\n"
121
 
      "    \n"
122
 
      "    // addKitten not needed by Hibernate\n"
123
 
      "    public void addKitten(Cat kitten) {\n"
124
 
      "            kitten.setMother(this);\n"
125
 
      "        kitten.setLitterId( kittens.size() ); \n"
126
 
      "        kittens.add(kitten);\n"
127
 
      "    }\n"
128
 
      "}]]>"
129
 
msgstr ""
130
 
 
131
 
#. Tag: para
132
 
#: persistent_classes.xml:55
133
 
#, no-c-format
134
 
msgid "The four main rules of persistent classes are explored in more detail in the following sections."
135
 
msgstr ""
136
 
 
137
 
#. Tag: title
138
 
#: persistent_classes.xml:61
139
 
#, no-c-format
140
 
msgid "Implement a no-argument constructor"
141
 
msgstr ""
142
 
 
143
 
#. Tag: para
144
 
#: persistent_classes.xml:63
145
 
#, no-c-format
146
 
msgid "<literal>Cat</literal> has a no-argument constructor. All persistent classes must have a default constructor (which can be non-public) so that Hibernate can instantiate them using <literal>Constructor.newInstance()</literal>. It is recommended that you have a default constructor with at least <emphasis>package</emphasis> visibility for runtime proxy generation in Hibernate."
147
 
msgstr ""
148
 
 
149
 
#. Tag: title
150
 
#: persistent_classes.xml:73
151
 
#, no-c-format
152
 
msgid "Provide an identifier property (optional)"
153
 
msgstr ""
154
 
 
155
 
#. Tag: para
156
 
#: persistent_classes.xml:75
157
 
#, no-c-format
158
 
msgid "<literal>Cat</literal> has a property called <literal>id</literal>. This property maps to the primary key column of a database table. The property might have been called anything, and its type might have been any primitive type, any primitive \"wrapper\" type, <literal>java.lang.String</literal> or <literal>java.util.Date</literal>. If your legacy database table has composite keys, you can use a user-defined class with properties of these types (see the section on composite identifiers later in the chapter.)"
159
 
msgstr ""
160
 
 
161
 
#. Tag: para
162
 
#: persistent_classes.xml:84
163
 
#, no-c-format
164
 
msgid "The identifier property is strictly optional. You can leave them off and let Hibernate keep track of object identifiers internally. We do not recommend this, however."
165
 
msgstr ""
166
 
 
167
 
#. Tag: para
168
 
#: persistent_classes.xml:89
169
 
#, no-c-format
170
 
msgid "In fact, some functionality is available only to classes that declare an identifier property:"
171
 
msgstr ""
172
 
 
173
 
#. Tag: para
174
 
#: persistent_classes.xml:96
175
 
#, no-c-format
176
 
msgid "Transitive reattachment for detached objects (cascade update or cascade merge) - see"
177
 
msgstr ""
178
 
 
179
 
#. Tag: literal
180
 
#: persistent_classes.xml:103
181
 
#, no-c-format
182
 
msgid "Session.saveOrUpdate()"
183
 
msgstr ""
184
 
 
185
 
#. Tag: literal
186
 
#: persistent_classes.xml:108
187
 
#, no-c-format
188
 
msgid "Session.merge()"
189
 
msgstr ""
190
 
 
191
 
#. Tag: para
192
 
#: persistent_classes.xml:113
193
 
#, no-c-format
194
 
msgid "We recommend that you declare consistently-named identifier properties on persistent classes and that you use a nullable (i.e., non-primitive) type."
195
 
msgstr ""
196
 
 
197
 
#. Tag: title
198
 
#: persistent_classes.xml:120
199
 
#, no-c-format
200
 
msgid "Prefer non-final classes (optional)"
201
 
msgstr ""
202
 
 
203
 
#. Tag: para
204
 
#: persistent_classes.xml:121
205
 
#, no-c-format
206
 
msgid "A central feature of Hibernate, <emphasis>proxies</emphasis>, depends upon the persistent class being either non-final, or the implementation of an interface that declares all public methods."
207
 
msgstr ""
208
 
 
209
 
#. Tag: para
210
 
#: persistent_classes.xml:126
211
 
#, no-c-format
212
 
msgid "You can persist <literal>final</literal> classes that do not implement an interface with Hibernate. You will not, however, be able to use proxies for lazy association fetching which will ultimately limit your options for performance tuning."
213
 
msgstr ""
214
 
 
215
 
#. Tag: para
216
 
#: persistent_classes.xml:131
217
 
#, no-c-format
218
 
msgid "You should also avoid declaring <literal>public final</literal> methods on the non-final classes. If you want to use a class with a <literal>public final</literal> method, you must explicitly disable proxying by setting <literal>lazy=\"false\"</literal>."
219
 
msgstr ""
220
 
 
221
 
#. Tag: title
222
 
#: persistent_classes.xml:139
223
 
#, no-c-format
224
 
msgid "Declare accessors and mutators for persistent fields (optional)"
225
 
msgstr ""
226
 
 
227
 
#. Tag: para
228
 
#: persistent_classes.xml:141
229
 
#, no-c-format
230
 
msgid "<literal>Cat</literal> declares accessor methods for all its persistent fields. Many other ORM tools directly persist instance variables. It is better to provide an indirection between the relational schema and internal data structures of the class. By default, Hibernate persists JavaBeans style properties and recognizes method names of the form <literal>getFoo</literal>, <literal>isFoo</literal> and <literal>setFoo</literal>. If required, you can switch to direct field access for particular properties."
231
 
msgstr ""
232
 
 
233
 
#. Tag: para
234
 
#: persistent_classes.xml:151
235
 
#, no-c-format
236
 
msgid "Properties need <emphasis>not</emphasis> be declared public - Hibernate can persist a property with a default, <literal>protected</literal> or <literal>private</literal> get / set pair."
237
 
msgstr ""
238
 
 
239
 
#. Tag: title
240
 
#: persistent_classes.xml:162
241
 
#, no-c-format
242
 
msgid "Implementing inheritance"
243
 
msgstr ""
244
 
 
245
 
#. Tag: para
246
 
#: persistent_classes.xml:164
247
 
#, no-c-format
248
 
msgid "A subclass must also observe the first and second rules. It inherits its identifier property from the superclass, <literal>Cat</literal>. For example:"
249
 
msgstr ""
250
 
 
251
 
#. Tag: programlisting
252
 
#: persistent_classes.xml:169
253
 
#, no-c-format
254
 
msgid ""
255
 
      "<![CDATA[package eg;\n"
256
 
      "\n"
257
 
      "public class DomesticCat extends Cat {\n"
258
 
      "        private String name;\n"
259
 
      "\n"
260
 
      "        public String getName() {\n"
261
 
      "                return name;\n"
262
 
      "        }\n"
263
 
      "        protected void setName(String name) {\n"
264
 
      "                this.name=name;\n"
265
 
      "        }\n"
266
 
      "}]]>"
267
 
msgstr ""
268
 
 
269
 
#. Tag: title
270
 
#: persistent_classes.xml:173
271
 
#, no-c-format
272
 
msgid "Implementing <literal>equals()</literal> and <literal>hashCode()</literal>"
273
 
msgstr ""
274
 
 
275
 
#. Tag: para
276
 
#: persistent_classes.xml:175
277
 
#, no-c-format
278
 
msgid "You have to override the <literal>equals()</literal> and <literal>hashCode()</literal> methods if you:"
279
 
msgstr ""
280
 
 
281
 
#. Tag: para
282
 
#: persistent_classes.xml:181
283
 
#, no-c-format
284
 
msgid "intend to put instances of persistent classes in a <literal>Set</literal> (the recommended way to represent many-valued associations); <emphasis>and</emphasis>"
285
 
msgstr ""
286
 
 
287
 
#. Tag: para
288
 
#: persistent_classes.xml:188
289
 
#, no-c-format
290
 
msgid "intend to use reattachment of detached instances"
291
 
msgstr ""
292
 
 
293
 
#. Tag: para
294
 
#: persistent_classes.xml:194
295
 
#, no-c-format
296
 
msgid "Hibernate guarantees equivalence of persistent identity (database row) and Java identity only inside a particular session scope. When you mix instances retrieved in different sessions, you must implement <literal>equals()</literal> and <literal>hashCode()</literal> if you wish to have meaningful semantics for <literal>Set</literal>s."
297
 
msgstr ""
298
 
 
299
 
#. Tag: para
300
 
#: persistent_classes.xml:202
301
 
#, no-c-format
302
 
msgid "The most obvious way is to implement <literal>equals()</literal>/<literal>hashCode()</literal> by comparing the identifier value of both objects. If the value is the same, both must be the same database row, because they are equal. If both are added to a <literal>Set</literal>, you will only have one element in the <literal>Set</literal>). Unfortunately, you cannot use that approach with generated identifiers. Hibernate will only assign identifier values to objects that are persistent; a newly created instance will not have any identifier value. Furthermore, if an instance is unsaved and currently in a <literal>Set</literal>, saving it will assign an identifier value to the object. If <literal>equals()</literal> and <literal>hashCode()</literal> are based on the identifier value, the hash code would change, breaking the contract of the <literal>Set</literal>. See the Hibernate website for a full discussion of this problem. This is not a Hibernate issue, but normal Java semantics of object identity and equality."
303
 
msgstr ""
304
 
 
305
 
#. Tag: para
306
 
#: persistent_classes.xml:216
307
 
#, no-c-format
308
 
msgid "It is recommended that you implement <literal>equals()</literal> and <literal>hashCode()</literal> using <emphasis>Business key equality</emphasis>. Business key equality means that the <literal>equals()</literal> method compares only the properties that form the business key. It is a key that would identify our instance in the real world (a <emphasis>natural</emphasis> candidate key):"
309
 
msgstr ""
310
 
 
311
 
#. Tag: programlisting
312
 
#: persistent_classes.xml:224
313
 
#, no-c-format
314
 
msgid ""
315
 
      "<![CDATA[public class Cat {\n"
316
 
      "\n"
317
 
      "    ...\n"
318
 
      "    public boolean equals(Object other) {\n"
319
 
      "        if (this == other) return true;\n"
320
 
      "        if ( !(other instanceof Cat) ) return false;\n"
321
 
      "\n"
322
 
      "        final Cat cat = (Cat) other;\n"
323
 
      "\n"
324
 
      "        if ( !cat.getLitterId().equals( getLitterId() ) ) return false;\n"
325
 
      "        if ( !cat.getMother().equals( getMother() ) ) return false;\n"
326
 
      "\n"
327
 
      "        return true;\n"
328
 
      "    }\n"
329
 
      "\n"
330
 
      "    public int hashCode() {\n"
331
 
      "        int result;\n"
332
 
      "        result = getMother().hashCode();\n"
333
 
      "        result = 29 * result + getLitterId();\n"
334
 
      "        return result;\n"
335
 
      "    }\n"
336
 
      "\n"
337
 
      "}]]>"
338
 
msgstr ""
339
 
 
340
 
#. Tag: para
341
 
#: persistent_classes.xml:226
342
 
#, no-c-format
343
 
msgid "A business key does not have to be as solid as a database primary key candidate (see <xref linkend=\"transactions-basics-identity\"/>). Immutable or unique properties are usually good candidates for a business key."
344
 
msgstr ""
345
 
 
346
 
#. Tag: title
347
 
#: persistent_classes.xml:236
348
 
#, no-c-format
349
 
msgid "Dynamic models"
350
 
msgstr ""
351
 
 
352
 
#. Tag: title
353
 
#: persistent_classes.xml:239
354
 
#, no-c-format
355
 
msgid "Note"
356
 
msgstr ""
357
 
 
358
 
#. Tag: emphasis
359
 
#: persistent_classes.xml:241
360
 
#, no-c-format
361
 
msgid "The following features are currently considered experimental and may change in the near future."
362
 
msgstr ""
363
 
 
364
 
#. Tag: para
365
 
#: persistent_classes.xml:246
366
 
#, no-c-format
367
 
msgid "Persistent entities do not necessarily have to be represented as POJO classes or as JavaBean objects at runtime. Hibernate also supports dynamic models (using <literal>Map</literal>s of <literal>Map</literal>s at runtime) and the representation of entities as DOM4J trees. With this approach, you do not write persistent classes, only mapping files."
368
 
msgstr ""
369
 
 
370
 
#. Tag: para
371
 
#: persistent_classes.xml:254
372
 
#, no-c-format
373
 
msgid "By default, Hibernate works in normal POJO mode. You can set a default entity representation mode for a particular <literal>SessionFactory</literal> using the <literal>default_entity_mode</literal> configuration option (see <xref linkend=\"configuration-optional-properties\"/>)."
374
 
msgstr ""
375
 
 
376
 
#. Tag: para
377
 
#: persistent_classes.xml:261
378
 
#, no-c-format
379
 
msgid "The following examples demonstrate the representation using <literal>Map</literal>s. First, in the mapping file an <literal>entity-name</literal> has to be declared instead of, or in addition to, a class name:"
380
 
msgstr ""
381
 
 
382
 
#. Tag: programlisting
383
 
#: persistent_classes.xml:267
384
 
#, no-c-format
385
 
msgid ""
386
 
      "<![CDATA[<hibernate-mapping>\n"
387
 
      "\n"
388
 
      "    <class entity-name=\"Customer\">\n"
389
 
      "\n"
390
 
      "        <id name=\"id\"\n"
391
 
      "            type=\"long\"\n"
392
 
      "            column=\"ID\">\n"
393
 
      "            <generator class=\"sequence\"/>\n"
394
 
      "        </id>\n"
395
 
      "\n"
396
 
      "        <property name=\"name\"\n"
397
 
      "            column=\"NAME\"\n"
398
 
      "            type=\"string\"/>\n"
399
 
      "\n"
400
 
      "        <property name=\"address\"\n"
401
 
      "            column=\"ADDRESS\"\n"
402
 
      "            type=\"string\"/>\n"
403
 
      "\n"
404
 
      "        <many-to-one name=\"organization\"\n"
405
 
      "            column=\"ORGANIZATION_ID\"\n"
406
 
      "            class=\"Organization\"/>\n"
407
 
      "\n"
408
 
      "        <bag name=\"orders\"\n"
409
 
      "            inverse=\"true\"\n"
410
 
      "            lazy=\"false\"\n"
411
 
      "            cascade=\"all\">\n"
412
 
      "            <key column=\"CUSTOMER_ID\"/>\n"
413
 
      "            <one-to-many class=\"Order\"/>\n"
414
 
      "        </bag>\n"
415
 
      "\n"
416
 
      "    </class>\n"
417
 
      "    \n"
418
 
      "</hibernate-mapping>]]>"
419
 
msgstr ""
420
 
 
421
 
#. Tag: para
422
 
#: persistent_classes.xml:269
423
 
#, no-c-format
424
 
msgid "Even though associations are declared using target class names, the target type of associations can also be a dynamic entity instead of a POJO."
425
 
msgstr ""
426
 
 
427
 
#. Tag: para
428
 
#: persistent_classes.xml:276
429
 
#, no-c-format
430
 
msgid "After setting the default entity mode to <literal>dynamic-map</literal> for the <literal>SessionFactory</literal>, you can, at runtime, work with <literal>Map</literal>s of <literal>Map</literal>s:"
431
 
msgstr ""
432
 
 
433
 
#. Tag: programlisting
434
 
#: persistent_classes.xml:282
435
 
#, no-c-format
436
 
msgid ""
437
 
      "<![CDATA[Session s = openSession();\n"
438
 
      "Transaction tx = s.beginTransaction();\n"
439
 
      "Session s = openSession();\n"
440
 
      "\n"
441
 
      "// Create a customer\n"
442
 
      "Map david = new HashMap();\n"
443
 
      "david.put(\"name\", \"David\");\n"
444
 
      "\n"
445
 
      "// Create an organization\n"
446
 
      "Map foobar = new HashMap();\n"
447
 
      "foobar.put(\"name\", \"Foobar Inc.\");\n"
448
 
      "\n"
449
 
      "// Link both\n"
450
 
      "david.put(\"organization\", foobar);\n"
451
 
      "\n"
452
 
      "// Save both\n"
453
 
      "s.save(\"Customer\", david);\n"
454
 
      "s.save(\"Organization\", foobar);\n"
455
 
      "\n"
456
 
      "tx.commit();\n"
457
 
      "s.close();]]>"
458
 
msgstr ""
459
 
 
460
 
#. Tag: para
461
 
#: persistent_classes.xml:284
462
 
#, no-c-format
463
 
msgid "One of the main advantages of dynamic mapping is quick turnaround time for prototyping, without the need for entity class implementation. However, you lose compile-time type checking and will likely deal with many exceptions at runtime. As a result of the Hibernate mapping, the database schema can easily be normalized and sound, allowing to add a proper domain model implementation on top later on."
464
 
msgstr ""
465
 
 
466
 
#. Tag: para
467
 
#: persistent_classes.xml:292
468
 
#, no-c-format
469
 
msgid "Entity representation modes can also be set on a per <literal>Session</literal> basis:"
470
 
msgstr ""
471
 
 
472
 
#. Tag: programlisting
473
 
#: persistent_classes.xml:297
474
 
#, no-c-format
475
 
msgid ""
476
 
      "<![CDATA[Session dynamicSession = pojoSession.getSession(EntityMode.MAP);\n"
477
 
      "\n"
478
 
      "// Create a customer\n"
479
 
      "Map david = new HashMap();\n"
480
 
      "david.put(\"name\", \"David\");\n"
481
 
      "dynamicSession.save(\"Customer\", david);\n"
482
 
      "...\n"
483
 
      "dynamicSession.flush();\n"
484
 
      "dynamicSession.close()\n"
485
 
      "...\n"
486
 
      "// Continue on pojoSession\n"
487
 
      "]]>"
488
 
msgstr ""
489
 
 
490
 
#. Tag: para
491
 
#: persistent_classes.xml:300
492
 
#, no-c-format
493
 
msgid "Please note that the call to <literal>getSession()</literal> using an <literal>EntityMode</literal> is on the <literal>Session</literal> API, not the <literal>SessionFactory</literal>. That way, the new <literal>Session</literal> shares the underlying JDBC connection, transaction, and other context information. This means you do not have to call <literal>flush()</literal> and <literal>close()</literal> on the secondary <literal>Session</literal>, and also leave the transaction and connection handling to the primary unit of work."
494
 
msgstr ""
495
 
 
496
 
#. Tag: para
497
 
#: persistent_classes.xml:310
498
 
#, no-c-format
499
 
msgid "More information about the XML representation capabilities can be found in <xref linkend=\"xml\"/>."
500
 
msgstr ""
501
 
 
502
 
#. Tag: title
503
 
#: persistent_classes.xml:318
504
 
#, no-c-format
505
 
msgid "Tuplizers"
506
 
msgstr ""
507
 
 
508
 
#. Tag: para
509
 
#: persistent_classes.xml:320
510
 
#, no-c-format
511
 
msgid "<literal>org.hibernate.tuple.Tuplizer</literal>, and its sub-interfaces, are responsible for managing a particular representation of a piece of data given that representation's <literal>org.hibernate.EntityMode</literal>. If a given piece of data is thought of as a data structure, then a tuplizer is the thing that knows how to create such a data structure and how to extract values from and inject values into such a data structure. For example, for the POJO entity mode, the corresponding tuplizer knows how create the POJO through its constructor. It also knows how to access the POJO properties using the defined property accessors."
512
 
msgstr ""
513
 
 
514
 
#. Tag: para
515
 
#: persistent_classes.xml:330
516
 
#, no-c-format
517
 
msgid "There are two high-level types of Tuplizers, represented by the <literal>org.hibernate.tuple.entity.EntityTuplizer</literal> and <literal>org.hibernate.tuple.component.ComponentTuplizer</literal> interfaces. <literal>EntityTuplizer</literal>s are responsible for managing the above mentioned contracts in regards to entities, while <literal>ComponentTuplizer</literal>s do the same for components."
518
 
msgstr ""
519
 
 
520
 
#. Tag: para
521
 
#: persistent_classes.xml:338
522
 
#, no-c-format
523
 
msgid "Users can also plug in their own tuplizers. Perhaps you require that a <literal>java.util.Map</literal> implementation other than <literal>java.util.HashMap</literal> be used while in the dynamic-map entity-mode. Or perhaps you need to define a different proxy generation strategy than the one used by default. Both would be achieved by defining a custom tuplizer implementation. Tuplizer definitions are attached to the entity or component mapping they are meant to manage. Going back to the example of our customer entity:"
524
 
msgstr ""
525
 
 
526
 
#. Tag: programlisting
527
 
#: persistent_classes.xml:347
528
 
#, no-c-format
529
 
msgid ""
530
 
      "<![CDATA[<hibernate-mapping>\n"
531
 
      "    <class entity-name=\"Customer\">\n"
532
 
      "        <!--\n"
533
 
      "            Override the dynamic-map entity-mode\n"
534
 
      "            tuplizer for the customer entity\n"
535
 
      "        -->\n"
536
 
      "        <tuplizer entity-mode=\"dynamic-map\"\n"
537
 
      "                class=\"CustomMapTuplizerImpl\"/>\n"
538
 
      "\n"
539
 
      "        <id name=\"id\" type=\"long\" column=\"ID\">\n"
540
 
      "            <generator class=\"sequence\"/>\n"
541
 
      "        </id>\n"
542
 
      "\n"
543
 
      "        <!-- other properties -->\n"
544
 
      "        ...\n"
545
 
      "    </class>\n"
546
 
      "</hibernate-mapping>\n"
547
 
      "\n"
548
 
      "\n"
549
 
      "public class CustomMapTuplizerImpl\n"
550
 
      "        extends org.hibernate.tuple.entity.DynamicMapEntityTuplizer {\n"
551
 
      "    // override the buildInstantiator() method to plug in our custom map...\n"
552
 
      "    protected final Instantiator buildInstantiator(\n"
553
 
      "            org.hibernate.mapping.PersistentClass mappingInfo) {\n"
554
 
      "        return new CustomMapInstantiator( mappingInfo );\n"
555
 
      "    }\n"
556
 
      "\n"
557
 
      "    private static final class CustomMapInstantiator\n"
558
 
      "            extends org.hibernate.tuple.DynamicMapInstantitor {\n"
559
 
      "        // override the generateMap() method to return our custom map...\n"
560
 
      "            protected final Map generateMap() {\n"
561
 
      "                    return new CustomMap();\n"
562
 
      "            }\n"
563
 
      "    }\n"
564
 
      "}]]>"
565
 
msgstr ""
566
 
 
567
 
#. Tag: title
568
 
#: persistent_classes.xml:353
569
 
#, no-c-format
570
 
msgid "EntityNameResolvers"
571
 
msgstr ""
572
 
 
573
 
#. Tag: para
574
 
#: persistent_classes.xml:355
575
 
#, no-c-format
576
 
msgid "The <interfacename>org.hibernate.EntityNameResolver</interfacename> interface is a contract for resolving the entity name of a given entity instance. The interface defines a single method <methodname>resolveEntityName</methodname> which is passed the entity instance and is expected to return the appropriate entity name (null is allowed and would indicate that the resolver does not know how to resolve the entity name of the given entity instance). Generally speaking, an <interfacename>org.hibernate.EntityNameResolver</interfacename> is going to be most useful in the case of dynamic models. One example might be using proxied interfaces as your domain model. The hibernate test suite has an example of this exact style of usage under the <package>org.hibernate.test.dynamicentity.tuplizer2</package>. Here is some of the code from that package for illustration."
577
 
msgstr ""
578
 
 
579
 
#. Tag: programlisting
580
 
#: persistent_classes.xml:367
581
 
#, no-c-format
582
 
msgid ""
583
 
      "/**\n"
584
 
      " * A very trivial JDK Proxy InvocationHandler implementation where we proxy an interface as\n"
585
 
      " * the domain model and simply store persistent state in an internal Map.  This is an extremely\n"
586
 
      " * trivial example meant only for illustration.\n"
587
 
      " */\n"
588
 
      "public final class DataProxyHandler implements InvocationHandler {\n"
589
 
      "        private String entityName;\n"
590
 
      "        private HashMap data = new HashMap();\n"
591
 
      "\n"
592
 
      "        public DataProxyHandler(String entityName, Serializable id) {\n"
593
 
      "                this.entityName = entityName;\n"
594
 
      "                data.put( \"Id\", id );\n"
595
 
      "        }\n"
596
 
      "\n"
597
 
      "        public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {\n"
598
 
      "                String methodName = method.getName();\n"
599
 
      "                if ( methodName.startsWith( \"set\" ) ) {\n"
600
 
      "                        String propertyName = methodName.substring( 3 );\n"
601
 
      "                        data.put( propertyName, args[0] );\n"
602
 
      "                }\n"
603
 
      "                else if ( methodName.startsWith( \"get\" ) ) {\n"
604
 
      "                        String propertyName = methodName.substring( 3 );\n"
605
 
      "                        return data.get( propertyName );\n"
606
 
      "                }\n"
607
 
      "                else if ( \"toString\".equals( methodName ) ) {\n"
608
 
      "                        return entityName + \"#\" + data.get( \"Id\" );\n"
609
 
      "                }\n"
610
 
      "                else if ( \"hashCode\".equals( methodName ) ) {\n"
611
 
      "                        return new Integer( this.hashCode() );\n"
612
 
      "                }\n"
613
 
      "                return null;\n"
614
 
      "        }\n"
615
 
      "\n"
616
 
      "        public String getEntityName() {\n"
617
 
      "                return entityName;\n"
618
 
      "        }\n"
619
 
      "\n"
620
 
      "        public HashMap getData() {\n"
621
 
      "                return data;\n"
622
 
      "        }\n"
623
 
      "}\n"
624
 
      "\n"
625
 
      "/**\n"
626
 
      " *\n"
627
 
      " */\n"
628
 
      "public class ProxyHelper {\n"
629
 
      "    public static String extractEntityName(Object object) {\n"
630
 
      "        // Our custom java.lang.reflect.Proxy instances actually bundle\n"
631
 
      "        // their appropriate entity name, so we simply extract it from there\n"
632
 
      "        // if this represents one of our proxies; otherwise, we return null\n"
633
 
      "        if ( Proxy.isProxyClass( object.getClass() ) ) {\n"
634
 
      "            InvocationHandler handler = Proxy.getInvocationHandler( object );\n"
635
 
      "            if ( DataProxyHandler.class.isAssignableFrom( handler.getClass() ) ) {\n"
636
 
      "                DataProxyHandler myHandler = ( DataProxyHandler ) handler;\n"
637
 
      "                return myHandler.getEntityName();\n"
638
 
      "            }\n"
639
 
      "        }\n"
640
 
      "        return null;\n"
641
 
      "    }\n"
642
 
      "\n"
643
 
      "    // various other utility methods ....\n"
644
 
      "\n"
645
 
      "}\n"
646
 
      "\n"
647
 
      "/**\n"
648
 
      " * The EntityNameResolver implementation.\n"
649
 
      " * IMPL NOTE : An EntityNameResolver really defines a strategy for how entity names should be\n"
650
 
      " * resolved.  Since this particular impl can handle resolution for all of our entities we want to\n"
651
 
      " * take advantage of the fact that SessionFactoryImpl keeps these in a Set so that we only ever\n"
652
 
      " * have one instance registered.  Why?  Well, when it comes time to resolve an entity name,\n"
653
 
      " * Hibernate must iterate over all the registered resolvers.  So keeping that number down\n"
654
 
      " * helps that process be as speedy as possible.  Hence the equals and hashCode impls\n"
655
 
      " */\n"
656
 
      "public class MyEntityNameResolver implements EntityNameResolver {\n"
657
 
      "    public static final MyEntityNameResolver INSTANCE = new MyEntityNameResolver();\n"
658
 
      "\n"
659
 
      "    public String resolveEntityName(Object entity) {\n"
660
 
      "        return ProxyHelper.extractEntityName( entity );\n"
661
 
      "    }\n"
662
 
      "\n"
663
 
      "    public boolean equals(Object obj) {\n"
664
 
      "        return getClass().equals( obj.getClass() );\n"
665
 
      "    }\n"
666
 
      "\n"
667
 
      "    public int hashCode() {\n"
668
 
      "        return getClass().hashCode();\n"
669
 
      "    }\n"
670
 
      "}\n"
671
 
      "\n"
672
 
      "public class MyEntityTuplizer extends PojoEntityTuplizer {\n"
673
 
      "        public MyEntityTuplizer(EntityMetamodel entityMetamodel, PersistentClass mappedEntity) {\n"
674
 
      "                super( entityMetamodel, mappedEntity );\n"
675
 
      "        }\n"
676
 
      "\n"
677
 
      "        public EntityNameResolver[] getEntityNameResolvers() {\n"
678
 
      "                return new EntityNameResolver[] { MyEntityNameResolver.INSTANCE };\n"
679
 
      "        }\n"
680
 
      "\n"
681
 
      "    public String determineConcreteSubclassEntityName(Object entityInstance, SessionFactoryImplementor factory) {\n"
682
 
      "        String entityName = ProxyHelper.extractEntityName( entityInstance );\n"
683
 
      "        if ( entityName == null ) {\n"
684
 
      "            entityName = super.determineConcreteSubclassEntityName( entityInstance, factory );\n"
685
 
      "        }\n"
686
 
      "        return entityName;\n"
687
 
      "    }\n"
688
 
      "\n"
689
 
      "    ...\n"
690
 
      "}"
691
 
msgstr ""
692
 
 
693
 
#. Tag: para
694
 
#: persistent_classes.xml:369
695
 
#, no-c-format
696
 
msgid "In order to register an <interfacename>org.hibernate.EntityNameResolver</interfacename> users must either:"
697
 
msgstr ""
698
 
 
699
 
#. Tag: para
700
 
#: persistent_classes.xml:373
701
 
#, no-c-format
702
 
msgid "Implement a custom <link linkend=\"persistent-classes-tuplizers\">Tuplizer</link>, implementing the <methodname>getEntityNameResolvers</methodname> method."
703
 
msgstr ""
704
 
 
705
 
#. Tag: para
706
 
#: persistent_classes.xml:379
707
 
#, no-c-format
708
 
msgid "Register it with the <classname>org.hibernate.impl.SessionFactoryImpl</classname> (which is the implementation class for <interfacename>org.hibernate.SessionFactory</interfacename>) using the <methodname>registerEntityNameResolver</methodname> method."
709
 
msgstr ""
710