Configuration

All configuration of the server is done through the routemaster.properties file, a copy of the example configuration is below.

#
# All lines that start with the '#' symbol will be ignored.
#

#
# These are the current options that are available, namely the location of the
# 404, and 500 error pages
#
option.error.500=/error/500.html
option.error.404=/error/404.html

#
# What index files are registered - these are the files which will be search for
# in the requested directory if no specific file is requested
#
option.indexfiles=index.html.templar,index.html,index.htm

#
# If you wish to define a route, start the property name with a 'route.' and it
# will be bound to the defined path.
#
# routes __must__ extend
#     synapticloop.nanohttpd.router.Routable

route./*=synapticloop.nanohttpd.servant.ClasspathFileServant

# This route will list all of the handlers
route./handlers/=synapticloop.nanohttpd.example.servant.HandlerTemplarServant

#
# If you wish to define a restful route, start the property name with a 'rest.'
# and it will be bound to the defined path and pass through any defined
# parameters as a hashmap
#
# rest routes __must__ extend
#     synapticloop.nanohttpd.router.RestRoutable

rest./rest/%method%/=synapticloop.nanohttpd.example.servant.RouteMasterRestTemplarServant

# This is a simple rest servant that shows the various http methods being called
# with mapped and unmapped parameters.  Any parameters that form part of the
# uri after the /%mapped%/ mapping will be passed through wholly as a string
# of 'unmapped'
#
# e.g.:
#  public Response doGet(File rootDir, IHTTPSession httpSession, HashMap restParams, String unmappedParams)
#
# rest routes __must__ extend
#     synapticloop.nanohttpd.router.RestRoutable

rest./simple/%mapped%/=synapticloop.nanohttpd.example.servant.SimpleRestServant

# This is a simple rest servant that lists the mimetypes that are registered
# with no mapped or unmapped parameters.  Any parameters that form part of the
# uri after the /%mapped%/ mapping will be passed through wholly as a string
# of 'unmapped', however they will not be picked up.
#
# e.g.:
#  public Response doGet(File rootDir, IHTTPSession httpSession, HashMap restParams, String unmappedParams)
#
# rest routes __must__ extend
#     synapticloop.nanohttpd.router.RestRoutable

rest./mimetypes/=synapticloop.nanohttpd.example.servant.MimeTypesRestServant

# Now for some handlers - this is for the templar handle (bound to *.templar)

handler.templar=synapticloop.nanohttpd.handler.TemplarHandler

Options

The options section adds in the locations of the error files using the key option.error.<http_status_code>.

Error code files

In the example properties file above, two error pages are defined:


option.error.500=/error/500.html
option.error.404=/error/404.html

For any of the error codes that are returned by routemaster, if they are defined within this file, then the contents of the referenced files sill be returned.

The referenced locations for the file can reside wither within the classpath, or on the file system.

index files

The key:

option.indexfiles=index.html,index.htm

is a comma separated list of files that will be served if a directory is requested. For example, when a user browses to the http://localhost:5474/ page, the router will look first for a index.html file in the directory, then it will look for a index.htm file in the directory.

Simple Routes

All simple routes MUST start with a key of route.

Simple routes do not have URL part parameters mapped and passed through to the underlying implementation.

for the key:

route./*=synapticloop.nanohttpd.servant.StaticFileServant

All routes that start with / will invoke the StaticFileServant which which serve up the routes. See the routing section for information on how routemaster determines which class to invoke.

If you only wanted to map a route to the root directory of the site, then you could use the following:

route./=synapticloop.nanohttpd.servant.StaticFileServant

RESTful Routes

All RESTful routes MUST start with a key of rest.

RESTful routes simplifies the coding of RESTful web servers by providing the boilerplate code for all methods. By default any HTTP method that is not over-ridden will return a 405 method not allowed response code.

Additionally, the RESTful router allows mapping of parameters within the URL to specific variables, which are then passed through to the implementing class.

For the key:

rest./simple/%mapped%/=synapticloop.nanohttpd.example.servant.SimpleRestServant

The route is set as /simple/%mapped%/. When a user GETs the URL the appropriate method is invoked. E.g.:

  • /simple/hello/ will invoke the SimpleRestServant and pass through a key value pair of mapped:hello
  • /simple/goodbye/ will invoke the SimpleRestServant and pass through a key value pair of mapped:goodbye

The key of mapped is used for illustrative purposes only, and may be any value. For example, you could define a route of:

rest./user/%organisation%/%id_user%/=synapticloop.nanohttpd.example.servant.UserServant

and when invoked through http://localhost:5474/user/synapticloop/25/, would invoke the UserServant class and pass through mapped parameters organisation:synapticloop, and id_user:25

Handlers

To register handlers for the routemaster, the key must start with handler then the extension to which this should be bound.

handler.templar=synapticloop.nanohttpd.handler.TemplarHandler
NOTE You MUST have a route defined in order for the handler to work.
route./*=synapticloop.nanohttpd.servant.ClasspathFileServant

handler.xyz=synapticloop.nanohttpd.example.handler.XyzHandler