Fork me on GitHub

The anatomy of a Ninja application

Intro

Ninja does a lot of things via convention over configuration. If things are in the right place it will automatically work.

For instance the routes for your application should always at conf/Routes.java. And HTML views always map to a certain controller method via their directory structure.

The conventions are explained in detail in the later sections of the documentation.

An example project

The following tree shows an example project with some explanations what is going on. The project is a comprehensive project with database access via JPA, database migrations and advanced features like filters and argument extractors.

├── pom.xml                                     // Instructions about dependencies and the build (Maven)
└── src
    ├── main
    │   ├── java
    │   │   ├── META-INF
    │   │   │   └── persistence.xml             // Contains informations how to access databases via JPA
    │   │   ├── assets                          // Static assets of your application
    │   │   │   └── css
    │   │   │       └── custom.css
    │   │   ├── conf 
    │   │   │   ├── Module.java                 // Dependency injection definitions via Guice (Optional) 
    │   │   │   ├── Routes.java                 // Contains all routes of your application in one location
    │   │   │   ├── ServletModule.java          // Integration of arbitrary servlet filters and mappings (Optional)
    │   │   │   ├── StartupActions.java         // Customization of application startup (Optional)
    │   │   │   ├── application.conf            // Configuration for test dev and production mode
    │   │   │   ├── messages.properties         // 18n messages
    │   │   │   └── messages_de.properties
    │   │   ├── controllers                     // Controllers will handle the actual request and do something
    │   │   │   ├── ApiController.java
    │   │   │   ├── ApplicationController.java
    │   │   │   ├── ArticleController.java
    │   │   │   └── LoginLogoutController.java
    │   │   ├── dao                             // Database access via DAO objects and not in the controller
    │   │   │   ├── ArticleDao.java
    │   │   │   ├── SetupDao.java
    │   │   │   └── UserDao.java
    │   │   ├── db                              // Database migrations when dealing with RDBMS (Flyway)
    │   │   │   └── migration
    │   │   │       ├── V1__.sql
    │   │   │       └── V2__.sql
    │   │   ├── ehcache.xml                     // Configuration for ehcache
    │   │   ├── etc
    │   │   │   ├── LoggedInUser.java
    │   │   │   └── LoggedInUserExtractor.java  // Argument extractors for controller methods
    │   │   ├── filters
    │   │   │   └── LoggerFilter.java           // Filter to filter the request in the controller
    │   │   ├── logback.xml                     // Logging configuration via logback / slf4j
    │   │   ├── models                          // Some models that map to your relational database
    │   │   │   ├── Article.java
    │   │   │   ├── ArticleDto.java
    │   │   │   ├── ArticlesDto.java
    │   │   │   └── User.java
    │   │   └── views                           // html views - always map to a controller and a method
    │   │       ├── ApplicationController
    │   │       │   ├── index.ftl.html          // Maps to controller "ApplicationController" and method "index"
    │   │       │   └── setup.ftl.html
    │   │       ├── ArticleController
    │   │       │   ├── articleNew.ftl.html
    │   │       │   └── articleShow.ftl.html
    │   │       ├── LoginLogoutController
    │   │       │   ├── login.ftl.html
    │   │       │   └── logout.ftl.html
    │   │       ├── layout
    │   │       │   ├── defaultLayout.ftl.html
    │   │       │   ├── footer.ftl.html
    │   │       │   └── header.ftl.html
    │   │       └── system                      // Error html views. Can be customized to output custom error pages
    │   │           ├── 403forbidden.ftl.html
    │   │           └── 404notFound.ftl.html
    │   ├── resources
    │   └── webapp
    │       └── WEB-INF
    │           └── web.xml                    // Needed for servlet containers to start up Ninja
    └── test
        ├── java
        │   └── controllers                    // Different tests for your application
        │       ├── ApiControllerDocTest.java
        │       ├── ApiControllerDocTesterTest.java
        │       ├── ApiControllerMockTest.java
        │       ├── ApiControllerTest.java
        │       ├── ApplicationControllerFluentLeniumTest.java
        │       ├── ApplicationControllerTest.java
        │       ├── LoginLogoutControllerTest.java
        │       └── RoutesTest.java
        └── resources
            └── test_for_upload.txt