= bmt: Bean Managed Transactions with JPA and JTA
:author: Mike Musgrove
:productName: WildFly
:productNameFull: WildFly Application Server
:jbossHomeName: WILDFLY_HOME
:productVersion: 12
:buildRequirements: Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later
include::../shared-doc/attributes.adoc[]

:level: Intermediate
:technologies: EJB, BMT
:source: {githubRepoUrl}

[abstract]
The `bmt` quickstart demonstrates Bean-Managed Transactions (BMT), showing how to manually manage transaction demarcation while accessing JPA entities.

:standalone-server-type: default
:archiveType: war

== What is it?

The `bmt` quickstart demonstrates how to manually manage transaction demarcation while accessing JPA entities in {productNameFull}.

On occasion, the application developer requires finer grained control over the lifecycle of JTA transactions and JPA Entity Managers than the defaults provided by the Java EE container. This example shows how the developer can override these defaults and take control of aspects of the lifecycle of JPA and transactions.

When you run this example, you are presented with a *Use bean managed Entity Managers* checkbox.

* If you check the checkbox, it shows the developer responsibilities when injecting an Entity Manager into a managed (stateless) bean.
* If you uncheck the checkbox, shows the developer responsibilities when using JPA and transactions with an unmanaged component.

This example shows how to transactionally insert key value pairs into the database and demonstrates the requirements on the developer with respect to the JPA Entity Manager.

//*************************************************
// Add notes about use in a production environment.
//*************************************************
// == Considerations for Use in a Production Environment
:uses-h2:
:uses-ds-xml:
:performance-scalability:
include::../shared-doc/development-shortcuts.adoc[leveloffset=+1]

//*************************************************
// Add System Requirements
//*************************************************
// == System Requirements
include::../shared-doc/system-requirements.adoc[leveloffset=+1]

//*************************************************
// Add Use of JBoss Home Name
//*************************************************
// == Use of {jbossHomeName}
include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]

//*************************************************
// Start the server with the default profile
//*************************************************
// == Start the {productName} Standalone Server
include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1]

//*************************************************
// Build and deploy the quickstart WAR
//*************************************************
// == Build and Deploy the Quickstart
include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1]

== Access the Application

The application will be running at the following URL: http://localhost:8080/{artifactId}/.

You are presented with a simple form for adding key/value pairs, and a checkbox to indicate whether the updates should be executed using an unmanaged component. Effectively this will run the transaction and JPA updates in the servlet, not session beans. If the box is checked then the updates are executed within a session bean method.

. To list all pairs leave the *Key* input field empty.
. To add or update the value of a key, fill in the *Key* and *Value* input fields.
. Click the *Submit* button to see the results.

== Server Log: Expected Warnings and Errors

You will see the following warnings in the server log. You can ignore these warnings.

----
WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version.

HHH000431: Unable to determine H2 database version, certain features may not work
----

//*************************************************
// Undeploy the quickstart archive
//*************************************************
// == Undeploy the Quickstart
include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1]


//*************************************************
// Add JBoss Developer Studio instructions
//*************************************************
// == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse
include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1]

//*************************************************
// Deploy the quickstart to OpenShift
//*************************************************
// == Deploy the Quickstart to OpenShift Online
include::../shared-doc/deploy-to-openshift-online.adoc[leveloffset=+1]

//*************************************************
// Add info to debug the application
//*************************************************
// == Debug the Application
include::../shared-doc/debug-the-application.adoc[leveloffset=+1]
