DOCSEARCHbyAlgolia
Submit Docs

Restlet Framework Java Documentation

repository·2.6·Indexed 20 days ago

https://github.com/restlet/restlet-framework-java

A mature Java-based framework for building RESTful web services and clients. It provides a unified API aligned with HTTP and REST principles, supporting deployment across microservices, Android, GWT, OSGi, and GAE. Key features include dynamic routing, security, and extensions for Google Guice, Jetty, and Atom feeds.

Tokens
4.1K
Snippets
13
Records
18
Agent score
61%

What's inside Restlet Framework

  1. Overview of Restlet Framework

    2.6

    Restlet Framework is an open-source Java framework designed for building RESTful applications. It provides a unified API for developing both web clients and web servers, closely following REST architecture and HTTP protocol concepts.

    Key features include:

    • Dynamic Routing and Security: Powerful tools for managing request routing and application security.
    • Flexible Deployment: Can be deployed in Servlet containers or run directly in a JVM with minimal dependencies, making it suitable for microservices.
    • Broad Environment Support: Available in editions compatible with Java SE/EE, GAE (Google App Engine), OSGi, Android, and a separate GWT edition.
    • Extensibility: Offers several extensions for common use cases and is designed to be easily extended.

  3. Access Restlet Framework resources

    2.6

    To get started with Restlet Framework, you can access the following official resources:

    • Downloads: Get the latest versions of the framework.
    • Tutorials: Step-by-step guides for learning the framework.
    • User Guide: Comprehensive documentation for all features.
    • JavaDocs: Detailed API reference.
    • What's New: Release notes and updates.
    • Community Support: Engage via GitHub Issues, Discussions, or Stack Overflow (tag: restlet).

  4. Access the underlying RestletHelper via Context

    2.6

    For advanced use cases, you can retrieve the RestletHelper instance used by a Client from the Context object. This is useful if you need to interact directly with the engine's implementation details.

    When a Client is initialized with a Context, the helper is stored in the context attributes using the following key:

    org.restlet.engine.helper

  5. How Server and Finder work together

    2.6

    In the Restlet framework, a Server is a Connector that accepts incoming network connections. To actually process the logic of a request, the Server delegates to a next Restlet.

    Commonly, this next component is a Finder. When you provide a Class<? extends ServerResource> to the server via setNext(Class<? extends ServerResource> nextClass), the server creates a Finder. When a request arrives, the Finder identifies the appropriate ServerResource instance, instantiates it, and calls its handle method. This allows you to map URI patterns to specific resource classes.

    // Using a Class instead of a Restlet instance to trigger Finder logic
Server server = new Server(context, Protocol.HTTP, 8080, MyResource.class);

  6. Initialize a Restlet Server

    2.6

    The org.restlet.Server class acts as a generic connector for hosting RESTful services. You can initialize a server by specifying the protocol (e.g., HTTP), the listening port, and the next Restlet in the chain (often a Finder that maps requests to ServerResource classes).

    Key Configuration Options:

    • Port: Use a specific port number. Setting the port to 0 instructs the system to pick an ephemeral port at binding time.
    • Address: An optional IP address or domain name to listen on. If null, it defaults to localhost.
    • Next Restlet: The component that handles the request after the server accepts the connection. You can pass a Restlet instance or a Class<? extends ServerResource> which will be automatically wrapped in a Finder.

    Concurrency Note: Instances of Server can be invoked by multiple threads simultaneously and must be treated as thread-safe. Avoid storing non-thread-safe state in member variables.

    // Example: Starting a server on port 8080 that routes to a specific ServerResource class
Server server = new Server(context, Protocol.HTTP, 8080, MyResource.class);
server.start();

  7. Debug Jetty using JMX

    2.6

    To monitor or manage the Jetty server state using JMX (Java Management Extensions), you must manually update the implementation where the server is created (typically in JettyServerHelper).

    1. Activate JMX

    Register an MBeanContainer with the platform MBeanServer and add it to the jettyServer instance:

    2. State Tracking

    Once activated, you can use tools like jconsole to inspect the state of MBeans or execute operations on them directly.

    // Inside JettyServerHelper where the server is created:

// Create an MBeanContainer with the platform MBeanServer.
MBeanContainer mbeanContainer = new MBeanContainer(ManagementFactory.getPlatformMBeanServer());
// Add MBeanContainer to the root component.
jettyServer.addBean(mbeanContainer);

  8. Enable full Jetty logging

    2.6

    To debug Jetty within the Restlet framework, you can increase the logging verbosity to TRACE. Since org.eclipse.jetty:jetty-slf4j-impl is already included in the pom.xml, you can use one of the following two methods:

    Method 1: Programmatic Configuration

    Set the system property at the start of your application:

    Method 2: Configuration File

    Create a jetty-logging.properties file in your classpath with the following content:

    // Method 1: Programmatic
System.setProperty("org.eclipse.jetty.LEVEL", "TRACE");
    // Method 2: jetty-logging.properties
org.eclipse.jetty.LEVEL=TRACE
org.eclipse.jetty.client.LEVEL=TRACE

  9. Initialize a Client for HTTP requests

    2.6

    The Client class acts as a generic connector for making HTTP requests. It uses an underlying RestletHelper provided by the Restlet engine to handle the actual protocol logic.

    To use a Client, you must provide a Context and a list of Protocol objects (e.g., Protocol.HTTP). If no suitable connector helper is found on the classpath for the requested protocol, the client will return a CONNECTOR_ERROR_INTERNAL status.

    Concurrency Note: Instances of Client are thread-safe and can be invoked by multiple threads simultaneously, provided you do not store non-thread-safe state in member variables.

    // Example: Initializing a client for HTTP
Client client = new Client(new Context(), Protocol.HTTP);

  10. Instantiate an Entry

    2.6

    The Entry class provides several constructors depending on your source data:

    ConstructorDescription
    Entry()Creates an empty entry.
    Entry(String entryUri)Fetches and parses an entry from the specified URI via HTTP GET.
    Entry(Client clientDispatcher, String entryUri)Fetches and parses an entry using a specific Client dispatcher.
    Entry(Context context, String entryUri)Fetches and parses an entry using a Context to retrieve the client dispatcher.
    Entry(Representation xmlEntry)Parses an entry from an existing XML Representation.
    Entry(Representation xmlEntry, EntryReader entryReader)Parses an entry from XML using a custom EntryReader.
    // From a URI
Entry entry = new Entry("https://example.com/atom/entry/123");

// From an existing XML Representation
Entry entryFromXml = new Entry(xmlRepresentation);

  11. Use the Entry class to represent Atom feed entries

    2.6

    The org.restlet.ext.atom.Entry class is a data model representing an individual entry in an Atom feed. It extends SaxRepresentation, allowing it to be parsed from or written to XML.

    Note: This class is marked as @Deprecated and is scheduled for removal in a future major release. Use with caution in new projects.

    Key Capabilities

    • Parsing from XML: Create an Entry instance from an existing XML Representation.
    • Fetching from a URI: Instantiate an Entry directly from a web URI (this performs an HTTP GET request).
    • Data Access: Retrieve metadata such as authors, categories, content, links, published date, summary, and title.
    • Serialization: Write the entry back to XML using an XmlWriter.
    // Create an entry from a URI (performs an HTTP GET)
Entry entry = new Entry("http://example.com/feed/entry/1");

// Access data
String title = entry.getTitle().getText();
String id = entry.getId();
Date published = entry.getPublished();

// Access links by relation type
Link selfLink = entry.getLink(Relation.SELF);

  12. Use the Client class for HTTP requests

    2.6

    The Client class is a generic connector used to make HTTP requests. It acts as a wrapper around a RestletHelper provided by the underlying engine.

    Note: This class is marked as @Deprecated and is scheduled for removal in the next 2.7/3.0 release.

    Concurrency: Instances of Client (or its subclasses) are thread-safe and can be invoked by multiple threads simultaneously. However, be cautious when storing state in member variables.

    Advanced Usage: You can access the wrapped RestletHelper instance by retrieving the attribute "org.restlet.client.engine.helper" from the Context object used to initialize the client.

    // Example initialization with a single protocol
Client client = new Client(context, Protocol.HTTP);

// Example initialization with a list of protocols
List<Protocol> protocols = Arrays.asList(Protocol.HTTP, Protocol.HTTPS);
Client client = new Client(context, protocols);

// Example initialization using a protocol name string
Client client = new Client("HTTP");