Download Restlet Framework

  • Open Source
  • RESTful
  • Client & Server
  • Scalable
  • Secure
Order Your Free Restlet Stickers!
Fill in the form below and receive free Restlet stickers in your mailbox!

Your details will never be shared to a 3rd party. We hate spam just as much as you do.

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.

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.resource.Get;
import org.restlet.resource.ServerResource;

public class HelloWorldResource extends ServerResource {

    @Get
    public String represent() {
        return "hello, world";
    }
}
   

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.Restlet;
import org.restlet.routing.Router;

public class FirstStepsApplication extends Application {

    /**
     * Creates a root Restlet that will receive all incoming calls.
     */
    @Override
    public Restlet createInboundRoot() {
        // 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
  • org.restlet.ext.servlet.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>
         org.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".

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

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

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());

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

Conclusion

We hope you that enjoyed these simple steps and we now encourage you to move on to the Learn section for more advanced examples.

Notes
  • Thanks to Didier Girard for suggesting this page.

Maven configuration

The Maven repository for Restlet is accessible from http://maven.restlet.com and contains all Restlet JARs and third party dependencies that aren't available in the main public Maven repository. It is automatically refreshed once a day if the build succeeds.

Sample POM

Each Restlet Framework project needs at least one dependency: the Restlet core module and we assume that you will use Jackson for JSON support. You also need to configure your Maven client to point to the dedicated Restlet repository. Just open and edit the pom.xml file for your project and add the following lines of text:

<repositories>
    <repository>
        <id>maven-restlet</id>
        <name>Restlet repository</name>
        <url>http://maven.restlet.com</url>
    </repository>
</repositories>
<properties>
    <restlet-version>2.2.1</restlet-version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.restlet.jse</groupId>
        <artifactId>org.restlet</artifactId>
        <version>${restlet-version}</version>
    </dependency>
    <dependency>
        <groupId>org.restlet.jse</groupId>
        <artifactId>org.restlet.ext.jackson</artifactId>
        <version>${restlet-version}</version>
    </dependency>
</dependencies>
	   

Available artifacts

According to your needs, you might have to complete the list of dependencies. The table table lists available artifacts and their group and artifact ids.

As Restlet Framework supports multiple editions, it is necessary to make a distinction between an extension for a given edition and the same extension for another one. This is reflected in the group id of each artifact. They folllow the same pattern: org.restlet.<edition> where <edition> is three-letters code of an edition among: jse (Java SE edition), jee (Java EE edition), gae (Google App Engine edition), android (Android edition) and gwt (google Web Toolkit edition).

Please find below the list of extensions available for the release and edition that you selected.

artifactId Description
org.restlet Restlet API
org.restlet.example Examples
org.restlet.ext.atom Atom extension
org.restlet.ext.crypto Cryptography extension including Amazon S3 and Windows Azure client authentication.
org.restlet.ext.fileupload Integration with Apache FileUpload.
org.restlet.ext.freemarker Integration with FreeMarker.
org.restlet.ext.grizzly Integration with Grizzly NIO framework.
org.restlet.ext.gwt Server-side integration with GWT.
org.restlet.ext.httpclient Integration with Apache HTTP Client.
org.restlet.ext.jaas Support for JAAS authentication and authorization framework.
org.restlet.ext.jackson Integration with Jackson.
org.restlet.ext.javamail Integration with JavaMail (POP3 and SMTP clients)
org.restlet.ext.jaxb Integration with Java XML Binding (JAXB).
org.restlet.ext.jaxrs Implementation of JAX-RS.
org.restlet.ext.jdbc Integration with Java DataBase Connectivity (JDBC).
org.restlet.ext.jetty Integration with Jetty.
org.restlet.ext.jibx Integration with JiBX.
org.restlet.ext.json Support for JSON representations.
org.restlet.ext.lucene Integration with Apache Lucene.
org.restlet.ext.net Integration with Java URLConnection class.
org.restlet.ext.netty Integration with Netty.
org.restlet.ext.odata Support for the OData Services.
org.restlet.ext.rdf Support for the RDF parsing and generation.
org.restlet.ext.rome Integration with ROME.
org.restlet.ext.servlet Integration with Servlet API.
org.restlet.ext.simple Integration with Simple Framework.
org.restlet.ext.slf4j Integration with SLF4J.
org.restlet.ext.spring Integration with Spring Framework.
org.restlet.ext.ssl Support for SSL utilities and integration with jSSLutils library.
org.restlet.ext.velocity Integration with Apache Velocity.
org.restlet.ext.wadl Support the WADL specification.
org.restlet.ext.xdb Integration with Oracle 11g XML DB feature.
org.restlet.ext.xml Support for XML and XSLT representations.
org.restlet.ext.xstream Integration with XStream.
org.restlet.test Test module.

Alternative repository configuration

Sometimes its more convenient to declare the same repository for all of your projects. To do so, just go to your Maven installation directory. Open and edit conf/settings.xml file and add to the <profiles> section the following code:

<profile>
  <id>restlet</id>
  <repositories>
     <repository>
        <id>maven-restlet</id>
        <name>Restlet Framework repository</name>
        <url>http://maven.restlet.com</url>
     </repository>
  </repositories>
</profile>
   

Just after the </profiles> add the following:

<activeProfiles>
    <activeProfile>restlet</activeProfile>
</activeProfiles>
   

Eclipse update site

Introduction

This update site is only intended for the Restlet edition for OSGi environments. It allows the retrieval of Restlet modules and their dependencies as plain bundles (including their dependencies) directly from the Eclipse IDE. They are gathered by type of module: Core module, support of standards, pluggable connectors and integrations with third-party libraries. It is only available from the 2.1 release and beyond.

The URL of the update site is based on the following pattern http://p2.restlet.com/2.2/. It provides all tagged releases (such as current snapshot, or milestones, releases candidates, etc). It is automatically refreshed once a day if the build succeeds.

Installation steps

Here are some instructions about how to configure your Eclipse IDE to work with the online update site.

Just go to the “help/Install New Software” menu. Enter the URL of the desired repository in the upper field:

Add the eclipse update site to the IDE.

The available items are listed by category (Restlet Core, Pluggable connectors, etc.). Just make your selection, and click on the “Next” button:

Select plugins to be installed.

After a few moments of calculation (required dependencies among others calculation), you will be warned that you are on the way to install unsigned content. Just stick to your choice and click the “OK” button:

Valid the warning message: the content is unsigned.

The installation process goes on, and after a few moment you will be asked to restart your Eclipse instance in order to finalize the installation.