include::../shared-doc/attributes.adoc[]

= shopping-cart: EJB Stateful Session Bean (SFSB) Example
:author: Serge Pagop
:level: Intermediate
:technologies: SFSB EJB

[abstract]
The `shopping-cart` quickstart demonstrates how to deploy and run a simple {javaVersion} shopping cart application that uses a stateful session bean (SFSB).

:standalone-server-type: default
:archiveType: jar
:archiveDir: {artifactId}/server/target
:includes-cli-scripts:
:restoreScriptName: restore-system-exception.cli

== What is it?

The `shopping-cart` quickstart demonstrates how to deploy and run a simple {javaVersion} application that uses a stateful session bean (SFSB) in {productNameFull}. The application allows customers to buy, checkout, and view their cart contents.

The `shopping-cart` application consists of the following:

. A server side component:
+
This standalone Java EE module is a JAR containing EJBs. It is responsible for managing the shopping cart.

. A Java client:
+
This simple Java client is launched using a `main` method. The remote client looks up a reference to the server module's API, via JNDI. It then uses this API to perform the operations the customer requests.

// System Requirements
include::../shared-doc/system-requirements.adoc[leveloffset=+1]
// Use of {jbossHomeName}
include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]
// Back Up the {productName} Standalone Server Configuration
include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1]
// Start the {productName} Standalone Server
include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1]

[[configure_the_server]]
== Configure the Server

This example quickstart purposely throws a `NoSuchEJBException` exception when the shopping cart is empty. This is the expected result because method is annotated with `@Remove`. This means the next invocation after the shopping cart checkout fails because the container has destroyed the instance and it is no longer available. If you do not run this script, you see the following ERROR in the server log, followed by the stacktrace

[source,options="nowrap"]
----
ERROR [org.jboss.as.ejb3.invocation] (EJB default - 7) WFLYEJB0034: EJB Invocation failed on component ShoppingCartBean for method public abstract java.util.Map org.jboss.as.quickstarts.sfsb.ShoppingCart.getCartContents(): javax.ejb.NoSuchEJBException: WFLYEJB0168: Could not find EJB with id UnknownSessionID [5168576665505352655054705267485457555457535250485552546568575254]
----

Follow the steps below to suppress system exception logging.

. Before you begin, make sure you  do the following:

* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above.
* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above.

. Review the `configure-system-exception.cli` file in the root of this quickstart directory. This script sets the `log-system-exceptions` attribute to `false` in the `ejb3` subsystem in the server configuration file.
. Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing __{jbossHomeName}__ with the path to your server:
+
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-system-exception.cli
----
+
NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script.

+
You should see the following result when you run the script:
+
[source,options="nowrap"]
----
The batch executed successfully
----

. Stop the {productName} server.

== Review the Modified Server Configuration

After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes.

You should see the following configuration in the `ejb3` subsystem.

[source,xml,options="nowrap"]
----
<log-system-exceptions value="false"/>
----

// Install the Quickstart Parent Artifact in Maven
include::../shared-doc/install-quickstart-parent-artifact.adoc[leveloffset=+1]

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

// Additional deployment information

You can also check the server console to see information messages regarding the deployment.

[source,options="nowrap"]
----
INFO  [org.jboss.as.ejb3.deployment] (MSC service thread 1-2) WFLYEJB0473: JNDI bindings for session bean named 'ShoppingCartBean' in deployment unit 'deployment "{artifactId}-server.jar"' are as follows:

  java:global/{artifactId}-server/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart
  java:app/{artifactId}-server/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart
  java:module/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart
  java:jboss/exported/{artifactId}-server/ShoppingCartBean!org.jboss.as.quickstarts.sfsb.ShoppingCart
  java:global/{artifactId}-server/ShoppingCartBean
  java:app/{artifactId}-server/ShoppingCartBean
  java:module/ShoppingCartBean

INFO  [org.jboss.weld.deployer] (MSC service thread 1-4) WFLYWELD0006: Starting Services for CDI deployment: {artifactId}-server.jar
INFO  [org.jboss.weld.deployer] (MSC service thread 1-8) WFLYWELD0009: Starting weld service for deployment {artifactId}-server.jar
INFO  [org.jboss.as.server] (management-handler-thread - 3) WFLYSRV0010: Deployed "{artifactId}-server.jar" (runtime-name : "{artifactId}-server.jar")
----

== Run the Client Application

Now start a client that will access the beans you just deployed.

You can use the terminal from the previous step or open a new one and navigate to the root of the `shopping-cart` quickstart directory.

Type the following command:

[source,options="nowrap"]
----
$ mvn exec:java -f client/pom.xml
----

== Investigate the Console Output

You should see the following:

. The client sends a remote method invocation to the stateful session bean to buy two `32 GB USB 2.0 Flash Drive` and one `Wireless Ergonomic Keyboard and Mouse`.
. The client sends a remote method invocation to get the contents of the cart and prints it to the console.
. The client sends a remote method invocation to invoke checkout. Note the `checkout()` method in the server `ShoppingCartBean` has the `@Remove` annotation. This means the container will destroy shopping cart after the call and it will no longer be available.
. The client calls `getCartContents()` to make sure the shopping cart was removed after checkout. This results in a `javax.ejb.NoSuchEJBException` trace in the server, proving the cart was removed.

. On the client console, you should see output similar to:
+
[source,options="nowrap"]
----
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
Obtained the remote interface to the shopping cart
Buying a "32 GB USB 2.0 Flash Drive".
Buying another "32 GB USB 2.0 Flash Drive".
Buying a "Wireless Ergonomic Keyboard and Mouse"

Print cart:
1     Wireless Ergonomic Keyboard and Mouse
2     32 GB USB 2.0 Flash Drive

Checkout
Cart was correctly removed, as expected, after Checkout
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
----

. In the server log, you should see:
+
[source,options="nowrap"]
----
INFO  [stdout] (pool-9-thread-8) implementing checkout() left as exercise for the reader!
----

// Undeploy the Quickstart
include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1]
// Restore the {productName} Standalone Server Configuration
include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1]

// Additional information about this script
This script restores the the `log-system-exceptions` attribute value to `true`. You should see the following result when you run the script:
+
[source,options="nowrap"]
----
The batch executed successfully
----

// Restore the {productName} Standalone Server Configuration Manually
include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2]
// Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse
include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1]

// Additional JBoss Developer Studio instructions
This quickstart consists of multiple projects, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts.

* Make sure you configure {productName} to suppress system exception logging as described above under xref:configure_the_server[Configure the Server]. Stop the server at the end of that step.
* To deploy the server project, right-click on the *{artifactId}-server* project and choose *Run As* –> *Run on Server*.
* To run the client, right-click on the *{artifactId}-client* project and choose *Run As* –> *Java Application*. In the *Select Java Application* window, choose *Client - org.jboss.as.quickstarts.client* and click *OK*. The client output displays in the *Console* window.
* To undeploy the project, right-click on the *{artifactId}-server* project and choose *Run As* –> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*.
* Make sure you xref:restore_the_server_configuration[restore the {productName} standalone server configuration] when you have completed testing this quickstart.

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