Revision: 1244
Author: dhanji
Date: Thu Sep 16 14:37:57 2010
Log: Created wiki page through web user interface.
http://code.google.com/p/google-guice/source/detail?r=1244
Added:
/wiki/Transactions.wiki
=======================================
--- /dev/null
+++ /wiki/Transactions.wiki Thu Sep 16 14:37:57 2010
@@ -0,0 +1,63 @@
+#summary Transactions with Guice Persist
+
+== Method-level @Transactional ==
+
+By default, any method marked with `...@transactional` will have a
transaction started before, and committed after it is called.
+
+{{{
+ @Transactional
+ public void myMethod() { ... }
+}}}
+
+The only restriction is that these methods must be on objects that were
created by Guice and they must not be `private`.
+
+== Responding to exceptions ==
+
+If a transactional method encounters an unchecked exception (any kind of
`RuntimeException`), the transaction will be rolled back. Checked
exceptions are ignored and the transaction will be committed anyway.
+
+To change this behavior, you can specify your own exceptions (checked or
unchecked) on a per-method basis:
+
+{{{
+ @Transactional(rollbackOn = IOException.class)
+ public void myMethod() throws IOException { ... }
+}}}
+
+Once you specify a `rollbackOn` clause, only the given exceptions and
their subclasses will be considered for rollback. Everything else will be
committed. Note that you can specify any combination of exceptions using
array literal syntax:
+
+{{{
+ @Transactional(rollbackOn = { IOException.class,
RuntimeException.class, ... })
+}}}
+
+It is sometimes necessary to have some general exception types you want to
rollback but particular subtypes that are still allowed. This is also
possible using the `ignore` clause:
+
+{{{
+ @Transactional(rollbackOn = IOException.class, ignore =
FileNotFoundException.class)
+}}}
+
+In the above case, any `IOException` (and any of its subtypes) except
FileNotFoundException will trigger a rollback. In the case of
`FileNotFoundException`, a commit will be performed and the exception
propagated to the caller anyway.
+
+_Note that you can specify any combination of checked or unchecked
exceptions._
+
+== Units of Work ==
+
+A unit of work is roughly the lifespan of an `EntityManager` (in JPA). It
is the _session_ referred to in the `session-per-*` strategies. We have so
far seen how to create a unit of work that spans a single transaction, and
one that spans an entire HTTP request.
+
+Sometimes you need to define a custom unit-of-work that doesn't fit into
either requests or transactions. For example, you may want to do some
background work in a timer thread, or some initialization work during
startup. Or perhaps you are making a desktop app and have some other idea
of a unit of work.
+
+To start and end a unit of work arbitrarily, inject the `UnitOfWork`
interface:
+
+public class MyBackgroundWorker {
+ @Inject private UnitOfWork unitOfWork;
+
+ public void doSomeWork() {
+ unitOfWork.begin();
+ try {
+ // Do transactions, queries, etc...
+ //...
+ } finally {
+ unitOfWork.end();
+ }
+ }
+}
+
+You are free to call any `...@transactional` methods while a unit of work is
in progress this way. When `end()` is called, any existing session is
closed and discarded. It is safe to call `begin()` multiple times--if a
unit of work is in progress, nothing happens. Similarly, if one is ended
calling `end()` returns silently. `UnitOfWork` is threadsafe and can be
cached for multiple uses or injected directly into singletons.
--
You received this message because you are subscribed to the Google Groups
"google-guice-dev" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/google-guice-dev?hl=en.
