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

= ejb-throws-exception: Handle Exceptions across JARs in an EAR
:author: Brad Maxwell
:level: Intermediate
:technologies: EJB, EAR

[abstract]
The `ejb-throws-exception` quickstart demonstrates how to throw and handle exceptions across JARs in an EAR.

:standalone-server-type: default
:archiveType: ear

== What is it?

The `ejb-throws-exception` quickstart extends the link:../ejb-in-ear/README{outfilesuffix}[ejb-in-ear] quickstart and demonstrates how to handle exceptions across JARs in an EAR deployed to {productNameFull}. In this quickstart, an EJB in the EJB JAR throws a custom exception. The web application in the client JAR catches the exception and displays it in a nicely formatted message. The EAR contains: _JSF WAR_, an _EJB_ JAR and a client library JAR containg classes that both the WAR and EJB JAR use.

This example consists of the following Maven projects, each with a shared parent.

[cols="30%,70%",options="headers"]
|===
|Project |Description

| `ejb`
a| This project contains the EJB code and can be built independently to produce the JAR archive.

* The EJB has a single method `sayHello` which will take in a String `name`.
* If the `name` is not null or an empty String, it returns `Hello <name>`.
* If the `name` is null or an empty String, it throws a custom `GreeterException` exception back to the client.

| `web`
a| This project contains the JSF pages and the CDI managed bean.

* The CDI Managed Bean, `GreeterBean`, is bound to the JSF page, `index.xhtml`.
* It invokes the `GreeterEJB` and displays the response back from the EJB.
* The `GreeterBean` catches the custom `GreeterException` exception thrown by `GreeterEJB` and displays the exception message in the response text on the JSF page.

| `ear`
| This project builds the EAR artifact and pulls in the ejb, web, and client artifacts.

| `ejb-api`
a| This project builds the ejb-api library artifact which is used by the ejb, web, as well as remote client artifacts.

* This directory contains the EJB interfaces, custom exceptions the EJB throws and any other transfer objects which the EJB may receive or send back to the client.
* The EJB interfaces, custom exceptions, and other transfer objects are split into a separate JAR, which is packaged in the ear/lib. This allows all sub deployments of the EAR to see the classes of the ejb-api JAR in the classpath. This is also useful for remote clients.
* The ejb-api JAR can be distributed to a remote client and give the remote clients the classes that are needed to interact with the EJB.
|===

The root `pom.xml` builds each of the subprojects in the above order and deploys the EAR archive to the server.

The example follows the common "Hello World" pattern, using the following workflow.

. A JSF page asks for a user name.
. On clicking *Say Hello*, the value of the *Name* input text is sent to a managed bean named `GreeterBean`.
. On setting the name, the `Greeter` invokes the `GreeterEJB`, which was injected to the managed bean. Notice that the field is annotated with `@EJB`.
. The EJB responds with *Hello <name>* or throws an exception if the name is empty or null.
. The response or exception's message from invoking the `GreeterEJB` is stored in a field (response) of the managed bean.
. The managed bean is annotated as `@RequestScoped`, so the same managed bean instance is used only for the request/response.


// System Requirements
include::../shared-doc/system-requirements.adoc[leveloffset=+1]
// Use of {jbossHomeName}
include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]
// Start the {productName} Standalone Server
include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1]
// 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}/.

Enter a name in the input field *Name* and click the *Say Hello* button to see the response.

The *Response* output text will display the response from the EJB.
If the *Name* input text box is not empty, then the *Response* output text will display *Hello <name>*
If the *Name* input text box is empty, then the *Response* output text will display the message of the exception throw back from the EJB.

// Undeploy the Quickstart
include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1]
// 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
For this quickstart, follow the special instructions to build link:{useEclipseDeployEARDocUrl}[Quickstarts Containing an EAR].

. Right-click on the *{artifactId}-ear* subproject, and choose *Run As* -> *Run on Server*.
. Choose the server and click *Finish*.
. This starts the server, deploys the application, and opens a browser window that accesses the running application.
. To undeploy the project, right-click on the *{artifactId}-ear* project and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*.

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