Minnal Core

Container Configuration

Minnal’s configuration follows a composite pattern. Routes inherit from a Resource, Resources inherit from an Application and Applications inherit from Container. Minnal abstracts out a bunch of configuration parameters at container level and every component inherits them from their parent.

The configuration is loaded from a container.yml file located under META-INF/ folder in the classpath

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# The name of the container
name: My Container

# The base path to use for the routes from all the applications
basePath: /

# Http server configuration
server:
  connectors:
    - port: 8080
      scheme: http

# The default http media type that this container would support. Can be overridden by applications
defaultMediaType: application/json

# The serializers to use for the supported media types
serializers:
  application/json:
    class: org.minnal.core.serializer.DefaultJsonSerializer

# The mount points for the applications. If you just have one application in the container,
# you can skip this configuration. Defaults to the path '/'
mounts:
  com.shopping.cart.ShoppingCartApplication: /

Configuring SSL

Enabling https is quite similar to http, just that ssl needs to be configured. Create a https connector and configure ssl,

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Http server configuration
server:
  connectors:
    - port: 8080
      scheme: http
     - port: 8443
      scheme: https
      ssl:
        keyStoreFile: /Users/ganeshs/keystore.jks
        keyStorePassword: password
        keyPassword: secret

Mounting applications to the container

To mount an application to the container, you will have add the application class to the SPI of org.minnal.core.Application. The container loads all the applications from the SPI file and mounts them as configured in the container.yml. Create a file org.minnal.core.Application under META-INF/services/ folder and the list of applications you want to add to the container,

1

com.example.shopping.cart.ShoppingCartApplication

Application Configuration

Application inherits the configuration parameters from container. For instance, if you haven’t set any serializers for json content type, it will get it from container. You can override it by explicitly specifying in the ApplicationConfiguration. Minnal looks for the application configuration under META-INF/ folder in the classpath. Be sure to name the file as lowercased application name. For instance if your application class name is ShoppingCartApplication, then the application config file name should be shoppingcart.yml. Bare minimum, the application config requires a name to be defined

1
2

# The name of the application
name: shopping_cart

Database Configuration

Minnal recommends you to use JPA in your persistence layer but the database configuration is generic enough to use any library in your persistence layer

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

db:
  driverClass: com.mysql.jdbc.Driver
  url: jdbc:mysql://localhost/facilities
  username: root
  providerProperties:
    hibernate.ejb.naming_strategy: org.hibernate.cfg.ImprovedNamingStrategy
    hibernate.show_sql: true
    hibernate.format_sql: false
    hibernate.current_session_context_class: thread
    hibernate.dialect: org.hibernate.dialect.MySQLDialect
  packagesToScan:
    - com.ekl.facilities

Minnal uses c3p0 for connection pooling.

Resource Configuration

By default minnal inherits the application configuration parameters in to the resource configuration. In most cases you won’t have a need to customize these properties. But say if you want to accept the text/csv which is not the default content type specified by the application, you can customize the resource configuration by just pass on an instance of resource configuration to addResource method.

1
2
3
4
5
6

@Override
protected void defineResources() {
  ResourceConfiguration configuration = new ResourceConfiguration("example resource");
  configuration.addSerializer(MediaType.CSV_UTF_8, csvSerializer);
  addResource(ExmapleResource.class, configuration);
}

Route Configuration

By default minnal inherits the resource configuration parameters in to the route configuration. You can customize the route configuration as below,

1
2
3
4
5
6
7
8

@Override
protected void defineRoutes() {
  RouteConfiguration configuration = new RouteConfiguration("some name");
  configuration.addSerializer(MediaType.CSV_UTF_8, csvSerializer);

  // Map ExampleResource.readExample method to the route GET /examples/{id}
  resource(ExampleResource.class).builder("/examples/{id}").action(HttpMethod.GET, "readExample").using(configuration);
}

Add Filters to Application

You can add filters to the application in the addFilters() method

1
2
3
4
5
6

public class ExampleApplication extends Application<ExampleConfiguration> {
  @Override
  protected void addFilters() {
    addFilter(new MyFilter());
  }
}

Mapping Exceptions

You can map your exceptions to an application exception. You have to override the method mapExceptions() in the application class to do this

1
2
3
4
5
6
7

public class ExampleApplication extends Application<ExampleConfiguration> {
  @Override
  protected void mapExceptions() {
    addExceptionMapping(PersistenceException.class, BadRequestException.class);
    super.mapExceptions();
  }
}

Register Plugin to Application

You can register a plugin in the registerPlugins() method of the application class

1
2
3
4
5
6
7

public class ExampleApplication extends Application<ExampleConfiguration> {

  @Override
  protected void registerPlugins() {
    registerPlugin(new MyPlugin());
  }
}

Add Bundle to Container

To add a bundle to the container, you will have to add the bundle class to the SPI of org.minnal.core.Bundle under META-INF/ folder,

1

com.example.MyBundle