Getting started

AppBase : Getting started

An application built on top of app base is normally a web app, though it might run in an embedded Tomcat or in a full app server. This requires:

• including the appbase library, via maven
• a suitable web.xml
• one or more configuration file, pointed to by the web.xml
• optionally an embedded app server

The minibrowse project (a simple RDF browser) provides a complete example.

Maven dependency

To include app base in a project use:

<dependency>
  <groupId>com.epimorphics</groupId>
  <artifactId>appbase</artifactId>
  <version>0.0.5</version>
</dependency>

web.xml

The minimum web.xml entry needs to call the appbase startup and define a configuration file:

<listener>
  <listener-class>com.epimorphics.appbase.core.AppConfig</listener-class>
</listener>

<context-param>
  <param-name>AppConfig.myapp</param-name>
  <!-- Will initialize from first of these it finds -->
  <param-value>{webapp}/WEB-INF/app.conf</param-value>
</context-param>

This defines a single application called "myapp" which is configured from the app.conf file in the WEB-INF area of the war. You can have multiple "app"s within a single war though typically there's just one in which case its name is arbitrary. You can specifiy a set of configuration files (as a comma-separated list) to enable the application to pick up the configuration from a known external directory if it exists and fall-back on a built in configuration if that can't be found.

Most uses will also require velocity support, a single velocity filter can support multiple apps:

<filter>
  <filter-name>VelocityFilter</filter-name>
  <filter-class>com.epimorphics.appbase.webapi.VelocityFilter</filter-class>
</filter>

<filter-mapping>
  <filter-name>VelocityFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

Any request which can't be mapped to a velocity template will fall through so you can also have Jersey endpoints and can fall back to file serving.

Configuration file

The configuration file defines the components that make up the application. Its syntax is explained in Configuration.

Typically there will be a velocity renderer instance, one or more datasources and maybe some velocity library plugins. For example:

# Configure a basic velocity
velocity             = com.epimorphics.appbase.templates.VelocityRender
velocity.templates   = {webapp}/WEB-INF/templates
velocity.root        = /
velocity.production  = false

# Set up a data source
ssource              = com.epimorphics.appbase.data.impl.FileSparqlSource
ssource.fileDir      = load
ssource.textIndex    = default

source = com.epimorphics.appbase.data.WSource
source.source = $ssource

# Set up default prefixes
prefixes             = com.epimorphics.appbase.core.PrefixService
prefixes.prefixFile  = {webapp}/WEB-INF/prefixes.ttl

Server set up

Most app base projects will generate war artefacts that can be deployed to a container like tomcat. For development I've found it easiest to include a main routine which runs an embedded tomcat. This makes it possible to run the application live from eclipse without needing to create the war file or use the maven tomcat plugin. The same is obviously possible with Jetty but using tomcat helps ensure test and deployment environments are the same, it also means you can use tomcat-specific features (like the tomcat CORS support).

To include an embedded tomcat then put this in the pom.xml:

<dependency>
  <groupId>org.apache.tomcat.embed</groupId>
  <artifactId>tomcat-embed-core</artifactId>
  <version>7.0.42</version>
  <scope>provided</scope>
</dependency>
<dependency>
  <groupId>org.apache.tomcat.embed</groupId>
  <artifactId>tomcat-embed-logging-log4j</artifactId>
  <version>7.0.42</version>
  <scope>provided</scope>
</dependency>
<dependency>
  <groupId>org.apache.tomcat.embed</groupId>
  <artifactId>tomcat-embed-jasper</artifactId>
  <version>7.0.42</version>
  <scope>provided</scope>
</dependency>

and add a main method to a suitable class:

public static void main(String[] args) throws Exception {
    String root = "src/main/webapp";

    Tomcat tomcat = new Tomcat();
    tomcat.setPort(8080);

    tomcat.setBaseDir(".");

    String contextPath = "/";

    File rootF = new File(root);
    if (!rootF.exists()) {
        rootF = new File(".");
    }
    if (!rootF.exists()) {
        System.err.println("Can't find root app: " + root);
        System.exit(1);
    }

    tomcat.addWebapp(contextPath,  rootF.getAbsolutePath());
    // Use the following instead if you need to set context configuration for the tomcat
    // org.apache.catalina.Context context = tomcat.addWebapp(contextPath,  rootF.getAbsolutePath());
    //  context.setConfigFile(new URL("file:src/main/webapp/META-INF/context.xml"));

    tomcat.start();
    tomcat.getServer().await();
  }

This runs the embedded tomcat directly off the files in src/main/webapp so any edit (e.g. to a velocity template) is picked up immediately with no need for a server restart.