Ninja Web Framework

Ninja Web Framework Tutorial – Part 1


This is a two part series that will demonstrate the features of Ninja Web Framework and how to build a sample web application using the said framework. In this first part we will understand the motivations behind Ninja and different capabilities it has to offer. The part 2 will focus on building a sample end-to-end web application using the framework API.

There are plenty of web frameworks in the market today. Some of the popular frameworks are Spring MVC, Struts, and other Java based frameworks like Wicket that are widely used to develop business applications on the web. These frameworks are robust and comes with its own set of features and capabilities that makes web application development more convenient and easy. Ninja web framework is one more feather in the hat full of web frameworks. It is a more lightweight framework that simplifies the web development. Ninja was born with the sense of purpose and the primary motivations for creating this web framework was to provide ease of development, build and deployment.

Ninja Goal and Objectives

Some of the goals and objectives behind the making of Ninja are:

  • Create a RESTful style of framework whereby one can access and manipulate a resource through a well-defined URI request.
  • Incorporate the concept of dependency injection to address object dependencies so that developers can only focus on writing business logic and not bother about creating and wiring objects or beans or classes.
  • Making development more easy and fast. The moment developer makes changes to the code, it should get hot deployed on the server.
  • Development based on convention than configuration. This can bring in lot of discipline and organization towards the whole development approach.
  • Create a robust test infrastructure that is easy and fast to test a web application. Ninja strongly advocates unit testing. The test environment must seamlessly integrate with IDE of your choice.
  • Build and deployment should be faster and it should very well align with any Continuous Integration (CI) model.
  • The framework should cater to all kinds of request and response data types that includes JSON and XML apart from the regular HTML type.
  • Provide a clean server side validation framework that validates form fields without writing any explicit validation logic.
  • Support application level security through authentication, authorization and session signing and encryption


Ninja is a framework that is composed of different components or libraries that makes it a more feature rich framework. Ninja is very easy to setup. One can use an existing maven archetype to quickly prototype a small application and then work your way towards creating a more advanced business application. The project created from the maven can also be easily imported into IDE for more interactive development. The application environment related properties are defined in the configuration file named application.conf placed under conf/ folder. Many of the features of Ninja require you to provide configuration details in the said file.

Features of Ninja

The following section covers some of the important features offered by Ninja:

Model View Controller

Ninja like many other web frameworks is based on MVC design pattern. The two routing components viz. Router and Controller routes and process the request respectively. The route defines a mapping between URL request and the associated controller which process the request and returns the appropriate view. Remember, Ninja works through code conventions and therefore the naming conventions of the components and the folder or package structure has to be in line with the framework norms. All the routes are defined in the file placed under conf/ folder. All the controllers must be placed under the package named controllers. All the views are defined under the views/ folder.

Views with Freemarker

Ninja uses Apache Freemarker to templatize the views. Views in Ninja are HTML files with Freemarker conventions like directives. Framework like Freemarker separates view (data) rendering from data building. For more information on Freemarker, you can refer to the documentation available at


Ninja’s SuperDevMode feature allows you to build and deploy the code quickly. It hot deploys the code changes so that there is no need for server restart. SuperDevMode is maven plugin configured with embedded Jetty runtime. You can make use of IDE and Maven to setup the development environment with SuperDevMode.

Argument Extractors

Argument extractors allows you to inject arbitrary values as part of the method parameter using annotation. It could be as simple as injecting a logged in user name as a method parameter. You first write a custom annotation that defines the argument extractor class. The argument extractor class must implement ArgumentExtractor interface parameterized with appropriate data type. You then use that custom annotation by injecting in the controller method parameter to get the appropriate value.

Handling Sessions

Unlike many other web frameworks, Ninja does not attach session to the server. The complete session information is stored on the client side in the browser cookie. This makes Ninja applications scale very well in a distributed environment. Different session related configuration can be set in the application.conf configuration file to manage sessions.

Handling ORM

Ninja makes use of JPA 2.0 for persistence handling and Guice Persist for transaction handling. One can make use of Hibernate-JPA implementation to develop ORM routines. You have to make use of application.conf file under the conf/ folder to define DB settings including user credentials. The JPA settings are provided in the persistence.xml file placed under META-INF/ folder. The model entity class then can make use of JPA annotations to devise ORM mapping.


In Ninja, the session information is stored in the browser cookie and signed by a secret key. The secret key is stored in the application.conf configuration file. Every time the server is started, the new key is generated. Obviously for production use, you want to keep the secret key which is different from the development and stored in a separate configuration file. Ninja can also encrypt the session information by enabling encryption feature in the configuration file. It uses AES/128 algorithm for encryption.


Ninja provides the support for localization. You can build web application based on country and its language. The labels and field names can be specified in the message properties file and the name of the file is suffixed with <>. The languages to be used are defined in the application.conf configuration file. You can use Messages object to get the appropriate localized property in the code. You can make use of i18n function to render messages in the template (html) file.

Handling validation

Ninja supports Bean Validation specification (JSR 303) and therefore one can use annotations on the entity classes to validate fields. This eliminates the need to write any explicit field level validation logic in the code. It mandates using Hibernate Validator framework for implementing the validation feature.


Testing in Ninja is easy and fast. Ninja advocates unit testing through the use of JUnit. Tests can be mocked using Mockito framework. Details about Mockito framework can be found at One can also document test routines while executing the tests using the component NinjaDocTester. You can also automate the tests by writing Selenium tests using FluentLenium framework. More details on FluentLenium can be found at


There are plenty of deployment options with Ninja. You can deploy Ninja application in a standalone mode using the embedded Jetty web container that comes with the distribution. You can make use of Maven Stork plugin to deploy it as a service or daemon job on Linux. Ninja can also be deployed on the cloud. Some of the cloud hosting services supported by Ninja are Google App Engine and Heroku. Still it should be possible to deploy Ninja applications on any cloud provider. Ninja applications scales better in a distributed environment as the sessions are maintained only on the client side.


Ninja supports object caching by way of Memcached (recommended for production use) and EhCache for development environment. Details of caching like the cache provider, user credentials etc. can be configured in the application.conf file. One can use NinjaCache object to perform caching.


The article talked about the goals and objectives behind the making of Ninja. It’s a framework that is very easy to use and apply. It is designed around code conventions than configuration. The article also brushed upon important features offered by Ninja. In part 2 of the article, you will learn how to develop a sample web application using the Ninja framework API.

Rajeev Hathi

Rajeev is a senior Java architect and developer. He has been designing and developing business applications for various companies (both product and services). He is co-author of the book titled 'Apache CXF Web Service Development' and shares his technical knowledge through his blog platform
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Back to top button