Creating a Kikaha maven project

The most common way to configure a Kikaha project is using Apache Maven. Just create a pom.xml file and set kikaha-project as your maven parent project. It will setup up a minimal project containing the kikaha-core API and the kikaha-maven-plugin.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

	<modelVersion>4.0.0</modelVersion>

	<parent>
		<groupId>io.skullabs.kikaha</groupId>
		<artifactId>kikaha-project</artifactId>
		<version>PUT-KIKAHA-VERSION-HERE</version>
	</parent>

	<groupId>sample.app</groupId>
	<version>1.0-SNAPSHOT</version>
	<artifactId>kikaha-app</artifactId>
	<packaging>jar</packaging>

	<properties>
		<!-- enable runnable jar -->
		<config.plugins.jar.enabled>true</config.plugins.jar.enabled>
	</properties>
  
	<dependencies>
		<dependency>
			<groupId>io.skullabs.kikaha</groupId>
			<artifactId>kikaha-core</artifactId>
		</dependency>
		<!-- Configuring a logging library: using JDK defaults -->
		<dependency>
			<groupId>ch.qos.logback</groupId>
			<artifactId>logback-classic</artifactId>
		</dependency>
	</dependencies>
</project>

Since 2.1.0 version Kikaha does not follow the default maven directory structure convention, but they still configurable.The default directories are:

• source - For your routes and another Java classes
• resources - For your resource files ( Server configuration, JPA configuration, template configuration, etc )
• webapp - For your static files or templates.
• tests - For your unit tests
• tests-resources - For your test resources

Kikaha uses SLF4j as its main logging provider. You are allowed to use any SLF4j compliant implementation. At this example, we are using Logback. We encourage you to take a look at the Logging Configuration topic for more details about how to properly configure a logging system for your application.

Running your application

Kikaha has its own maven plugin (kikaha-maven-plugin). You can use it to run your project without the need to deploy it in pre-built environment. As mentioned before, this plugin was already set on kikaha-project so, you don't have to mind about its configuration. You are able to run the server directly from the command line:

# compilation lines were omitted
$ kikaha run-app
:: Loading configurations from: file:/m2/repository/io/skullabs/kikaha/kikaha-core/2.1.0/kikaha-core-2.1.0.jar!/META-INF/defaults.yml
:: Listening for HTTP requests at 0.0.0.0:9000
:: Configuring Undertow options...
::   buffer-size: 1024
:: XNIO version 3.3.6.Final
:: XNIO NIO Implementation Version 3.3.6.Final
:: Application started in 109ms.

Packaging and Installing your application

With Kikaha's Maven Plugin you can also bundle your project into a zip file:

# compilation lines were ommited
$ kikaha build
# running your just built project
$ java -jar output/the-generated-runnable.jar

Configuring your maven project

kikaha-project was designed to be easily configurable. Most of its configurations are changeable through maven properties. There is a lot of properties in which you are able to change kikaha-project's default behavior, but the important ones are listed bellow:

• config.skip.tests: if set to true all tests will be skip. [default: false]
• config.skip.tests.unit: if set to true all unit tests will be skip. [default: false]
• config.skip.tests.integration: if set to true all integration tests will be skip. [default: false]
• config.plugins.jar.enabled: if set to true a fat jar will be created for your project every time you run mvn clean install. [default: false]
• config.plugins.package.enabled: if set to true a zip will be created for your project every time you run mvn clean install. [default: false]

Keep control of your project dependencies

As mentioned before, kikaha-project provides a set of dependencies ready to be imported on your project but only the bellow set of dependencies (both not needed at runtime) are automatically set on your project. These dependencies are useful libraries that will make easier to test unity your source code and avoid repetitive boilerplate codes.

<dependencies>
  <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
  </dependency>
  <dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
  </dependency>
  <dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-core</artifactId>
  </dependency>
</dependencies>

You can get more details about these dependencies at the Architecture Overview topic of this documentation.