org.apache.juneau.microservice

Class RestMicroservice

java.lang.Object

org.apache.juneau.microservice.Microservice

org.apache.juneau.microservice.RestMicroservice

All Implemented Interfaces:

ConfigEventListener

public class RestMicroservice
extends Microservice

Entry point for Juneau microservice that implements a REST interface using Jetty on a single port.

Jetty Server Details

The Jetty server is created by the createServer() method and started with the startServer() method. These methods can be overridden to provided customized behavior.

Defining REST Resources

Top-level REST resources are defined in the jetty.xml file as normal servlets.

Logging

Logging is initialized by the Microservice.initLogging() method. This method can be overridden to provide customized logging behavior.

Lifecycle Listener Methods

Subclasses can optionally implement the following event listener methods:

• Microservice.onStart() - Gets executed before start().
• Microservice.onStop() - Gets executed before stop().
• onCreateServer() - Gets executed before createServer().
• onStartServer() - Gets executed before startServer().
• onPostStartServer() - Gets executed after startServer().
• onStopServer() - Gets executed before stop().
• onPostStopServer() - Gets executed after stop().

Constructor Summary

Constructors

Constructor and Description
RestMicroservice(String... args) Constructor.

Method Summary

Modifier and Type	Method and Description
RestMicroservice	addServlet(javax.servlet.Servlet servlet, String pathSpec) Adds an arbitrary servlet to this microservice.
RestMicroservice	addServletAttribute(String name, Object value) Adds a servlet attribute to the Jetty server.
protected org.eclipse.jetty.server.Server	createServer() Method used to create (but not start) an instance of a Jetty server.
String	getContextPath() Returns the context path that this microservice is using.
String	getHostName() Returns the hostname of this microservice.
static RestMicroservice	getInstance() Returns the Microservice instance.
int	getPort() Returns the port that this microservice started up on.
String	getProtocol() Returns whether this microservice is using "http" or "https".
org.eclipse.jetty.server.Server	getServer() Returns the underlying Jetty server.
URI	getURI() Returns the URI where this microservice is listening on.
RestMicroservice	join() Joins the application with the current thread.
static void	main(String[] args) Main method.
void	onConfigChange(List<ConfigEvent> events) Called when Config.commit() is called on the config file.
protected void	onCreateServer() Called before createServer() is called.
protected void	onPostStartServer() Called after the Jetty server is started.
protected void	onPostStopServer() Called after the Jetty server is stopped.
protected void	onStartServer() Called before startServer() is called.
protected void	onStopServer() Called before the Jetty server is stopped.
RestMicroservice	setConfig(String cfPath, boolean create) Specifies the path of the config file for this microservice.
RestMicroservice	setJettyXml(Object jettyXml) Sets the jetty.xml used to configure the Jetty server.
RestMicroservice	setManifestContents(String... contents) Convenience method for specifying the manifest contents directly.
RestMicroservice	start() Start this application.
protected int	startServer() Method used to start the Jetty server created by createServer().
RestMicroservice	stop() Stop this application.

Methods inherited from class org.apache.juneau.microservice.Microservice

createConsoleCommands, createVarResolver, err, getArgs, getConfig, getConsoleCommands, getConsoleReader, getConsoleWriter, getLogger, getManifest, getVarResolver, initLogging, kill, log, onStart, onStop, out, setArgs, setConfig, setManifest, setManifest, setManifest, setManifest, startConsole

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RestMicroservice

public RestMicroservice(String... args)
                 throws Exception

Constructor.

Parameters:

args - Command line arguments.

Throws:

Exception

Method Detail

getInstance

public static RestMicroservice getInstance()

Returns the Microservice instance.

This method only works if there's only one Microservice instance in a JVM. Otherwise, it's just overwritten by the last call to RestMicroservice(String...).

Returns:

The Microservice instance, or null if there isn't one.

main

public static void main(String[] args)
                 throws Exception

Main method.

Subclasses must also implement this method!

Parameters:

args - Command line arguments.

Throws:

Exception

start

public RestMicroservice start()
                       throws Exception

Description copied from class: Microservice

Start this application.

Default implementation simply calls Microservice.onStart().

Overridden methods MUST call this method FIRST so that the Microservice.onStart() method is called.

Overrides:

start in class Microservice

Returns:

This object (for method chaining).

Throws:

Exception

join

public RestMicroservice join()
                      throws Exception

Description copied from class: Microservice

Joins the application with the current thread.

Default implementation is a no-op.

Overrides:

join in class Microservice

Returns:

This object (for method chaining).

Throws:

Exception

stop

public RestMicroservice stop()

Description copied from class: Microservice

Stop this application.

Default implementation simply calls Microservice.onStop().

Overridden methods MUST call this method LAST so that the Microservice.onStop() method is called.

Overrides:

stop in class Microservice

Returns:

This object (for method chaining).

getPort

public int getPort()

Returns the port that this microservice started up on.

The value is determined by looking at the Server/Connectors[ServerConnector]/port value in the Jetty configuration.

Returns:

The port that this microservice started up on.

getContextPath

public String getContextPath()

Returns the context path that this microservice is using.

The value is determined by looking at the Server/Handlers[ServletContextHandler]/contextPath value in the Jetty configuration.

Returns:

The context path that this microservice is using.

getProtocol

public String getProtocol()

Returns whether this microservice is using "http" or "https".

The value is determined by looking for the existence of an SSL Connection Factorie by looking for the Server/Connectors[ServerConnector]/ConnectionFactories[SslConnectionFactory] value in the Jetty configuration.

Returns:

Whether this microservice is using "http" or "https".

getHostName

public String getHostName()

Returns the hostname of this microservice.

Simply uses InetAddress.getLocalHost().getHostName().

Returns:

The hostname of this microservice.

getURI

public URI getURI()

Returns the URI where this microservice is listening on.

Returns:

The URI where this microservice is listening on.

createServer

protected org.eclipse.jetty.server.Server createServer()
                                                throws Exception

Method used to create (but not start) an instance of a Jetty server.

Subclasses can override this method to customize the Jetty server before it is started.

The default implementation is configured by the following values in the config file if a jetty.xml is not specified via a REST/jettyXml setting:

#================================================================================ # Jetty settings #================================================================================ [Jetty] # Path of the jetty.xml file used to configure the Jetty server. config = jetty.xml # Resolve Juneau variables in the jetty.xml file. resolveVars = true # Port to use for the jetty server. # You can specify multiple ports. The first available will be used. '0' indicates to try a random port. # The resulting available port gets set as the system property "availablePort" which can be referenced in the # jetty.xml file as "$S{availablePort}" (assuming resolveVars is enabled). port = 10000,0,0,0

Returns:

The newly-created server.

Throws:

Exception

addServlet

public RestMicroservice addServlet(javax.servlet.Servlet servlet,
                                   String pathSpec)

Adds an arbitrary servlet to this microservice.

Parameters:

servlet - The servlet instance.

pathSpec - The context path of the servlet.

Returns:

This object (for method chaining).

Throws:

RuntimeException - if createServer() has not previously been called.

addServletAttribute

public RestMicroservice addServletAttribute(String name,
                                            Object value)

Adds a servlet attribute to the Jetty server.

Parameters:

name - The server attribute name.

value - The context path of the servlet.

Returns:

This object (for method chaining).

Throws:

RuntimeException - if createServer() has not previously been called.

getServer

public org.eclipse.jetty.server.Server getServer()

Returns the underlying Jetty server.

Returns:

The underlying Jetty server, or null if createServer() has not yet been called.

startServer

protected int startServer()
                   throws Exception

Method used to start the Jetty server created by createServer().

Subclasses can override this method to customize server startup.

Returns:

The port that this server started on.

Throws:

Exception

onConfigChange

public void onConfigChange(List<ConfigEvent> events)

Called when Config.commit() is called on the config file.

The default behavior is configured by the following value in the config file:

# What to do when the config file is saved. # Possible values: # NOTHING - Don't do anything. (default) # RESTART_SERVER - Restart the Jetty server. # RESTART_SERVICE - Shutdown and exit with code '3'. saveConfigAction = RESTART_SERVER

Specified by:

onConfigChange in interface ConfigEventListener

Overrides:

onConfigChange in class Microservice

Parameters:

events - The list of changes in the config file.

setJettyXml

public RestMicroservice setJettyXml(Object jettyXml)

Sets the jetty.xml used to configure the Jetty server.

Parameters:

jettyXml - The jetty.xml.
Can be any of the following:

• A File representing the location on the file system.
• An InputStream containing the contents of the file.
• A String representing the file system path.

Returns:

This object (for method chaining).

onCreateServer

protected void onCreateServer()

Called before createServer() is called.

Subclasses can override this method to hook into the lifecycle of this application.

onStartServer

protected void onStartServer()

Called before startServer() is called.

Subclasses can override this method to hook into the lifecycle of this application.

onPostStartServer

protected void onPostStartServer()

Called after the Jetty server is started.

Subclasses can override this method to hook into the lifecycle of this application.

onStopServer

protected void onStopServer()

Called before the Jetty server is stopped.

Subclasses can override this method to hook into the lifecycle of this application.

onPostStopServer

protected void onPostStopServer()

Called after the Jetty server is stopped.

Subclasses can override this method to hook into the lifecycle of this application.

setConfig

public RestMicroservice setConfig(String cfPath,
                                  boolean create)
                           throws IOException

Description copied from class: Microservice

Specifies the path of the config file for this microservice.

If you do not specify the config file location, we attempt to resolve it through the following methods:

1. The first argument in the command line arguments passed in through the constructor.
2. The value of the Main-Config entry in the manifest file.
3. A config file in the same location and with the same name as the executable jar file. (e.g. "java -jar myjar.jar" will look for "myjar.cfg").

If this path does not exist, a FileNotFoundException will be thrown from the Microservice.start() command.

Overrides:

setConfig in class Microservice

Parameters:

cfPath - The absolute or relative path of the config file.

create - Create the file if it doesn't exist.

Returns:

This object (for method chaining).

Throws:

IOException - If config file does not exist at the specified location or could not be read or created.

setManifestContents

public RestMicroservice setManifestContents(String... contents)
                                     throws IOException

Description copied from class: Microservice

Convenience method for specifying the manifest contents directly.

Overrides:

setManifestContents in class Microservice

Parameters:

contents - The lines in the manifest file.

Returns:

This object (for method chaining).

Throws:

IOException