By convention Ninja will look for a configuration file at conf/application.conf.
application.conf is a simple properties file with keys and values. “#” is a comment.
# an arbitrary comment application.name=Ninja demo application application.cookie.prefix=NINJA
Like any other Ninja file it is encoded in UTF-8. Make sure your editor reads and saves the file in the correct encoding.
Ninja properties can do much more than traditional Java properties. For instance it is possible to reference other properties by their name and combine them.
serverName=myserver.com
serverPort=80
fullServerName=${serverName}:${serverPort}
fullServerName references the previously set values of the keys and will return myserver.com:80.
Inside your application there are two basic ways to access the properties.
First way is to use NinjaProperties.get(…). You have to inject NinjaProperties first, then you
can use all sorts of methods to retrieve properties.
@Inject
NinjaProperties ninjaProperties;
public void myMethod() {
String value = ninjaProperties.get("fullServerName")
... do even more...
}
The second way to get properties is to inject them via @Named(“fullServerName”).
/** An arbitrary constructor */
@Inject
ApplicationController(@Named("fullServerName") String fullServerName) {
... do something ...
}
By the way. And this is really important: Properties are read and managed by the excellent Apache Configurations library. Please refer to their manual for even more information on advanced usage.
Ninja uses three predefined modes (test, dev
and prod as defined in NinjaConstant.java).
If no mode is set explicitly Ninja will use the prod mode. That means if you
deploy Ninja via a war file to an arbitrary servlet container Ninja will use the prod
mode.
Ninja's SuperDevMode will set the mode to dev. And Ninja's
testcases will use mode test by default.
You can set the
modes by setting the Java system property ninja.mode.
On the command line: > java -Dninja.mode=dev Or programmatically: System.setProperty(NinjaConstant.MODE_KEY_NAME, NinjaConstant.MODE_DEV)
Make sure that you set the system property early so that Ninja knows its mode from the very beginning.
These modes are handy if you want to define different properties for different environments. You may want to use database1 when running tests and database2 when developing and database3 when running in production.
Ninja supports that use case by using a mode prefix prior to your property key.
database.name=database_production # will be used when no mode is set (or prod) %prod.database.name=database_prod # will be used when running in prod mode %dev.database.name=database_dev # will be used when running in dev mode %test.database.name=database_test # will be used when running in test mode
The convention is to use a “%” and the name of the mode followed by “.”.
As of version 5.2.3, Ninja supports basic HTTPS (SSL) in both standalone and SuperDevMode. While other methods of handling SSL in production (e.g. nginx) are highly recommended, its convenient to use Ninja's builtin support during development, testing, or light production use.
Ninja ships with a self-signed SSL certificate that is configured by default
in either dev or test modes. To enable SSL in either dev or test mode
you'll simply need to set the port you'd like to start an HTTPS server on.
ninja.ssl.port=8443
This can be accomplished by either adding this to your conf/application.conf
configuration file or on the command line when you run Ninja's maven plugin
mvn ninja:run -Dninja.ssl.port=8443
Ninja supports running both HTTP and HTTPS connectors at the same time. If you'd
like to only run HTTPS, simply set ninja.port to -1 to disable it.
ninja.port=-1 # disable clear text http connector ninja.ssl.port=8443 # enable ssl https connector
The SSL keystore and truststore values can be configured as well. The uri values
may either be a classpath resource in the format classpath:resourceName or
any other valid Java URL value since under-the-hood URL.openStream() is used.
Please note that in dev and test mode the default keystore is classpath:/ninja/standalone/ninja-development.keystore
and the default truststore is classpath:/ninja/standalone/ninja-development.truststore
ninja.ssl.keystore.uri=file:///var/etc/mysite.keystore ninja.ssl.keystore.password=changeit ninja.ssl.truststore.uri=file:///var/etc/mysite.truststore ninja.ssl.truststore.password=changeit
As of version 4.0.7, Ninja features a new diagnostic extension to dev mode where
detailed diagnostic error pages are returned from ninja.NinjaDefault
rather than the typical Result which pulls a template from system/views.
For example, in versions prior to 4.0.7, if your controller class method threw
an Exception then the default behavior of ninja.NinjaDefault
was to catch it in the onException method and return a Result using
the template views/system/500internalServerError.ftl.html. The
default system views are basic and more intended for use in production than
during development.
As of version 4.0.7, the default behavior of all the methods in
ninja.NinjaDefault are to first check if dev mode is on and if
NinjaProperties.areDiagnosticsEnabled() is true. If both are true
then a Result is returned with the renderable set to a
DiagnosticError instance. Since DiagnosticError
implements Renderable – it knows how to render itself to the output
stream and it will bypass the TemplateEngine.
Diagnostic mode is disabled automatically in PROD/TEST modes, but it can also be
disabled in DEV mode. Simply add the following to your application.conf:
application.diagnostics=false
If you provide your own conf.Ninja and extend ninja.NinjaDefault, then you will likely lose diagnostic mode for the particular methods you override. You can retain the feature, by calling the super method and conditionally returning its result, rather than your own.
public class Ninja extends NinjaDefault {
@Override
public Result getInternalServerErrorResult(Context context, Exception exception) {
if (isDiagnosticsEnabled()) {
return super.getInternalServerErrorResult(context, exception);
}
// your impl only active in test/prod or dev (with diagnostic disabled)
}
}
If you'd like to keep all Java code in specific package you can define
application.modules.package=com.someorganinization.somepackage
In this case you must put your Routes at
com.someorganization.somepackage.conf.Routes.java
and Guice application configuration modules at
com.someorganization.somepackage.conf.Module.java
com.someorganization.somepackage.conf.ServletModule.java
accordingly.
When running on a server you may want to use a completely different configuration. This can be accomplished by setting a Java system property:
java -Dninja.external.configuration=conf/production.conf
This tells Ninja to load conf/production.conf. It will also load conf/application.conf as usual, but values in conf/production.conf will overwrite values in conf/application.conf.
That way you can manage a production configuration separately from your project. You may want to do this for instance when your server secret should only be available to a certain set of people and not the world. Or if your cloud hoster uses a completely different configuration from prod, test or dev.
Ninja tries to load the file specified in ninja.external.configuration
from several locations:
It tries to load in the following order:
Ninja uses the excellent Apache Configurations library to do the loading. Please refer to their manual for more information.
As of Ninja v6.1.1, system properties can override any configuration key set
with your standard conf/application.conf or external configuration file. For
example, if you have a key db.connection.password set to mypass in conf/production.conf,
then you can override it via a system property to otherpass at runtime like so:
java -Dninja.external.configuration=conf/production.conf -Ddb.connection.password=otherpass
Prefixed system properties are honored as well. Using the previous example, if you only
wanted the property to take effect while in test mode you can do this:
java -Dninja.external.configuration=conf/production.conf -D%test.db.connection.password=otherpass
By default Ninja does not reload your external configuration. However for some installations it may be very useful to hot-reload this config instead of restarting your application.
java -Dninja.external.reload=true -Dninja.external.configuration=conf/production.conf
This tells Ninja to reload your configuration if it is modified during runtime.
You can reference system properties inside your configuration files by using the default apache commons configuration syntax:
%prod.db.connection.password=${env:DB_PASSWORD}
That's especially handy when it comes to production credentials that should not be known inside your application code.
You can disable the Ninja logo in startup logs with the following property:
ninja.splash.display=false
You can also replace it with a custom logo by placing an ascii file in ninja/logo.txt.
This file should contain at least one {} placeholder, which will be replaced by the ninja version.