Restlet 1.0 - First steps

Table of contents

This page should allow you to taste the simplicity of the Restlet Framework in less than 10 minutes. It explains how to create a Resource that says "hello, world".

  1. What do I need?
  2. The "hello, world" application
  3. Run in a Servlet container
  4. Run as a standalone Java application
  5. Conclusion

What do I need?

We assume that you have a development environment set up and operational, and that you already have installed the JRE 1.5 (or higher). In case you haven't downloaded Restlet yet, select one of the available distributions of the latest release of the Restlet framework v1.0.

The "hello, world" application.

Let's start with the core of a REST application: the Resource. Here is the code of the single resource defined by the sample application. Copy/paste the code in your "HelloWorldResource" class. 

package firstSteps;

import org.restlet.Context;
import org.restlet.data.MediaType;
import org.restlet.data.Request;
import org.restlet.data.Response;
import org.restlet.resource.Representation;
import org.restlet.resource.Resource;
import org.restlet.resource.StringRepresentation;
import org.restlet.resource.Variant;

/**
 * Resource which has only one representation.
 *
 */
public class HelloWorldResource extends Resource {

   public HelloWorldResource(Context context, Request request,
         Response response) {
      super(context, request, response);

      // This representation has only one type of representation.
      getVariants().add(new Variant(MediaType.TEXT_PLAIN));
   }

   /**
    * Returns a full representation for a given variant.
    */
   @Override
   public Representation getRepresentation(Variant variant) {
      Representation representation = new StringRepresentation(
            "hello, world", MediaType.TEXT_PLAIN);
      return representation;
   }
}

Then, create the sample application. Let's call it "FirstStepsApplication" and copy/paste the following code: 

package firstSteps;

import org.restlet.Application;
import org.restlet.Context;
import org.restlet.Restlet;
import org.restlet.Router;

public class FirstStepsApplication extends Application {

   public FirstStepsApplication(Context parentContext) {
      super(parentContext);
   }

   /**
    * Creates a root Restlet that will receive all incoming calls.
    */
   @Override
   public synchronized Restlet createRoot() {
      // Create a router Restlet that routes each call to a
      // new instance of HelloWorldResource.
      Router router = new Router(getContext());

      // Defines only one route
      router.attachDefault(HelloWorldResource.class);

      return router;
   }
}

Run in a Servlet container

As you are probably more familiar with Servlets, we propose you to run the Restlet application inside your favorite Servlet container. Create a new Servlet Web application as usual, add a "firstStepsServlet" package and put the resource and application classes in. Add the archives listed below into the directory of librairies (/WEB-INF/lib):

  • org.restlet.jar
  • com.noelios.restlet.jar
  • com.noelios.restlet.ext.servlet_2.4.jar

Then, update the "web.xml" configuration file as follow: 

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.4"
            xmlns="http://java.sun.com/xml/ns/j2ee"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
                 http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
   <display-name>first steps servlet</display-name>
   <!-- Application class name -->
   <context-param>
      <param-name>org.restlet.application</param-name>
      <param-value>
         firstSteps.FirstStepsApplication
      </param-value>
   </context-param>

   <!-- Restlet adapter -->
   <servlet>
      <servlet-name>RestletServlet</servlet-name>
      <servlet-class>
         com.noelios.restlet.ext.servlet.ServerServlet
      </servlet-class>
   </servlet>

   <!-- Catch all requests -->
   <servlet-mapping>
      <servlet-name>RestletServlet</servlet-name>
      <url-pattern>/*</url-pattern>
   </servlet-mapping>
</web-app>

Finally, package the whole as a WAR file called for example "firstStepsServlet.war" and deploy it inside your Servlet container. Once you have launched the Servlet container, kindly open your favourite web browser, and gently type the following URL: "http://<your server name>:<its port number>/firstStepsServlet". The server will happily welcome you with a nice "hello, world".

You can find the WAR file (packaged with archives taken from Restlet 1.0.7) in the "First steps application" files.

Run as a standalone Java application

A Restlet application cannot only run inside a Servlet container, but can also be run as a standalone Java application using a couple of JARs:

  • org.restlet.jar
  • com.noelios.restlet.jar
  • com.noelios.restlet.ext.simple.jar
  • org.simpleframework.jar

If you want to understand the purpose of each of the two last JARs, you can have a look at the connectors page.

Create also a main class, copy/paste the following code wich aims at defining a new HTTP server listening on port 8182 and delegating all requests to the "FirstStepsApplication". 

package firstSteps;
import org.restlet.Component;
import org.restlet.data.Protocol;

public class FirstStepsMain {

    public static void main(String[] args) {
        try {
            // Create a new Component.
            Component component = new Component();
            // Add a new HTTP server listening on port 8182.
            component.getServers().add(Protocol.HTTP, 8182);

            // Attach the sample application.
            component.getDefaultHost().attach(
                    new FirstStepsApplication(component.getContext()));

            // Start the component.
            component.start();
        } catch (Exception e) {
            // Something is wrong.
            e.printStackTrace();
        }
    }
}

Once you have launched the main class, if you kindly open your favourite web browser, and gently type the following URL: http://localhost:8182/, the server will happily welcome you with a nice "hello, world". Otherwise, make sure that the classpath is correct and that no other program is currently using the port 8182.

You can find the sources of this sample application in the "First steps application" files.

Conclusion

We hope you that enjoyed these simple steps and we now encourage you to move on quietly to the first Resource page or dive deeper in the Restlet tutorial.

Notes