exedio.github.io/transactions.html at master · exedio/exedio.github.io · GitHub

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
<!DOCTYPE html>
<html lang="en">
	<head>
		<meta http-equiv="content-type" content="text/html; charset=utf-8">
		<title>exedio persistence - Transactions Trail</title>
		<meta name="keywords" content="Persistence, Java">
		<meta name="description" content="persistence framework for java">
		<link rel="stylesheet" href="cope.css">
	</head>
	<body>
<!-- HEADER -->
<div id="header_wrap" class="outer">
	<header class="inner">
		<a id="forkme_banner" href="https://github.com/exedio">View on GitHub</a>
		<h1 id="project_title">exedio persistence</h1>
		<h2 id="project_tagline">Persistence Framework for Java.</h2>
		<a id="toplink" href="index.html">Go to top</a>
	</header>
</div>
<!-- MAIN CONTENT -->
<div id="main_content_wrap" class="outer">
	<section id="main_content" class="inner">

		<h2>Transactions Trail</h2>
		<p>
			This trail assumes,
			that you are already familar with the general meaning of
			<a href="https://en.wikipedia.org/wiki/Database_transaction">transactions</a>.
			It shows you, how to start, commit and rollback transactions.
		</p>
		<h3>When to use transactions</h3>
		<p>
			The short anser is <i>always</i>.
			Whenever you want to read, write or search persistent data,
			this must happen within the boundaries of a transaction.
			These boundaries are marked by calls to the methods
			<code>Model.startTransaction()</code> and <code>Model.commit()</code>
			or <code>Model.rollback()</code>.
		</p>
		<p>
			Any attempt to access persistent data outside a transaction
			will cause an exception.
			There is no equivalent to what is known as <i>auto-commit</i>
			in relational databases.
		</p>
		<h3>Example</h3>
		<p>
			Since you also have to take care of exceptions,
			the standard way of using transactions looks like this:
		</p>
<pre>
boolean failure = true;
try
{
   Main.model.<a href="api/com/exedio/cope/Model.html#startTransaction()">startTransaction</a>();
   // put the body of the transaction here
   Main.model.<a href="api/com/exedio/cope/Model.html#commit()">commit</a>();
   failure = false;
}
finally
{
   if(failure)
      Main.model.<a href="api/com/exedio/cope/Model.html#rollback()">rollback</a>();
}
</pre>
		<p>
			For your convenience, the framework provides a method
			<code>Model.rollbackIfNotCommitted()</code>
			which does a <i>rollback</i> if and only if the transaction
			has not been closed (committed or rolled back) before.
			Therefore you can make the code a little bit shorter:
		</p>
<pre>
try
{
   Main.model.<a href="api/com/exedio/cope/Model.html#startTransaction()">startTransaction</a>();
   // put the body of the transaction here
   Main.model.<a href="api/com/exedio/cope/Model.html#commit()">commit</a>();
}
finally
{
   Main.model.<a href="api/com/exedio/cope/Model.html#rollbackIfNotCommitted()">rollbackIfNotCommitted</a>();
}
</pre>
		<p>
			For even more convenience you may use the try-with-resources syntax
			introduced in Java 1.7:
		</p>
<pre>
try(<a href="api/com/exedio/cope/TransactionTry.html">TransactionTry</a> tx = Main.model.<a href="api/com/exedio/cope/Model.html#startTransactionTry(java.lang.String)">startTransactionTry</a>("web"))
{
   // put the body of the transaction here
   tx.<a href="api/com/exedio/cope/TransactionTry.html#commit()">commit</a>();
}
</pre>
		<h3>Further Reading</h3>
		<p>
			There is not much more to say about transactions,
			so you may want to proceed to any of the following trails:
		</p>
		<ul>
			<li>
				<a href="searching.html">Searching Trail</a>
				gives you an introduction into the searching capabilities of exedio persistence.
			</li>
			<li>
				<a href="fields2.html">Field Reloaded Trail</a>
				covers all the more specific possibilities to store data with exedio persistence.
			</li>
			<li>
				<a href="webapplications.html">Web Application Trail</a>
				shows you the little differences when using the framework within a web container.
				This includes a helper class for managing transactions as well.
			</li>
		</ul>
	</section>
</div>

<!-- FOOTER  -->
<div id="footer_wrap" class="outer">
	<footer class="inner">
		<p>
			Maintained by
			<a href="https://www.exedio.com/" target="_top">exedio</a>
			Gesellschaft f&uuml;r Softwareentwicklung mbH.
		</p>
		<a href="https://validator.w3.org/check?uri=referer" class="validhtml">Valid HTML5</a>
		<p>
			Slate theme by <a href="https://github.com/jasoncostello">Jason Costello</a>.
			Published with <a href="https://pages.github.com">GitHub Pages</a>.
		</p>
	</footer>
</div>
	</body>
</html>