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

= tasks-rs: JAX-RS, JPA quickstart
:author: Mike Musgrove
:level: Intermediate
:technologies: JPA, JAX-RS
:prerequisites: link:tasks/README{outfilesuffix}[tasks]

[abstract]
The `tasks-rs` quickstart demonstrates how to implement a JAX-RS service that uses JPA persistence.

:standalone-server-type: default
:archiveType: war
:uses-h2:
:uses-ds-xml:
:app-user-groups: guest

== What is it?

The `tasks-rs` quickstart demonstrates how to implement a JAX-RS service that uses JPA persistence deployed to {productNameFull}.

* The client uses HTTP to interact with the service. It builds on the _tasks_ quickstart, which provides simple task management with secure login.

* The service interface is implemented using JAX-RS. The SecurityContext JAX-RS annotation is used to inject the security details into each REST method.

The application manages `User` and `Task` JPA entities. A user represents an authenticated principal and is associated with zero or more tasks. Service methods validate that there is an authenticated principal and the first time a principal is seen, a JPA User entity is created to correspond to the principal. JAX-RS annotated methods are provided for associating tasks with this user and for listing and removing tasks.


// Considerations for Use in a Production Environment
include::../shared-doc/development-shortcuts.adoc[leveloffset=+1]
// System Requirements
include::../shared-doc/system-requirements.adoc[leveloffset=+1]
// Use of {jbossHomeName}
include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]
// Add the Authorized Application User
include::../shared-doc/add-application-user.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 Resources

Application resources for this quickstart are prefixed with the URL http://localhost:8080/{artifactId}/ and can be accessed by an HTTP client.

* A web browser can be used for methods that accept `GET`.
* Otherwise, you must use cURL or some other command line tool that supports HTTP _POST_ and _DELETE_ methods.

Below you will find instructions to create, display, and delete tasks.

[[create_a_task]]
=== Create a Task

To associate a task called `task1` with the user `quickstartUser`, you must authenticate as user `quickstartUser` and send an HTTP _POST_ request to the url http://localhost:8080/{artifactId}/tasks/title/task1.

To issue the _POST_ command using cURL, type the following command:

[source,options="nowrap"]
----
$ curl -i -u 'quickstartUser:quickstartPwd1!' -H "Content-Length: 0" -X POST http://localhost:8080/{artifactId}/tasks/title/task1
----

You will see the following response:

[source,options="nowrap"]
----
HTTP/1.1 201 Created
Expires: 0
Cache-Control: no-cache, no-store, must-revalidate
X-Powered-By: Undertow/1
Server: JBoss-EAP/7
Pragma: no-cache
Location: http://localhost:8080/{artifactId}/tasks/id/1
Date: Thu, 20 Aug 2015 17:30:24 GMT
----

This is what happens when the command is issued:

* The `-i` flag tells cURL to print the returned headers.
* The `-u` flag provides the authentication information for the request.
* The `-H` flag adds a header to the outgoing request.
* The `-X` flag tells cURL which HTTP method to use. The HTTP _POST_ is used to create resources.
* The `Location` header of the response contains the URI of the resource representing the newly created task.

The final argument to cURL determines the title of the task. Note that this approach is perhaps not very restful but it simplifies this quickstart. A better approach would be to _POST_ to `http://localhost:8080/{artifactId}/tasks/title` passing the task title in the body of the request.

=== Display the XML Representation of a Task

To display the XML representation of the newly created resource, issue a `GET` request on the task URI returned in the `Location` header during the create.

. To issue a `GET` using a browser, open a browser and access the URI. You will be challenged to enter valid authentication credentials.
+
[source,options="nowrap"]
----
http://localhost:8080/{artifactId}/tasks/id/1
----

. To issue a `GET` using cURL, type the following command:
+
[source,options="nowrap"]
----
$ curl -H "Accept: application/xml" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/{artifactId}/tasks/id/1
----
+
The ``-H` flag tells the server that the client wishes to accept XML content.

Using either of the above `GET` methods, you should see the following XML:

[source,xml,options="nowrap"]
----
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <task id="1" ownerName="quickstartUser">
      <title>task1</title>
   </task>
----

=== Display the XML Representation of all Tasks for a User

To obtain a list of all tasks for user `quickstartUser` in XML format, authenticate as user `quickstartUser` and send an HTTP `GET` request to the resource `tasks` URL.

. To issue a `GET` using a browser, open a browser and access the following URL. You will be challenged to enter valid authentication credentials.
+
[source,options="nowrap"]
----
http://localhost:8080/{artifactId}/tasks/title
----

. To list all tasks associated with the user `quickstartUser` using cURL, type:
+
[source,options="nowrap"]
----
$ curl -H "Accept: application/xml" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/{artifactId}/tasks/title
----

Using either of the above `GET` methods, you should see the following XML:

[source,xml,options="nowrap"]
----
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<collection>
    <task id="1" ownerName="quickstartUser">
    <title>task1</title>
    </task>
</collection>
----

=== Delete a Task

To delete a task, again authenticate as principal `quickstartUser` and send an HTTP _DELETE_ request to the URI that represents the task.

To delete the task with id `1`:

[source,options="nowrap"]
----
$ curl -i -u 'quickstartUser:quickstartPwd1!' -X DELETE http://localhost:8080/{artifactId}/tasks/id/1
----

You will see this response:

[source,options="nowrap"]
----
HTTP/1.1 204 No Content
Expires: 0
Cache-Control: no-cache, no-store, must-revalidate
X-Powered-By: Undertow/1
Server: JBoss-EAP/7
Pragma: no-cache
Date: Thu, 20 Aug 2015 17:32:39 GMT
----

Now list all tasks associated with user `quickstartUser`:

[source,options="nowrap"]
----
$ curl -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/{artifactId}/tasks/title
----

You will see a response with an empty collection:

[source,xml,options="nowrap"]
----
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<collection/>
----

== Modify this Quickstart to Support JSON Representations of Tasks

JSON is not part of the JAX-RS standard but most JAX-RS implementations do support it. This quickstart can be modified to support JSON by uncommenting a few lines. Look for comment lines containing `JSON:`:

. Open the `pom.xml` file and remove the comments from the dependency with artifactId `resteasy-jackson2-provider`.
+
[source,xml,options="nowrap"]
----
<!-- JSON: uncomment to include json support (note json is not part of the JAX-RS standard) -->
<!--
<dependency>
    <groupId>org.jboss.resteasy</groupId>
    <artifactId>resteasy-jackson2-provider</artifactId>
    <scope>provided</scope>
</dependency>
-->
----

. Open the `src/main/java/org/jboss/as/quickstarts/tasksrs/model/Task.java` file and remove the comments from the following two lines.
+
[source,java,options="nowrap"]
----
// import com.fasterxml.jackson.annotation.JsonIgnore;

// @JsonIgnore
----

. Open the `src/main/java/org/jboss/as/quickstarts/tasksrs/service/TaskResource.java` file and make sure the `GET` methods produce "application/json" as well as "application/xml". Again, look for lines beginning with `// JSON:`.

** Remove comments from this line:
+
[source,java,options="nowrap"]
----
// @Produces({ "application/xml", "application/json" })
----

** Add comments to this line:
+
[source,java,options="nowrap"]
----
@Produces({ "application/xml" })
----

. Rebuild and redeploy the quickstart.
. xref:create_a_task[Create a Task] as you did for the XML version of this quickstart.

. View task resources in JSON media type by specifying the correct _Accept_ header. For example, using the cURL tool, type the following command:
+
[source,options="nowrap"]
----
$ curl -H "Accept: application/json" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/{artifactId}/tasks/id/1
----
+
You will see the following response:
+
[source,options="nowrap"]
----
{"id":1,"title":"task1","ownerName":"quickstartUser"}
----

== Server Log: Expected Warnings and Errors

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

[source,options="nowrap"]
----
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
include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1]
//  Run the Arquillian Tests
include::../shared-doc/run-arquillian-tests.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
Make sure you xref:add_the_application_user[add the authorized application user].

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