modules/ROOT/pages/modules/tx-control/advancedScopes.adoc

Title: Notice:    Licensed to the Apache Software Foundation (ASF) under one            or more contributor license agreements.
See the NOTICE file            distributed with this work for additional information            regarding copyright ownership.
The ASF licenses this file            to you under the Apache License, Version 2.0 (the            "License");
you may not use this file except in compliance            with the License.
You may obtain a copy of the License at            .              http://www.apache.org/licenses/LICENSE-2.0            .            Unless required by applicable law or agreed to in writing,            software distributed under the License is distributed on an            "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY            KIND, either express or implied.
See the License for the            specific language governing permissions and limitations            under the License.

#Advanced Scope control

There are a number of useful ways to interact with the scopes created by the Transaction Control Service

== Determining the current scope

The Transaction Control Service has methods which can be used to work out whether a scope is in effect:

* `txControl.activeScope();` - When `true` there is a scope in effect and resources can be  accessed.
The scope may, or may not, be transactional.
When false there is no current scope and `txControl.getCurrentContext();` will return `null`.
* `txControl.activeTransaction()` - When `true` there is a transactional scope in  effect and resources can be accessed transactionally.
When false there may, or may not, be a "No Transaction" scope in effect.

Note that `assert txControl.activeTransaction();` can be used to enforce the presence of a transaction.
This is equivalent to a "Mandatory" transaction in Spring or Java EE.

== Avoiding rollback

When setting up a transaction certain exception types can be marked as not triggering rollback:

 txControl.build()
     .noRollbackFor(MyCustomException.class)
     .required(() -> {
             // A MyCustomException thrown here will not trigger rollback
         });

== Nesting a transaction

Nesting a Transaction can easily be managed using `requiresNew()`

 txControl.required(() -> {
         // Do some work...

         return txControl.requiresNew(() -> {
                 // Do some more work
             });
     });

== Suspending a transaction

Suspending a Transaction can easily be managed using `notSupported()`

 txControl.required(() -> {
         // Do some work...

         return txControl.notSupported(() -> {
                 // Do some more work
             });
     });