routemaster-module-example ^{^top}

This project requires JVM version of at least 1.7

routemaster-module-example ^{^top}

example module for the routemaster

Quick overview ^{^top}

This module provides an extension point for the routemaster server which can be automatically loaded and registered by placing it in the modules/ directory alongside the routemaster-server.jar. The module provides all dependencies and configuration required to fully load and execute the module.

Download from https://github.com/synapticloop/routemaster-module-example/releases

Within the module, at the root of the jar file will be a file named routemaster-module-example.properties which determines the configuration for the module. The configuration file may be viewed here:

src/main/resources/routemaster-module-example.properties

Furthermore, the in-built configuration can be over-ridden by placing a file named routemaster-module-example.properties in the modules directory along side the jar file which will take precedence when searching for configuration.

The file format and layout is as per the routemaster.properties file for the routemaster server.

Table of Contents ^{^top}

routemaster-module-example
Quick overview
Table of Contents
Creating a new module
Deploying modules
- Step 1
- Step 2
- Step 3
Running the server
Generating the default documentation
Building the Package
- *NIX/Mac OS X
- Windows
Running the Tests

Module Support

This is an example module that offers additional, modular support for synapticloop routemaster.

Routemaster modules can be automatically loaded from the modules directory that can automatically provide:

Handlers
Configuration options
RESTful routes
static routes

Creating a new module ^{^top}

Setup ^{^top}

Download the latest version of the source code, and unzip it into your project working directory.

The structure of the folder is as follows:

build.gradle (the build.gradle file)
gradle
gradlew
gradlew.bat
settings.gradle (the settings file for gradle)
src (the source files directory)

Configuration ^{^top}

File: `build.gradle`

This is the main build file and contains everything to build (and bundle - if required) the module. It can be executed by typing the following:

gradle build

If you are on windows:

gradle.bat build

The build.gradle file contents are:

plugins {
	id 'java'
	id 'eclipse'
	id "maven"
	id "maven-publish"

	id "com.github.ben-manes.versions" version "0.13.0"
	id 'net.saliman.cobertura' version '2.2.6'
	id 'co.riiid.gradle' version '0.4.2'

	id "com.github.johnrengelman.shadow" version "1.2.4"

	id "synapticloop.copyrightr" version "1.1.2"
	id "synapticloop.documentr" version "2.9.0"
}

version = '1.1.0'

//
// ensure that you change the following values
//
group = 'synapticloop'
archivesBaseName = 'routemaster-module-example'
description = """example module for the routemaster"""

sourceCompatibility = 1.7
targetCompatibility = 1.7

repositories {
	mavenLocal()
	mavenCentral()
	jcenter()
}

//
// We create a configuration here which is used to run the shadow jar
//

configurations {
	shadow
}

//
// ensure that the dependencies are up-to-date, you can do this by running
//
//    gradle dependencyUpdates
//
// or as a shortcut (provided there are no clashes)
//
//    gradle dU
//
// this functionality is provided by the plugin:
//    id "com.github.ben-manes.versions" version "0.13.0"
//

dependencies {
	runtime 'synapticloop:routemaster:2.1.0'

	compile 'synapticloop:routemaster:2.1.0'

	// if you need to include any dependencies, then you __MUST__ add them to the
	// 'shadow configuration, e.g. uncomment the following line to include 'templar'
	// shadow 'synapticloop:templar:1.4.4'
}

// the following is the shadow jar plugin configuration which ultimately collects
// all of the dependencies together and puts them into the same jar file for
// deployment

shadowJar {
	classifier = ''
	configurations = [project.configurations.shadow]
}

//
// This will upload the file to github releases section and can be accomplished 
// by running 
//
//    gradle githubRelease
//
// or as a shortcut (provided there are no clashes)
//
//    gradle gR
//
// you __MUST__ provide the following environment key:
//    - GITHUB_TOKEN
//

github {
	owner = group
	repo = archivesBaseName
	if(System.getenv('GITHUB_TOKEN')) {
		token = System.getenv('GITHUB_TOKEN')
	}
	tagName = version
	name = version
	assets = [
		'build/libs/' + archivesBaseName + '-' + version + '.jar',
	]
}

Including dependencies in the module ^{^top}

Within the build.gradle file a shadow configuration is defined. Any dependencies that you wish to include in the final module MUST be listed here.

See the configurations, dependencies and the shadowJat sections in the build.gradle file above.

WARNING: if multiple modules are including different versions of jar dependencies, then the order in which that these will be picked up by the class loader is undefined.

File: `settings.gradle`

You will also want to change the settings.gradle file:

rootProject.name = 'routemaster-module-example'

so that the rootProject.name value matches your project name.

Code ^{^top}

All the code resides in the src/main/java directory, with resources in the src/main/resources directory.

File: `src/main/resources/{archivesBaseName}.properties`

You MUST have a properties file deployed with every module jar or it will not be activated. The name of the properties file is the module name (without any version number - (e.g. {archivesBaseName}.properties - in this example it is routemaster-module-example.properties

The keys and values in the properties file are the same as the default routemaster.properties file. This file has the same standard layout as the default properties file, and may map options, handlers and routes (both RESTful and not).

Some things to note:

All properties defined in the module jar file will over-write any existing properties that are set.

Deploying modules ^{^top}

Step 1 ^{^top}

To deploy the built module, ensure that you have downloaded the latest routemaster server from github routemaster releases (the jar file is the one that has the server classifier - e.g. routemaster-2.0.0-server.jar).

Note: The server version has NO functionality built in - i.e. no routes are defined - instead all functionality must come from the modules. It will still operate successfully, however all the modules must map the routes.

Step 2 ^{^top}

Create a modules directory which is in the same directory that the downloaded file is (your directory listing should look something like the following:

/routemaster-2.0.0-server.jar
/modules/

Step 3 ^{^top}

Place the module (or multiple modules) into the modules directory so that it will look something like the following:

/routemaster-2.0.0-server.jar
/modules/
        /routemaster-module-example-1.0.0.jar

Running the server ^{^top}

now run the server:

java -jar routemaster-2.0.0-server.jar

For the example above, the only routes that are mapped are:

/module/example/
/module/example/*

If you open http://localhost:5474/module/example/

you will see something along the lines of:

Hello from the example module, this page was brought to you by the letter 'H'

Generating the default documentation ^{^top}

Simply run:

gradle --no-daemon documentr

Or you can simply generate your own README.md file.

Building the Package ^{^top}

*NIX/Mac OS X ^{^top}

From the root of the project, simply run

./gradlew build

Windows ^{^top}

./gradlew.bat build

This will compile and assemble the artefacts into the build/libs/ directory.

Note that this may also run tests (if applicable see the Testing notes)

Running the Tests ^{^top}

*NIX/Mac OS X ^{^top}

From the root of the project, simply run

gradle --info test

if you do not have gradle installed, try:

gradlew --info test

Windows ^{^top}

From the root of the project, simply run

gradle --info test

if you do not have gradle installed, try:

./gradlew.bat --info test

The --info switch will also output logging for the tests

Dependencies - Gradle ^{^top}

dependencies {
	runtime(group: 'synapticloop', name: 'routemaster-module-example', version: '1.1.0', ext: 'jar')

	compile(group: 'synapticloop', name: 'routemaster-module-example', version: '1.1.0', ext: 'jar')
}

or, more simply for versions of gradle greater than 2.1

dependencies {
	runtime 'synapticloop:routemaster-module-example:1.1.0'

	compile 'synapticloop:routemaster-module-example:1.1.0'
}

Dependencies - Maven ^{^top}

<dependency>
	<groupId>synapticloop</groupId>
	<artifactId>routemaster-module-example</artifactId>
	<version>1.1.0</version>
	<type>jar</type>
</dependency>

Dependencies - Downloads ^{^top}

You will also need to download the following dependencies:

cobertura dependencies

net.sourceforge.cobertura:cobertura:2.0.3: (It may be available on one of: bintray mvn central)

compile dependencies

synapticloop:routemaster:2.1.0: (It may be available on one of: bintray mvn central)

runtime dependencies

synapticloop:routemaster:2.1.0: (It may be available on one of: bintray mvn central)

NOTE: You may need to download any dependencies of the above dependencies in turn (i.e. the transitive dependencies)

--

This README.md file was hand-crafted with care utilising synapticlooptemplar->documentr

--

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

routemaster-module-example ^{^top}

Quick overview ^{^top}

Table of Contents ^{^top}

Module Support

Creating a new module ^{^top}

Setup ^{^top}

Configuration ^{^top}

File: `build.gradle`

Including dependencies in the module ^{^top}

File: `settings.gradle`

Code ^{^top}

File: `src/main/resources/{archivesBaseName}.properties`

Deploying modules ^{^top}

Step 1 ^{^top}

Step 2 ^{^top}

Step 3 ^{^top}

Running the server ^{^top}

Generating the default documentation ^{^top}

Building the Package ^{^top}

*NIX/Mac OS X ^{^top}

Windows ^{^top}

Running the Tests ^{^top}

*NIX/Mac OS X ^{^top}

Windows ^{^top}

Dependencies - Gradle ^{^top}

Dependencies - Maven ^{^top}

Dependencies - Downloads ^{^top}

cobertura dependencies

compile dependencies

runtime dependencies

About

Releases 3

Packages

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
gradle/wrapper		gradle/wrapper
src		src
.gitignore		.gitignore
README.md		README.md
build.gradle		build.gradle
documentr.json		documentr.json
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle		settings.gradle

synapticloop/routemaster-module-example

Folders and files

Latest commit

History

Repository files navigation

routemaster-module-example top

Quick overview top

Table of Contents top

Module Support

Creating a new module top

Setup top

Configuration top

File: build.gradle

Including dependencies in the module top

File: settings.gradle

Code top

File: src/main/resources/{archivesBaseName}.properties

Deploying modules top

Step 1 top

Step 2 top

Step 3 top

Running the server top

Generating the default documentation top

Building the Package top

*NIX/Mac OS X top

Windows top

Running the Tests top

*NIX/Mac OS X top

Windows top

Dependencies - Gradle top

Dependencies - Maven top

Dependencies - Downloads top

cobertura dependencies

compile dependencies

runtime dependencies

About

Topics

Resources

Stars

Watchers

Forks

Releases 3

Packages 0

Languages

routemaster-module-example ^{^top}

Quick overview ^{^top}

Table of Contents ^{^top}

Creating a new module ^{^top}

Setup ^{^top}

Configuration ^{^top}

File: `build.gradle`

Including dependencies in the module ^{^top}

File: `settings.gradle`

Code ^{^top}

File: `src/main/resources/{archivesBaseName}.properties`

Deploying modules ^{^top}

Step 1 ^{^top}

Step 2 ^{^top}

Step 3 ^{^top}

Running the server ^{^top}

Generating the default documentation ^{^top}

Building the Package ^{^top}

*NIX/Mac OS X ^{^top}

Windows ^{^top}

Running the Tests ^{^top}

*NIX/Mac OS X ^{^top}

Windows ^{^top}

Dependencies - Gradle ^{^top}

Dependencies - Maven ^{^top}

Dependencies - Downloads ^{^top}

Packages