Red Hat

Developer Materials

tasks-rs: JAX-RS, JPA quickstart

  • Author:
  • Contributors: Sande Gilda, Pete Muir , LightGuard, mmusgrov
  • Published: Jan 26, 2016
  • Level: Intermediate
  • Technologies:JPA, JAX-RS
  • Target Product:JBoss EAP

What is it?

The tasks-rs quickstart demonstrates how to implement a JAX-RS service that uses JPA persistence deployed to Red Hat JBoss Enterprise Application Platform.

  • 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.

Note: This quickstart uses the H2 database included with Red Hat JBoss Enterprise Application Platform 7. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!

Note: This quickstart uses a *-ds.xml datasource configuration file for convenience and ease of database configuration. These files are deprecated in JBoss EAP and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the Configuration Guide for Red Hat JBoss Enterprise Application Platform.

System requirements

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 7 or later.

All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.1.1 or later. See Configure Maven for JBoss EAP 7 to make sure you are configured correctly for testing the quickstarts.

Use of EAP7_HOME

In the following instructions, replace EAP7_HOME with the actual path to your JBoss EAP installation. The installation path is described in detail here: Use of EAP7_HOME and JBOSS_HOME Variables.

Add an Application User

This quickstart uses secured management interfaces and requires that you create the following application user to access the running application.

UserName Realm Password Roles
quickstartUser ApplicationRealm quickstartPwd1! guest

To add the application user, open a command prompt and type the following command:

  For Linux:   EAP7_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest'
  For Windows: EAP7_HOME\bin\add-user.bat  -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest'

If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: Add an Application User.

Start the JBoss EAP Server

  1. Open a command prompt and navigate to the root of the JBoss EAP directory.
  2. The following shows the command line to start the server:

     For Linux:   EAP7_HOME/bin/standalone.sh
     For Windows: EAP7_HOME\bin\standalone.bat
    

Build and Deploy the Quickstart

  1. Make sure you have started the JBoss EAP server as described above.
  2. Open a command prompt and navigate to the root directory of this quickstart.
  3. Type this command to build and deploy the archive:

     mvn clean install wildfly:deploy
    
  4. This will deploy target/jboss-tasks-rs.war to the running instance of the server.

Access the Application Resources

Application resources for this quickstart are prefixed with the URL http://localhost:8080/jboss-tasks-rs/ 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

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/jboss-tasks-rs/tasks/task1.

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

curl -i -u 'quickstartUser:quickstartPwd1!' -H "Content-Length: 0" -X POST http://localhost:8080/jboss-tasks-rs/tasks/task1

You will see the following response:

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/jboss-tasks-rs/tasks/1
Date: Thu, 20 Aug 2015 17:30:24 GMT
Connection: keep-alive
Content-Length: 0

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/jboss-tasks-rs/tasks" 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.

  1. To issue a GET using a browser, open a browser and access the URI. You will be challenged to enter valid authentication credentials.

    http://localhost:8080/jboss-tasks-rs/tasks/1

  2. To issue a GET using cURL, type the following command:

     curl -H "Accept: application/xml" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/jboss-tasks-rs/tasks/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:

<?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.

  1. To issue a GET using a browser, open a browser and access the following URL. You will be challenged to enter valid authentication credentials.

    http://localhost:8080/jboss-tasks-rs/tasks

  2. To list all tasks associated with the user quickstartUser using cURL, type:

     curl -H "Accept: application/xml" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/jboss-tasks-rs/tasks
    

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

<?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:

curl -i -u 'quickstartUser:quickstartPwd1!' -X DELETE http://localhost:8080/jboss-tasks-rs/tasks/1

You will see this response:

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
Connection: keep-alive
Content-Length: 0

Now list all tasks associated with user quickstartUser:

curl -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/jboss-tasks-rs/tasks

You will see a response with an empty collection:

<?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 lines beginning with "// JSON:":

  1. Open the file src/main/java/org/jboss/as/quickstarts/tasksrs/model/Task.java and remove the comments from the following two lines.

     // import com.fasterxml.jackson.annotation.JsonIgnore;
    
     // @JsonIgnore
    
  2. Open the file src/main/java/org/jboss/as/quickstarts/tasksrs/service/TaskResource.java and make sure the GET methods produce "application/json" as well as "application/xml". Again, look for lines beginning with "// JSON:".
    • Remove comments from these lines:

      //@Produces({ "application/xml", "application/json" })
      
    • Add comments to these lines:

      @Produces({ "application/xml" })
      
  3. Open pom.xml and remove the comments from the dependency with artifactId resteasy-jackson2-provider

     <!--
     <dependency>
         <groupId>org.jboss.resteasy</groupId>
         <artifactId>resteasy-jackson2-provider</artifactId>
         <scope>provided</scope>
     </dependency>
     -->
    
  4. Rebuild and redeploy the quickstart.
  5. Create a Task as you did for the XML version of this quickstart.

  6. View task resources in JSON media type by specifying the correct Accept header. For example, using the cURL tool, type the following command:

     curl -H "Accept: application/json" -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/jboss-tasks-rs/tasks/1
    

You will see the following response:

  {"id":1,"title":"task1","ownerName":"quickstartUser"}

Server Log: Expected warnings and errors

Note: 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 Archive

  1. Make sure you have started the JBoss EAP server as described above.
  2. Open a command prompt and navigate to the root directory of this quickstart.
  3. When you are finished testing, type this command to undeploy the archive:

     mvn wildfly:undeploy
    

Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a JBoss EAP server, and build and deploy a quickstart, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts

Be sure to Add an Application User as described above.

Note: When you deploy this quickstart, you see the following error. This is because JBoss Developer Studio automatically attempts to access the URL http://localhost:8080/jboss-tasks-rs/, however, all incoming requests are handled by the REST application. You can ignore this error.

JBWEB000065: HTTP Status 404 - RESTEASY001185: Could not find resource for relative : / of full path: http://localhost:8080/jboss-tasks-rs/

Debug the Application

If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it.

mvn dependency:sources

Recent Changelog

  • Jan 26, 2016(Sande Gilda):JBEAP 3041 Updgrade quickstarts to use the resteasy jackson2 provider
  • Jan 13, 2016(Sande Gilda):JBEAP 787 Update README file datasource reference pointer to the documentation
  • Dec 22, 2015(Sande Gilda):JBEAP 787 Update JBoss EAP documentation links for JBoss EAP 7
  • Sep 29, 2015(Sande Gilda):JBEAP 836 Replace Server WildFly 10 with Server JBoss EAP 7 in tasks rs README
  • Sep 15, 2015(Sande Gilda):JBEAP 782 Remove resteasy jackson provider version comment from tasks rs README file
  • Aug 20, 2015(Sande Gilda):JBEAP 785 Fix order of JSON instructions in tasks rs quickstart README file
  • Aug 20, 2015(Sande Gilda):JBEAP 782 Update org.jboss.resteasy resteasy jackson provider to use EAP BOM update README output
  • Aug 20, 2015(Sande Gilda):JBEAP 577 Replace links to shared resources for JBoss EAP 7 material
  • Aug 20, 2015(Sande Gilda):JBEAP 777 Update tasks rs README to remove redundant phrase and clean up other instructions
  • Aug 10, 2015(Sande Gilda):JBEAP 600 Update warning for use of ds.xml files in deployments
Avg:
Your Rating:
×