Skip to main content

Resource Classes

This section describes how to define a top-level REST resource page and deploy it in our microservice. The example is a router page that serves as a jumping off page to child resources.

@Rest(
    path="/*",
    title="My Microservice",
    description="Top-level resources page",
    children={
        HelloWorldResource.class,
        ConfigResource.class,
        LogsResource.class
    }
)
@HtmlDocConfig(
    navlinks={
        "options: servlet:/?method=OPTIONS"
    }
)
public class RootResources extends BasicRestServletGroup {
    // No code!
}

ConfigResource and LogsResource are demo admin resources that live in the unpublished juneau-microservice-examples module (package org.apache.juneau.microservice.examples) rather than in juneau-microservice itself — see Predefined Resource Classes.

When deployed, it looks like this in a browser:

http://localhost:10000

  • The title and description annotations define the titles on the page. These can be globalized using $L{...} variables, or by defining specially-named properties in the properties file for the resource.

  • In this case, the path annotation defines the context root of your application since it was not specified in the manifest or config file. Therefore, this resource is mapped to http://localhost:10000.

  • The children annotation make up the list of child resources. These child resources can be anything that extends from Servlet, although usually they will be subclasses of BasicRestServlet or other resource groups.

If you click the helloWorld link in your application, you'll get a simple hello world message:

http://localhost:10000/helloWorld

...which is generated by this class...

@Rest(
    path="/helloWorld",
    title="Hello World example",
    description="Simplest possible REST resource"
)
public class HelloWorldResource extends BasicRestServlet {

    @RestGet("/*")
    public String sayHello() {
        return "Hello world!";
    }
}

The most-common case for deploying the top-level resource is to expose it as a @Bean Servlet in an application @Configuration class. JettyServerComponent discovers all @Bean Servlet instances at start-up and auto-mounts any whose class is annotated with @Rest at @Rest(path="..."):

public class App {
    public static void main(String[] args) throws Exception {
        Microservice
            .create()
            .args(args)
            .configurations(JettyConfiguration.class, AppConfig.class)
            .build()
            .start()
            .startConsole()
            .join();
    }

    @Configuration
    public static class AppConfig {
        @Bean
        Servlet rootResources() { return new RootResources(); }
    }
}

However, there are multiple ways of deploying top-level resources:

#=======================================================================================================================
# Jetty settings

#=======================================================================================================================
[Jetty]

# Subclasses of RestServlet

servlets = org.apache.juneau.petstore.jetty.RootResources
  • As a configuration variable Jetty/servletMap.
#=======================================================================================================================
# Jetty settings

#=======================================================================================================================
[Jetty]

# Any servlets and their path specs

servletMap =
    {
        '/*': 'org.apache.juneau.petstore.jetty.RootResources'
    }
  • Directly in the jetty.xml file.
<Configure id="ExampleServer" class="org.eclipse.jetty.server.Server">
    ...
    <New id="context" class="org.eclipse.jetty.ee11.servlet.ServletContextHandler">
        <Set name="contextPath">/</Set>
        <Call name="addServlet">
            <Arg>org.apache.juneau.petstore.jetty.RootResources</Arg>
            <Arg>/*</Arg>
        </Call>
        <Set name="sessionHandler">
            <New class="org.eclipse.jetty.ee11.servlet.SessionHandler" />
        </Set>
    </New>
    ...