LDSTechForumWikiProjects

Stack Starter Application Walkthrough

The purpose of this document is to introduce a Java Stack developer to the structure of a project created through the Java Stack Starter.

Basic project structure

A Stack Starter based project follows typical maven project structure. It comes with a parent module and 1 or more sub modules. The project will always have a web sub module. This module creates the war for an application. In the case of a Websphere project an ear project will also be created to package the application into an ear. These 2 modules make up the core of a stack starter web application.

Stack Starter projects also include a deploy project. This project is responsible for creating a zip package that ICS tooling uses to configure and deploy the various environments this application may need to be deployed to (e.g. continuous, qa, stage, prod, etc.). This package will usually combine application server configuration with the primary deployable unit for the target environment (.war for Tomcat and .ear for Websphere).

There are also several optional modules created"

  • A qa module may exist if selected in stack starter. This project is responsible for packaging and executing the functional tests of an application.
  • A wam module may exist if you choose to create a project that uses wam for security. This project holds configuration and plugin definitions for running and managing the Wam Emulator.
  • An api module may also exist if you choose the Web Service project type. This module is responsible for creating interfaces for services that may act as a client library for clients that wish to consume the services you are creating.

Many default maven properties and plugins that control how these modules will operate from a build orchestration standpoint are configured in the parent pom, which includes 2 default profiles:

  • local: used mainly for development. This profile is enabled by default.
  • continuous: used mainly for building as part of a continuous build.

The web module

This module is responsible for creating the guts of your web application. It is configured as a typical maven war project. Source code and Test code go in the typical maven directories. Web resources go in the /src/main/webapp directory.

If spring is used you will find the main spring applicationContext.xml file under the /src/main/resources/META-INF/spring directory. This file is responsible for defining application wide features agnostic of the View technology used. You will find in this file configure items such as:

  • Database and Transaction management configuration using Stack DB Spring
  • Spring Security configuration appropriate to the technology chosen (WAM or LDS Account) using the LDS Account Spring Module.
  • Spring Annotation Scanning Configuration. Scanning by default all standard Spring default annotations except for @Controller.

If you configured your application to have a database and chose to add an example to your application you will see Model objects and Services targeted at managing some simple Example data item.

Spring MVC

Under View Layer if anything other than Manual Configuration is selected stack starter will create a simple web project template based on Interaction Framework (IxF). With some simple project templating that takes advantage of jsp tag files.

If Spring MVC is selected in Starter you will find your Spring MVC configuration file in the src/main/webapp/WEB-INF/{projectName}-servlet.xml file. This file will contain some default Spring MVC configuration. By default Stack Starter will configure Spring MVC utilizing the mvc:default-servlet-handler so that all requests by default will be handled by Spring MVC. This helps to ensure clean restful urls in your MVC development.

By default we also configure Spring annotation scanning to add all @Controller annotated classes to this MVC Context as apposed to the applicationContext.xml file's context.

If you chose to create an example then you will be presented with a simple example application that produces "Example" items.

CXF

If you chose a Web Services project then instead of Spring MVC and typical web artifacts you will have CXF pre-configured. Although CXF configuration can be done the conventional way we have decided instead to slightly customize our CXF default configuration. We have created the StackCXFServlet that extends Spring's FrameworkServlet to provide a configuration model very similar to that of SpringMVC. This is done so that view configuration can be separated from application configuration. CXF View specific config goes in the /src/main/webapp/WEB-INF/{projectName}-servlet.xml file and Spring annotation scanning is configured to add @Controller annotated beans to this context.

A Web Service project type will also pre configuration your application for multi-deployment based versioning. This essentially version numbers are included in default context roots.

If you chose to add an example to your project when creating it then you will find a simple service example that allows one to create and find Example data items. To completely comprehend this example you may need to read the api section.

Testing

To create a unit test simply end the test classname with Test (e.g. ExampleText.java) to create an Integration test end the classname with IT (e.g. ExampleIT.java) and place it in the /src/test/java directory. The main difference between unit and integration tests is integration tests failures will not fail a build.

Integration tests also come with a simple test grouping functionality if TestNG is used. If as part of your continuous build you only want to run a subset of Integration tests create a TestNG Group. Then when you build use the Maven Property itGroups to comma delimit the test groups you want executed as part of a given build.

It is common for integration tests of Spring projects to utilize Spring's Integration Testing features. To help facilitate the use of Spring integration tests we have included a applicationContext-test.xml file useful in providing alternative Spring configuration for tests only.

If you chose to create an example then some example unit and integration tests have been created for you. The example integration test provided uses Spring's integration test features.

The api module

If you created a Web Service application then an api module would have been created. The idea of the api module is to provide a kind of automatic client artifact for projects consuming your service to use so that they don't need to generate their own client artifacts. This project is mainly intended to work with SOAP services but can work with some caveats with REST JAX-RS services as well.

The idea is that only artifacts specific to your service's interface or API should go in this module. Implementations of these endpoints should go in the web module. In order for other applications to consume your services using this API jar you must make sure this api jar is published into the organization's maven repository. To do this consult a member of the build team.

The deploy module

The deploy module is meant to combine application server configuration with one or more web or ears. The module itself includes app server configuration for specific environments in the /src/main/resources directory. An ear or war(s) is specified as a dependency in the module's pom.xml file. At build time the application server configuration and deployment artifact are combined into a deployable zip file. This module may also be responsible for deploying this .zip file to a specified application server as part of building this project in a project build.

To control whether or not this module attempts to do a deploy as part of its execution use the skipDeployMode maven property.

The wam module

The WAM module is meant to house and help orchestrate use of the Wam Emulator. This module uses the WAM Maven Plugin to wrap the Emulator.

WAM Emulator configuration files are placed in the /src/main/resources directory and are packaged into a .jar file for reuse.

It can come in handly to deploy a WAM emulator instance to as part of a build. To control whether this module attempts to deploy itself to a local more remote location use the skipDeployMode maven property.

To run the emulator locally simply execute mvn install stack-wam:run in this directory or if you are using the LDSTech IDE you can right click on the -wam project and select Run As->Run WAM Emulator. This will execute the emulator using the configuration specified.

The qa module

The QA module is meant to house black box tests. Usually functional or load tests dependent upon the application being run in a container are placed in this module. This module usually must execute after the deploy module so that the black box tests can be run against the deployed application.

To enable the QA module in stack starter choose Add a functional test module under the Build section.

In the case of a web application functional tests can be created using Selenium. In the case of a Web Service application then functional tests can be created using Spring Integration Tests. This will simulate invoking your web services exactly the same way your clients will be.

Tests in the QA module should contain integration tests only and so they should all end with IT (e.g. ExampleIT) in their class name so that maven knows to execute them during the correct phase.

Often when writing functional tests you may want to be able to run these test against different environments without changing your test code. Variable such as the server url you are hitting or the username and password you use to login can change from environment to environment. To help manage environmental configuration for QA tests we've pre-configured the QA project to use the Stack QA Module.

If you chose to create an example in stack starter then an example black box test appropriate to your application type should have also been created.

Embedded Mode

If your application is a Tomcat application then stack starter will add support for what we call an EmbedMode build. This type of build will use the Tomcat Deploy Maven Plugin to launch the application in an embedded Tomcat instance running within Maven. This mode will also launch the WAM Emulator if your application uses WAM. This will provide a fully featured embedded environment for your application to run black box tests against. When the module is done running tests it will tear down the embedded Tomcat and emulator instances. To control whether your build runs in EmbedMode use the skipEmbedMode maven property.

This page was last modified on 12 July 2013, at 19:14. This page has been accessed 2,825 times.

Note: Content found in this wiki may not always reflect official Church information. See Terms of Use.