Basic concepts

This page explains the basic concepts of the SHOGun2 software design.

Goals of the SHOGun2 software design

SHOGun2 is intended to be

• Reusable
• Extendable
• Maintainable

Therefore SHOGun2 shall consist of (preferably independent) modules. To achieve this, SHOGun2 is organized as a Maven Multi Module project.

Modularity of SHOGun2

Maven is using POMs (XML files) to configure the build of a project. Each POM results in a (maven) artifact with some kind of (packaging) type, for example jar, war, pom or maven-archetype.

A Maven multi module project is realized by defining a root/super/parent POM (of packaging type pom) with a list of modules (which are in fact subfolders with custom POMs). On top of that it is possible that POMs (of modules) inherit (and possibly overwrite) the properties of their parent POM, which makes it easy to maintain a simple and clear project configuration.

The modules of SHOGun2 are structured in the following way:

• shogun2 (pom, root)
  • core (pom, the core-module, which has submodules again)
    • model (jar, data models of the core)
    • dao (jar, data access objects)
    • service (jar, service layer with business logic)
  • init (jar, module for content initialization)
  • web (jar, web/controller layer to provide some interface)
  • webapp-archetype (maven-archetype, template artifact for the quick creation of a SHOGun2-based war-artifact, i.e. webapplication)

ExtDirect

SHOGun2 makes use of the ExtDirect technology. ExtDirect is a technology, that allows you to call backend-methods (in our case JAVA-based) from your frontend (JavaScript).

Here you will find some general information about ExtDirect.

SHOGun2 uses the extdirectspring framework to connect the Ext4 frontend with the Java/Spring backend. You will find useful information about this framework in its wiki.

Understand how ExtDirect works with SHOGun2

Based on a SHOGun2-based webapplication, that was built with the shogun2-webapp-archetype, we will illustrate how ExtDirect works:

• Have a look at the web.xml and keep in mind what you see:

<servlet-mapping>
    <servlet-name>{{YOUR SERVLET}}</servlet-name>
    <url-pattern>/action/*</url-pattern>
</servlet-mapping>

• Have a look at the index.html:

<script type="text/javascript" src="action/api.js"></script>

• Have a look at this file (use api-debug.js here as it is better to read):

http://localhost:8080/{{YOUR SERVLET}}/action/api-debug.js

This file is provided by a web-controller of the extdirectspring framework. It contains information about backend-methods, that can be used in the frontend. All those methods have an @ExtDirectSpring annotation in the Java-Code. Otherwise they won't be published in the api.js.

Here you will find detailed information about the API.

In your Ext-JavaScript-Code one of the first statements should be:

Ext.onReady(function() {
    Ext.direct.Manager.addProvider(Ext.app.REMOTING_API);
 [...]
}

Now you are ready to make use of ExtDirect!

Autogenerated Ext4-Models

SHOGun2 offers a web-interface that can be used to retrieve autogenerated Ext4-data-models (which are based on the available Java-models). Originally, the Ext-model-generator was part of extdirectspring, but meanwhile it is a separate project.

• Try the following in your browser:

http://localhost:8080/{{YOUR SERVLET}}/shogun2/model/User.js

• This file is provided by the ExtModelController of SHOGun2, which in turn uses a method of the extclassgenerator framework:

ModelGenerator.writeModel(request, response, clazz, OutputFormat.EXTJS4, IncludeValidation.BUILTIN, true);

• You should have a look at the annotations in the SHOGun2-models, e.g.

@Model(value = "shogun2.model.User",
	readMethod = "userService.findWithSortingAndPagingExtDirect",
	createMethod = "userService.saveOrUpdateCollection",
	updateMethod = "userService.saveOrUpdateCollection",
	destroyMethod = "userService.deleteCollection")

• According to the value in the @Model annotation, you have to configure your servlet correctly to make this work:

<servlet-mapping>
    <servlet-name>{{YOUR SERVLET}}</servlet-name>
    <url-pattern>/shogun2/model/*</url-pattern>
</servlet-mapping>

You should also have a look at this documentation!