Developing a REST Web Service with MyEclipse

Use MyEclipse to develop REST web services to amp up your web applications. In this tutorial example, you will create a simple web service for maintaining a list of customers. You will learn to:

  • Develop a REST web service
  • Deploy to the MyEclipse Tomcat server
  • Test with the REST Web Services Explorer

Duration Time: 30 Minutes

Start Tutorial Now

Don't have MyEclipse? Download Now

1. Begin with a REST Web Service Project

The REST Web Service Project wizard gets you started with your project configuration.

  1. Click the drop-down arrow on the New icon on the toolbar, and select Web Service Project from the menu.
  2. Type restdemo in the Project Name field, select the REST (JAX-RS) framework option, and click Next.

    Note: This tutorial uses the JavaEE 6 version; however, JavaEE 7 is an available option when creating new projects.

    Creating a Web Service project
  3. Accept the default source folder, and click Next.
  4. Click Finish to accept defaults for the purpose of this example.

    Finishing the project


2. Create a New REST Web Service

With your project in place, you can create your web service. You will create classes necessary for managing the customer entity and a class for your resource methods.

2.1 Creating the Customer entity

This simple Customer class contains id, name, and address fields and represents the Customer entity you manage with the web service.

  1. Right-click the restdemo project, and select New>Class.
  2. Type com.myeclipseide.ws in the Package field, type Customer in the Name field, deselect the Public Static Void Main checkbox if selected, and click Finish.

    Creating a Java class
  3. Replace the default contents of the generated class with the following code, and save the file.

You are using XML as the serialization  format, i.e. you send and receive Customer entities from  the web service using XML.

The @XMLRootElement annotation in the Customer class is a JAXB annotation that allows JAXB to convert this entity from Java to XML and back. It is possible to annotate the fields and methods within the class to customize the serialization, but for this tutorial, the JAXB defaults are fine.

2.2 Create the Resource Class, the Core of the Web Service

  1. Right-click the restdemo project, and select New>Other.
  2. Type web service in the filter field, select Web Service, and click Next.

    Creating the new web service
  3. Select the Create web service from Java class option, select the Create new Java bean checkbox, and click Next.

    Creating the new web service
  4. Type customers in the URL path field, select the Singleton Lifecycle option, select application/xml from the Produces drop-down, type com.myeclipseide.ws in the Java Package field, and type CustomersResource in the Java class field.

    Web service configuration detailsURL path: Indicates the path at which this resource can be reached. For this tutorial, you use customers because this resource manages our customer list. The resource will be hosted at "/customers".

    Singleton Lifecycle: Ensures only one instance of this class is created by Jersey per web-application.

    Consumes and Produces: Can be used to specify the default mime type(s) of data this resource can accept and generate. These values can be overridden by individual methods in the class. As mentioned above, you are serializing to XML, so you use the application/xml mime type.
  5. Click the Add button to add the method that fetches a list of customers.
  6. Type getCustomers in the Method name field, java.util.List<Customer> in the Return type field, and click Finish.

    Adding a methodHTTP method: Can be used to specify the type of HTTP request this method responds to, in this case.

    Method Signature preview: Updated as you make changes to the page, giving you an idea of what your generated method will look like.
  7. Click the Add button again to add a method that returns details of a specific customer.
  8. Type getCustomer in the Method name field, Customer in the Return type field, and {id} in the URL path field.

    Adding a second method
  9. Click the Add button to add a Method parameter. Type int in the Java Type field, cId in the Java Name field, select PathParam from the Param Type drop-down, and type id in the Param Name field. Click Finish.

    Adding method parametersURL Path: Specifies the path at which this method can be reached, relative to the containing resource. 

    In this case you specify {id}, which means this resource method can be reached at /customers/{id}. The curly braces denote a URI variable. These variables are substituted at runtime for a resource to respond to a request based on the substituted URI.

    Parameters:
    Edit the parameters directly in the table. Because you need the value of the id variable, you use the PathParam annotation to map it to the cId parameter.
  10. Add a method that allows you to add a new customer to the list. Fill in the fields as shown below, and click Finish.

    Creating the addCustomer methodIn this case, you're responding to a POST request and expect application/xml input, which would be deserialized into the customer parameter. The customer parameter is an Entity parameter (unannotated) and is mapped directly from the message body of the incoming request. You also override the default application/xml output specified by the CustomersResource class and specify text/html instead.

    After adding those three methods, the configuration should look like this:

    Final web service configuration
  11. Click Finish to generate the CustomersResource class. Open the file to see stubbed out resource methods.

3. Provide Implementations for the Methods You Generated

Now, you need to provide implementations for the methods you created using the wizard. In a real application, at this point you would probably wire in a database using JPA or Hibernate to help manage the customer list, but a simple in-memory map is  sufficient for this tutorial.

The implementation is simple; when a customer is received by the service, you give the entity a counter-based id and add it to the map. Retrieving a customer from this map by id and providing a list of customers is straight forward as you can see below.

Replace the content in the CustomersResource class with the following code. Observe that the class and method signatures have not changed. You are fleshing out the generated stubs with an implementation of the service. You also add a single customer to the list for demonstration purposes.


4. Deploy the Web Service Application

The fastest way to deploy the web service is by using the Run As or Debug As MyEclipse Server Application action.

  1. Right-click the project, and select Debug As (or Run As)>MyEclipse Server Application.

    Deploying and running the project
  2. Select MyEclipse Tomcat, and click Finish.
    selecting_server
    Selecting a server for deployment

MyEclipse performs the following steps:

  • Packages the Web Service project and deploys it in Exploded format to the application server
  • Starts the application server and loads the project

The MyEclipse Web Browser opens the default index.jsp page of our the Web Service application. You don't need this because you aren't testing a web page, so you can close this view.

5. Test with the REST Web Services Explorer 

The REST Web Services Explorer is unavailable at the MyEclipse Standard subscription level. If you are a MyEclipse Standard subscriber, follow the instructions in Testing a Web Service Using a Standard Browser.

  1. Right-click the restdemo project, and select MyEclipse>Test with REST Web Services Explorer.

    Opening the REST Web Services ExplorerNote: If you deployed restdemo to an application server other than MyEclipse Tomcat, the WADL URL used in the explorer could contain an incorrect port, preventing the explorer from loading your WADL file. Correct the port, and click the Go button to proceed.

    You can also open the REST Web Services Explorer by clicking the drop-down arrow on the Web Services Explorer icon on the toolbar, and selecting Launch REST Web Services Explorer. In this case, you must enter the path of a WADL file in the address bar before proceeding.
  2. Expand the tree to the {id} node, and select the getCustomer method.

    Selecting the method to test
  3. Click Test method. A new tab opens where you can enter information and run the test.

    getCustomer tab for testing the method
  4. Type 0 in the id field, and click the Run Test icon .

    Retrieving the one customer in the list
  5. Close the getCustomer tab.
  6. Expand add in the tree, select the addCustomer method, and click Test method.
  7. In the Body, type application/xml area of the addCustomer tab, paste the following code, and click .

    The response confirms, Customer Bill Adama added with Id 1.

    Testing the add function

  8. Close the addCustomer tab.
  9. Select getCustomers in the customers node, and click Test method.
  10. Click . The two customers in the list are returned by the service in XML.

    Retrieving the entire customer list


6. Resources