Skip to main content
summaryrefslogtreecommitdiffstats
blob: 6f9af1c00c15f16afd75981df7dd01e3ae72f70e (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
<meta name="Forrest-version" content="0.7">
<meta name="Forrest-skin-name" content="elver4">
<style type="text/css">
          /*  */
          @import "../skin/tigris.css";
          @import "../skin/quirks.css";
          @import "../skin/inst.css";
         /*   */
        </style>
<link media="print" href="../skin/print.css" type="text/css" rel="stylesheet">
<link href="../skin/forrest.css" type="text/css" rel="stylesheet">
<link rel="shortcut icon" href="../">
<script type="text/javascript" src="../skin/tigris.js"></script><script src="../skin/menu.js" language="javascript" type="text/javascript"></script>
<title>Hibernate EMF Resources</title>
<meta content="text/css" http-equiv="Content-style-type">
</head>
<body class="composite" onload="focus()">
<div id="banner">
<table width="100%" cellpadding="8" cellspacing="0" border="0">
<tr>
<td align="left">
<div>
<a href="http://www.elver.org"><img class="logoImage" alt="Elver Store" src="../images/ELV2.gif"></a>
</div>
<span class="alt">Elver Store</span></td><td align="center">
<div>
<a href="http://www.elver.org/"><img class="logoImage" alt="Elver" src="../images/empty.gif"></a>
</div>
</td><td valign="top" align="right">
<div class="right" align="right" id="login">
<form target="_blank" action="http://www.google.com/search" method="get">
<select name="as_sitesearch"><option value="">Search...</option><option value="www.elver.org">The elver site</option><option value="">The web</option></select> for
		      <input size="15" name="as_q" id="query" type="text"><input name="Search" value="Go" type="submit">
</form>
</div>
</td>
</tr>
</table>
</div>
<div id="toptabs" class="tabs">
<table border="0" cellspacing="0" cellpadding="4">
<tr>
<td><a class="base-selected" href="../index.html">Home</a></td><th><a class="base-selected" href="../hibernate/index.html">EMF Hibernate</a></th><td><a class="base-selected" href="../jpox/index.html">EMF JDO/JPOX</a></td><td><a class="base-selected" href="../services/index.html">Services</a></td>
</tr>
</table>
</div>
<table width="100%" border="0" cellpadding="0" cellspacing="0" id="breadcrumbs">
<tr>
<td></td><td>
<div class="published" align="right">
<script type="text/javascript" language="JavaScript"><!--
                 document.write("Published: " + document.lastModified);
                 //  --></script>
</div>
</td>
</tr>
</table>
<table id="main" width="100%" cellpadding="4" cellspacing="0" border="0">
<tr valign="top">
<td style="padding: 0px" width="20%" id="leftcol">
<table width="100%" class="menuarea" cellspacing="0" cellpadding="0">
<tr>
<td width="6px" valign="top">
<table border="0" cellpadding="0" cellspacing="0" class="leftpagemargin">
<tr>
<td class="subborder trail">&nbsp;</td>
</tr>
</table>
</td><td class="dialog">
<div class="menu">
<div onclick="SwitchMenu('menu_1.1')" id="menu_1.1Title" class="menutitle">Home</div>
<div id="menu_1.1" class="menuitemgroup">
<div class="menuitem">
<a href="../hibernate/index.html">Introduction</a>
</div>
<div class="menuitem">
<a href="../hibernate/status.html">Status</a>
</div>
<div class="menuitem">
<a href="../hibernate/features.html">Features</a>
</div>
<div class="menuitem">
<a href="../hibernate/overview.html">Overview</a>
</div>
<div class="menuitem">
<a href="../hibernate/changelog.html">Changelog</a>
</div>
<div class="menuitem">
<a href="../hibernate/installation.html">Download &amp; Install</a>
</div>
<div class="menuitem">
<a href="../hibernate/knownissues.html">Known Issues</a>
</div>
<div class="menuitem">
<a href="../hibernate/quick_tutorial.html">Quick Start</a>
</div>
<div class="menuitem">
<a href="../hibernate/license.html">License</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.2')" id="menu_1.2Title" class="menutitle">Library Tutorial</div>
<div id="menu_1.2" class="menuitemgroup">
<div class="menuitem">
<a href="../hibernate/tutorialone/tutorial1_intro.html">Introduction</a>
</div>
<div class="menuitem">
<a href="../hibernate/tutorialone/tutorial1_1.html">Setup Environment</a>
</div>
<div class="menuitem">
<a href="../hibernate/tutorialone/tutorial1_2.html">Create and Store EMF Object</a>
</div>
<div class="menuitem">
<a href="../hibernate/tutorialone/tutorial1_3.html">Retrieve EMF Objects</a>
</div>
<div class="menuitem">
<a href="../hibernate/tutorialone/tutorial1_4.html">Query EMF Objects</a>
</div>
<div class="menuitem">
<a href="../hibernate/tutorialone/tutorial1_5.html">Using EMF/JPOX Resources</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.3')" id="menu_1.3Title" class="menutitle">Library Editor Tutorial</div>
<div id="menu_1.3" class="menuitemgroup">
<div class="menuitem">
<a href="../hibernate/tutorialtwo/tutorial2_intro.html">Introduction</a>
</div>
<div class="menuitem">
<a href="../hibernate/tutorialtwo/tutorial2_1.html">Initialize the Library Editor</a>
</div>
<div class="menuitem">
<a href="../hibernate/tutorialtwo/tutorial2_2.html">Run the Library Editor</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.4')" id="menu_1.4Title" class="menutitle">GMF Editor Tutorial</div>
<div id="menu_1.4" class="menuitemgroup">
<div class="menuitem">
<a href="../hibernate/gmftutorial/tutorial1.html">Introduction</a>
</div>
<div class="menuitem">
<a href="../hibernate/gmftutorial/tutorial2.html">Environment Setup</a>
</div>
<div class="menuitem">
<a href="../hibernate/gmftutorial/tutorial3.html">Running the editor</a>
</div>
</div>
<div onclick="SwitchMenu('menu_selected_1.5')" id="menu_selected_1.5Title" class="menutitle">Details</div>
<div id="menu_selected_1.5" class="selectedmenuitemgroup">
<div class="menuitem">
<a href="../hibernate/dynamic.html">Dynamic EMF Tutorial</a>
</div>
<div class="menuitem">
<a href="../hibernate/inheritance.html">Inheritance Mapping</a>
</div>
<div class="menuitem">
<a href="../hibernate/hibernate_relations.html">Modeling Associations</a>
</div>
<div class="menuitem">
<a href="../hibernate/hbdatastore.html">HbDataStore</a>
</div>
<div class="menuitem">
<a href="../hibernate/options.html">Options</a>
</div>
<div class="menuitem">
<a href="../hibernate/hibernate_details.html">EMF - Hibernate Details</a>
</div>
<div class="menupage">
<div class="menupagetitle">EMF Hibernate Resources</div>
</div>
<div class="menuitem">
<a href="../hibernate/resource_utility.html">Resource Utility</a>
</div>
<div class="menuitem">
<a href="../hibernate/troubleshooting.html">Troubleshooting</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.6')" id="menu_1.6Title" class="menutitle">Annotations (JPA/EJB3)</div>
<div id="menu_1.6" class="menuitemgroup">
<div class="menuitem">
<a href="../hibernate/ejb3_format.html">Format</a>
</div>
<div class="menuitem">
<a href="../hibernate/ejb3_examples.html">Examples</a>
</div>
<div class="menuitem">
<a href="../hibernate/ejb3_features.html">JPA/EJB3</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.7')" id="menu_1.7Title" class="menutitle">XML Schema</div>
<div id="menu_1.7" class="menuitemgroup">
<div class="menuitem">
<a href="../hibernate/features_details.html">XML Schema Support</a>
</div>
<div class="menuitem">
<a href="../hibernate/schema_list.html">XML Schema Examples</a>
</div>
<div class="menuitem">
<a href="../hibernate/featuremap.html">Feature Map/Mixed Content</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.8')" id="menu_1.8Title" class="menutitle">Support</div>
<div id="menu_1.8" class="menuitemgroup">
<div class="menuitem">
<a href="../hibernate/upgrading.html">Upgrading</a>
</div>
<div class="menuitem">
<a href="../hibernate/mailinglist.html">Newsgroup</a>
</div>
<div class="menuitem">
<a href="../hibernate/emfhibsupport.html">EMF/Hibernate Support</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.9')" id="menu_1.9Title" class="menutitle">Developer</div>
<div id="menu_1.9" class="menuitemgroup">
<div class="menuitem">
<a href="../hibernate/svn.html">CVS</a>
</div>
</div>
</div>
</td>
</tr>
<tr>
<td></td><td>
<table width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
<td class="border bottom-left"></td><td class="border bottomborder"></td><td class="border bottom-right"></td>
</tr>
</table>
</td>
</tr>
<tr>
<td colspan="2" height="10"></td>
</tr>
</table>
<table></table>
<table></table>
<div class="strut">&nbsp;</div>
</td><td>
<div class="content">
<div id="bodycol">
<div id="apphead">
<h2>
<em>Hibernate EMF Resources</em>
</h2>
</div>
<div class="abstract">The EMF Hibernate integration also contains a Resource implementation for
		integration with the EMF Editing Domain. The resource implementation
		extends the org.eclipse.emf.ecore.xmi.impl.XMIResourceImpl to enable easy importing 
		and exporting of XML to/from the relational store.
    </div>
<div class="app" id="projecthome">
<ul class="minitoc">
<li>
<a href="#Resource+URI">Resource URI</a>
</li>
<li>
<a href="#Hibernate+Resource+and+session%2Ftransaction+specifics">Hibernate Resource and session/transaction specifics</a>
</li>
<li>
<a href="#Validation">Validation</a>
</li>
<li>
<a href="#Standard+load+behavior%3A+Top+level+types">Standard load behavior: Top level types</a>
</li>
<li>
<a href="#Customizing+load+behavior">Customizing load behavior</a>
<ul class="minitoc">
<li>
<a href="#Extend+the+resource+implementation+in+java">Extend the resource implementation in java</a>
</li>
<li>
<a href="#Set+specific+queries+to+load+the+resource">Set specific queries to load the resource</a>
</li>
</ul>
</li>
<li>
<a href="#Load+of+referenced+Objects">Load of referenced Objects</a>
</li>
<li>
<a href="#Sharing+one+Session+between+Resources%2C+One+transaction+when+saving+multiple+resources">Sharing one Session between Resources, One transaction when saving multiple resources</a>
</li>
<li>
<a href="#Closing+a+resource">Closing a resource</a>
</li>
<li>
<a href="#Other+aspects">Other aspects</a>
<ul class="minitoc">
<li>
<a href="#Resource+use+after+Hibernate+exception">Resource use after Hibernate exception</a>
</li>
<li>
<a href="#Closing+a+resource-N100D2">Closing a resource</a>
</li>
</ul>
</li>
</ul>
	 
<p></p>
    
<a name="N10015"></a><a name="Resource+URI"></a>
<div class="h3">
<h3>Resource URI</h3>
      
      
<p>The Hibernate EMFResource is registered using different extensions/protocols:</p>
	  
<ul>
	  
<li>Protocol: the Hibernate EMF Resource (factory) will be registered for the protocols hibernate and ehb</li>
	  
<li>Extension: the Hibernate EMF Resource (factory) will be registered for the extensions hibernate and ehb</li>
	  
</ul>
	  
<p>When the hibernate protocol is used to retrieve a Resource then the resource 
		  needs to know how to reach a data store.  This is done by passing the registration name
	  of a HbDataStore to the resource with the org.eclipse.emf.teneo.Resource.DS_NAME_PARAM parameter. 
	  </p>
	  
<p>An example of a URI which returns a Hibernate resource: <em>hibernate://dsname=library</em>.</p>
	
</div>
    
<a name="N10031"></a><a name="Hibernate+Resource+and+session%2Ftransaction+specifics"></a>
<div class="h3">
<h3>Hibernate Resource and session/transaction specifics</h3>
      
      
<p>The Hibernate Resource opens a session when it is loaded for the first time.
		 A transaction is started when the load starts and committed at the end of the load.
		  This session is disconnected at the end of the load action.</p>
		
<p>The save action will reconnect the session, begin a transaction, do an update of
		  the datastore and then commit and disconnect.</p>
		 
<p>In one of the next releases a new resource implementation will be added which will create a new session
		 for each load and save action.</p>
	
</div>
    
<a name="N10041"></a><a name="Validation"></a>
<div class="h3">
<h3>Validation</h3>
      
      
<p>To enable validation on a Hibernate Resource you need to call setTrackingModification(true) on the resource.
      The Hibernate Resource then validates its content (the EObjects) when the
		  resource is saved. This validation makes use of the org.eclipse.emf.teneo.resource.NonLoadingDiagnostician.
		  This is a subclass of the standard EMF Diagnostician which does not load unloaded lazy lists. Only lists with 
		  minOccurs&gt;0 are loaded during validation. Validation fails when a ERROR level Diagnostic is
		  encountered. In this case the resource save method will throw a org.eclipse.emf.teneo.StoreValidationException. 
		  This exception has a method to retrieve all Diagnostics.</p>
	
</div>
		
<a name="N1004B"></a><a name="Standard+load+behavior%3A+Top+level+types"></a>
<div class="h3">
<h3>Standard load behavior: Top level types</h3>
	  		
      
<p>When a Hibernate EMF resource is loaded then only the so called top-level types are directly present in 
		  the resource contents. Top-level types are types which are not used as the 
		  the child in a containment relation. The assumption is that all contained types can be reached
	  from a top-level type.</p>
	  
<p>See also the <a href="knownissues.html">Known Issues</a>.</p>
	  
</div>
	 
<a name="N1005C"></a><a name="Customizing+load+behavior"></a>
<div class="h3">
<h3>Customizing load behavior</h3>
	 
<p>It is possible to customize what the resource actually loads from the database.</p>
		 
<a name="N10064"></a><a name="Extend+the+resource+implementation+in+java"></a>
<div class="h4">
<h4>Extend the resource implementation in java</h4>
<p>It is possible to customize the load behavior by overriding the loadFromStore method
				in the HibernateResource. This method gets a PersistenceManager and should return a list of 
				objects read from the Hibernate datastore.
			</p>
</div>
		 
<a name="N1006D"></a><a name="Set+specific+queries+to+load+the+resource"></a>
<div class="h4">
<h4>Set specific queries to load the resource</h4>
<p>There are two ways to pass specific queries to the HibernateResource. The first method
				is using uri parameters:</p>
<p>
<em>hibernate://?dsname=mystore&amp;query1=FROM Writer</em>
</p>
<p>You can pass multiple queries by using parameter names which start with query, for
			 example query1, query2 etc.</p>
<p>The other way to pass queries to the resource are to specify them in the 
			 .ehb file (see resource utility <a href="resource_utility.html">here</a>). An
			 example (commented out) of this can be found in the ehb file <a href="samples/library.ehb">here</a>.</p>
</div>
	 
</div>
	 
<a name="N10089"></a><a name="Load+of+referenced+Objects"></a>
<div class="h3">
<h3>Load of referenced Objects</h3>
	 
<p>Objects can be loaded explicitly (by using queries) or they are loaded implicitly when a 'lazy' collection is loaded or
	 there are references from explicitly loaded objects. The resource implementation can handle implicit loading of additional objects in different ways.
	 The implicit load strategy is controlled by setting the StoreResource.LOAD_STRATEGY_PARAM parameter. This parameter can be passed as an option to 
	 the load method or as a parameter in the uri. It can have two values:
	 </p>
	 
<ul>
	 
<li>StoreResource.SET_ERESOURCE (default): in this mode only the explicitly loaded objects are present in the contents of the resource
	 (i.e. in the top of the resource content). Objects may be present as contained children of explicitly loaded objects. Eventhough the 
	 referenced objects are not directly present in the contents the eResource of the referenced objects is set to 
	 the loading resource. This is only done if objects are not already present in another resource.</li>
	 
<li>StoreResource.ADD_TO_CONTENTS: this value means that any referenced objects and the container of a 
	 loaded object (if resolveProxies==false for the containment relation) are added to the contents of the resource.
	 This means that these objects are present in the top of the resource. If resolveProxies==true then the container of a
	 loaded object is not loaded in the resource as the container may be in a different resource. Implicitly loaded objects are only added to the 
	 loading resource if they are not already present in another resource.</li>
	 
</ul>
	 
<p>Implicit loading is mainly of importance when loading a resource using queries. In the default load method all top-entities are loaded anyway and then 
	 all objects are reachable through a loaded container.</p>
	 
</div>
    
<a name="N1009E"></a><a name="Sharing+one+Session+between+Resources%2C+One+transaction+when+saving+multiple+resources"></a>
<div class="h3">
<h3>Sharing one Session between Resources, One transaction when saving multiple resources</h3>
      
		
<p>As a standard behavior the resource will create its own session at load time.
		However, there are cases when you want to use one session to load and save multiple resources. This 
		is for example the case when there are references between objects in different resources. 
		In this case the load and save actions of multiple resources should use the same session and be done
		in the same transaction.</p>
		
<p>To support this Teneo has the concept of a SessionController. A SessionController manages one session
		for multiple resources. A SessionController is registered using a specific name. When a resource is opened this
		name is passed as an uri parameter. Using this name the HibernateResource can then find the SessionController
		and retrieve a session. When a HibernateResource has a SessionController then the HibernateResource does not itself 
		create a session or begin and commit transactions. Beginning and committing transactions is the responsibility
		of the application itself.</p>
		
<p>Here is some example code illustrating the use of a SessionController:</p>
		
<pre class="code">
	SessionController sc = new SessionController();

	// when creating a SessionController you have to pass your HbDataStore instance
	sc.setHbDataStore(hbDataStore);

	// register the SessionController, the name is used in the uri of the resource
	SessionController.registerSessionController("testsc", sc);

	// create an uri using the SessionController name
	URI uri1 = URI.createURI("hibernate://?" + HibernateResource.SESSION_CONTROLLER_PARAM + "=testsc&amp;query1=from Book");
	URI uri2 = URI.createURI("hibernate://?" + HibernateResource.SESSION_CONTROLLER_PARAM + "=testsc&amp;query1=from Writer");
	// resourceSet has to be set before somehow..
	final Resource res1 = resourceSet.createResource(uri1);
	final Resource res2 = resourceSet.createResource(uri2);
	
	// now load the resources 
	sc.getSession().beginTransaction();
	res1.load(Collections.EMPTY_MAP);
	res2.load(Collections.EMPTY_MAP);
	sc.getSession().getTransaction().commit();
	
	// do something usefull with your loaded resources...

	// and save them
	sc.getSession().beginTransaction();
	res1.save(Collections.EMPTY_MAP);
	res2.save(Collections.EMPTY_MAP);
	sc.getSession().getTransaction().commit();
		</pre>
		
<p>
<strong>Loading different EObjects (refering to eachother) in different resources can have side-effects if
		there are containment relations to and from these EObjects (with resolving=false). 
		If the containment relation is non-resolving then
		EMF will place an EObject always in the same resource as its container. If you use queries to load your resources
		then the containers are loaded also. For example: assume EObjects A1 and A2 both have container A0. If one resource
		loads A1 then A0 is also loaded automatically and A0 and A1 are in the same resource. If then a second resource loads
		A2 then A2 will be placed in the first resource because its container is located there. Overall this results in 
		unpredictable behavior. So: to correctly work with multiple resources the containment relations should be set to
		resolving = true, in addition the genmodel property Containment Proxy needs to be set to true.</strong>
</p>
		
</div>
		
<a name="N100B6"></a><a name="Closing+a+resource"></a>
<div class="h3">
<h3>Closing a resource</h3>
	  		
      
<p>The Hibernate EMF resource can be closed by calling the unload method. 
		  This method will close the disconnected session. In case a SessionController is used
		  the unload method will just nullify the internal session member, you should close
		  the session explicitly.</p>
	
</div>
    
<a name="N100C0"></a><a name="Other+aspects"></a>
<div class="h3">
<h3>Other aspects</h3>
      
		
<a name="N100C6"></a><a name="Resource+use+after+Hibernate+exception"></a>
<div class="h4">
<h4>Resource use after Hibernate exception</h4>
<p>When a Hibernate error/exception occurs when working with a Hibernate resource it can not
		be used anymore and should be unloaded (closed).</p>
<p>In a future resource implementation this issue will be solved.</p>
</div>
		
<a name="N100D2"></a><a name="Closing+a+resource-N100D2"></a>
<div class="h4">
<h4>Closing a resource</h4>
<p>The Hibernate EMF resource can be closed by calling the unload method. 
		  This method will close the disconnected session.</p>
</div>
	
</div>
  
</div>
</div>
</div>
</td>
</tr>
</table>
<div width="100%" id="footer">
<table width="100%" cellpadding="4" cellspacing="0" border="0">
<tr>
<td class="footer"><a href="license.html">
          Copyright &copy; 2006 The Elver Project</a>
      - All rights reserved.
      </td>
</tr>
</table>
</div>
</body>
</html>

Back to the top