RootResources

The RootResources class is the main page for the REST microservice. It serves as the jumping-off point for the other resources.

The class hierarchy for this class is:

- {@link oajr.RestServlet} - Contains all the REST servlet logic.
  - {@link oajr.BasicRestServlet} - Defines default serializers and parsers, and OPTIONs page logic.
    - {@link oajr.BasicRestServletGroup} - Specialized subclass for grouping other resources.

Pointing a browser to the resource shows the following:

http://localhost:10000

The RootResources class can also be defined as a servlet in a web.xml file:

<web-app version='2.3'> <servlet> <servlet-name>RootResources</servlet-name> <servlet-class>org.apache.juneau.rest.samples.RootResources</servlet-class> </servlet> <servlet-mapping> <servlet-name>RootResources</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> </web-app>

The RootResources class consists entirely of annotations:

##### RootResources.java

/** * Sample REST resource showing how to implement a "router" resource page. */ @RestResource( path="/", title="Root resources", description="Example of a router resource page.", htmldoc=@HtmlDoc( widgets={ PoweredByApache.class, ContentTypeMenuItem.class, StyleMenuItem.class }, navlinks={ "options: ?method=OPTIONS", "$W{ContentTypeMenuItem}", "$W{StyleMenuItem}", "source: $C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java" }, aside={ "<div style='max-width:400px' class='text'>", " <p>This is an example of a 'router' page that serves as a jumping-off point to child resources.</p>", " <p>Resources can be nested arbitrarily deep through router pages.</p>", " <p>Note the <span class='link'>options</span> link provided that lets you see the generated swagger doc for this page.</p>", " <p>Also note the <span class='link'>sources</span> link on these pages to view the source code for the page.</p>", " <p>All content on pages in the UI are serialized POJOs. In this case, it's a serialized array of beans with 2 properties, 'name' and 'description'.</p>", " <p>Other features (such as this aside) are added through annotations.</p>", "</div>" }, footer="$W{PoweredByApache}" ), properties={ // For testing purposes, we want to use single quotes in all the serializers so it's easier to do simple // String comparisons. // You can apply any of the Serializer/Parser/BeanContext settings this way. @Property(name=SERIALIZER_quoteChar, value="'") }, children={ HelloWorldResource.class, PetStoreResource.class, RequestEchoResource.class, SampleRrpcServlet.class, PhotosResource.class, DtoExamples.class, SqlQueryResource.class, ConfigResource.class, LogsResource.class, DebugResource.class, ShutdownResource.class } ) public class RootResources extends BasicRestServletJenaGroup { // No code! }

The children annotation defines the child resources of this router resource.
These are resources whose paths are direct decendents to the parent resource.

Child resources must be annotated with the {@link oajr.annotation.RestResource#path() @RestResource(path)} annotation to identify the subpath of the child.
Children CAN extend from {@link oajr.BasicRestServlet}, but it is not a requirement.

Child resources can also be defined programmatically by using the {@link oajr.RestContextBuilder#children(Class[])} method.

Note that these router pages can be arbitrarily nested deep. You can define many levels of router pages for arbitrarily hierarchical REST interfaces.

Let's step back and describe what's going on here:
During servlet initialization of the RootResources object, the toolkit looks for the @RestResource(children) annotation.
If it finds it, it instantiates instances of each class and recursively performs servlet initialization on them.
It then associates the child resource with the parent by the name specified by the @RestResource(path) annotation on the child class.
When a request for the child URL (/helloWorld) is received, the RootResources servlet gets the request and sees that the URL remainder matches one of its child resources.
It then forwards the request to the child resource for processing.
The request passed to the child resource is the same as if the child resource had been deployed independently (e.g. path-info, resource-URI, and so forth).