The Restlet framework is composed of four main parts.
1. Restlet API
First, there is the "Restlet API", a neutral API supporting the concepts of REST and facilitating the handling of calls for both client-side and server-side applications. This API is backed by the Restlet Engine and both are now shipped in a single JAR ("org.restlet.jar").
This separation between the API and the implementation is similar to the one between the Servlet API and Web containers like Jetty or Tomcat, or between the JDBC API and concrete JDBC drivers.
2. Retrieving the content of a Web page
As we mentioned in the introduction paper, the Restlet framework is at the same time a client and a server framework. For example, Restlet can easily work with remote resources using its HTTP client connector. A connector in REST is a software element that enables the communication between components, typically by implementing one side of a network protocol. Restlet provides several implementations of client connectors based on existing open-source projects. The connectors section lists all available client and server connectors and explain how to use and configure them.
Here we will get the representation of an existing resource and output it in the JVM console:
// Outputting the content of a Web page
new ClientResource("http://").get().write(System.out);
Note that the example above uses a simplified way to issue calls via the ClientResource class. If you need multi-threading or more control it is still possible to manipulate use the Client connector class or the Request objects directly. The example below how to set some preferences in your client call, like a referrer URI. It could also be the languages and media types you prefer to receive as a response:
// Create the client resource
ClientResource resource = new ClientResource("http://www.restlet.org");
// Customize the referrer property
resource.setReferrerRef("http://www.mysite.org");
// Write the response entity on the console
resource.get().write(System.out);
3. Listening to Web browsers
Now, we want to see how the Restlet framework can listen to client requests and reply to them. We will use the internal Restlet HTTP server connector (even though it is possible to switch to others such as the one based on Mortbay's Jetty) and return a simple string representation "hello, world" as plain text. Note that the Part03 class extends the base ServerResource class provided by Restlet:
public class Part03 extends ServerResource {
public static void main(String[] args) throws Exception {
// Create the HTTP server and listen on port 8182
new Server(Protocol.HTTP, 8182, Part03.class).start();
}
@Get
public String toString() {
return "hello, world";
}
}
If you run this code and launch your server, you can open a Web browser and hit the . Actually, any URI will work, try also.
Note that if you test your server from a different machine, you need to replace "localhost" by either the IP address of your server or its domain name if it has one defined.
So far, we have mostly showed you the highest level of abstraction in the Restlet API, with the ClientResource and ServerResource classes. But as we move forward, you will discover that those two classes are supported by a rich API, letting you manipulate all the REST artifacts.
4. Overview of a REST architecture
Let's step back a little and consider typical web architectures from a REST point of view. In the diagram below, ports represent the connector that enables the communication between components which are represented by the larger boxes.
