Advanced Build System

Component Oriented Development is a way of building sotfware using a modular architecture resulting in better understanding of system behaviour, easier maintenance and high level of reusability. In our context a component is :

A project is an application, whose delivery is the final objective. it's the result of several business components assembly.It defines targent running environment named "deployment" which may have differents and specific configuration.

A deployment is a target running environment receiving war, tar.gz and jnlp files. We can define several differents deployment in the same project, for example :development, customer test, production, ... Deployments list is store in file deployment.txt located in the root directory of the project.

localhost
test
prod

The previous example show 3 deployments. Very often each environment has distinct configuration properties. For example SMTP server to use is different for the development team and at the customer production site. We have to parametrize this information using a replacement token.

smtp.server.name=@@stmp.server.name@@

@@smt.server.name@@=test.mail.sharengo.org

@@smt.server.name@@=mail.sharengo.org

The two previous files allows to have different smtp server for each environment. environnement.

The module concept is equivalent to a component but it is not reusable and therefore related only to one project. Very often, modules are only used to defined project dependencies. We can find very specific source code needed for migration or stuff like that. Modules list is stored in moddep.txt file located at project root directory.

main 

This example shows a declaration for a module call "main" inside a project.

We have seen previously that ABS define tasks related to project methodology. You start by creating a project using abs new.project command and specifying a name. For each following task execution, ABS will load the project / component / module definition target of your command and will inject it in a velocity template containing a description of an Ant script to instanticiate. A script Ant is generated and run. One advantage of this approach is to completely separate project description from build tools. If you want to change the scripting langage and use something else, do it, that's easy. You have to see ABS as a logical "shell" running abstract project command in a project context. Moreover it's very configurable and use a package manager to upgrade easily developper workstation and so doing to provide new command very quickly. Developpers doesn't have to modify build script anymore.

ABS needs java version 5 or greater.

java -jar workshop-repository-manager-0.6.jar http://sharengo.org/abs/0.7/abs-core
java -jar workshop-repository-manager-0.6.jar http://sharengo.org/abs/0.7/mda
java -jar workshop-repository-manager-0.6.jar http://sharengo.org/abs/0.7/qa
java -jar workshop-repository-manager-0.6.jar http://sharengo.org/abs/0.7/doc

If you have to use a proxy, Si, vous souhaitez utiliser un proxy, you have to use the following syntax : java -jar workshop-repository-manager-0.6.jar repository-url [proxy port [user pwd] ]

TODO vérifier que cette commande existe encore, si oui la supprimer et créer un fichier build.properties par défaut.

cd $ABS_HOME
abs init

Answer the script questions (some sensible default values are provide, use it if you don't know the answer).This initialization phase will create a build.properties file in your $ABS_HOME directory. Here is a build.properties example :

binary.server.url=http://adk.open-model.org/adk-2.2/binary-components
binary-repository.path=/home/jeromeb/dev/abs/binary-repository
jvm.target=1.5

ci.server=build.argia.fr
ci.user=XXXX
ci.password=XXXX

Upload Eclipse version 3.3 (Europa) for your system : here .Start eclipse, select menu option "Help" -> "Software Updates" -> "Find and Install ..." :

Figure 2.1. Software updates screen shot

Choose "Search for news features to install" and click "Next" :

Figure 2.2. Update sites screen shot

Using "New Remote Site" button, add Sharen'Go update site : http://sharengo.org/update/europa, select it and click "Finish" Select Sharen'Go tools in the available features listand click "Next" :

Figure 2.3. Install features screen shot

Accept license and click "Finish"

A workspace permits to separate working context. It defines a physical storage area for a project and all the needed components. A good practive is to keep a distinct workspace for each version of a project you work on. So we you are working on a given project phase, you have to create a workspace. Then when you'll started a new phase, you'll create a new workspace and so doing isolate phase2 from phase 1. If you want to do some modifications on the first one, you'll be able to deliver a new version with only your small modifications without any evolution of phase 2.You'll find thereafter a workspace creation command :

$> cd $ABS_HOME
$> abs new.workspace

abs:version:
     [echo] 
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo]   ABS ~ Advanced Build System ~
     [echo] 
     [echo]          ~ Next Generation Build System ...
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo] 

new.workspace:
    [input] Enter workspace absolute path :
/home/jeromeb/workspaces/ws-workspace1    

...

BUILD SUCCESSFUL
		

First, you need to position yourself in the directory related to the newly created workspace.

$> cd /home/jeromeb/workspaces/ws-workspace1
$> abs new.project

abs:version:
     [echo] 
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo]   ABS ~ Advanced Build System ~
     [echo] 
     [echo]          ~ Next Generation Build System ...
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo] 

new.project:
    [input] Enter project name :
project1

...

BUILD SUCCESSFUL

$> cd /home/jeromeb/workspaces/ws-workspace1
$> abs new.scm.project

abs:version:
     [echo] 
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo]   ABS ~ Advanced Build System ~
     [echo] 
     [echo]          ~ Next Generation Build System ...
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo] 

new.scm.project:
    [input] Enter project name :
project2
    [input] Enter repository name : 
sharengo

...
BUILD SUCCESSFUL

$> cd /home/jeromeb/workspaces/ws-workspace1
$> abs new.scm.project.from.tag

abs:version:
     [echo] 
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo]   ABS ~ Advanced Build System ~
     [echo] 
     [echo]          ~ Next Generation Build System ...
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo] 

new.scm.project.from.tag:
    [input] Enter project name :
project3
    [input] Enter tag :
version1.0
    [input] Enter repository name : 
sharengo

...
BUILD SUCCESSFUL

First, you have to position yourself in the directory related to the current workspace.

$> cd /home/jeromeb/workspaces/ws-workspace1
$> abs new.component

abs:version:
     [echo] 
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo]   ABS ~ Advanced Build System ~
     [echo] 
     [echo]          ~ Next Generation Build System ...
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo] 

new.component:
    [input] Enter component name :
component1

...

BUILD SUCCESSFUL

$> cd /home/jeromeb/workspaces/ws-workspace1
$> abs new.scm.component

abs:version:
     [echo] 
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo]   ABS ~ Advanced Build System ~
     [echo] 
     [echo]          ~ Next Generation Build System ...
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo] 

new.scm.component:
    [input] Enter component name :
component2
    [input] Enter repository name : 
sharengo

...
BUILD SUCCESSFUL

$> cd /home/jeromeb/workspaces/ws-workspace1
$> abs new.scm.component.from.tag

abs:version:
     [echo] 
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo]   ABS ~ Advanced Build System ~
     [echo] 
     [echo]          ~ Next Generation Build System ...
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo] 

new.scm.component.from.tag:
    [input] Enter component name :
component3
    [input] Enter tag :
version1.0
    [input] Enter repository name : 
sharengo

...
BUILD SUCCESSFUL

The "lib.local" command is used to compile a component or a project. This operation build 3 jar archives containing all *.class files from the java source files. You can also use the command "lib.all" which apply the compilation process on all components used by the current one. The 3 resulting archives are :

$> cd /home/jeromeb/workspaces/ws-workspace1
$> cd components/component1
$> abs lib:all

...
BUILD SUCCESSFUL

The "deploy.new" command create a new deployment environment for the current project. It add a directory with the deployment name inside the "deployment" directory located in project root directory. It also create replace.server.properties and replace.client.properties files containing the value of the variable part of the configuration.

$> cd /home/jeromeb/workspaces/ws-workspace1/projects/project1
$> abs deploy:new

abs:version:
     [echo] 
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo]   ABS ~ Advanced Build System ~
     [echo] 
     [echo]          ~ Next Generation Build System ...
     [echo] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [echo] 

deploy:new:
    [input] Enter deployment target name :
localhost

...
BUILD SUCCESSFUL

The "deploy:build.war" command build a WAR archive which can be deployed in an application server as Tomcat.

The "deploy:build.cli" command build a *.tar.gz archive containing an application environnement for command line interface program.

This 2 commands build one archive file for each deployment environment using the configuration parameter values found in replace files.

In menu : "New" -> "Project" -> in ABS node select "New Component"

Figure 4.1. Screenshot from component creation

The eclipse plugin interacting with your locally installed ABS, it's mandatory to specify the installation directory $ABS_HOME and the ABS workspace. If those informations are not available in ABS eclipse configuration (menu "Window" -> "Preferences ..." -> "ABS Preference"), the following wizard will be presented and will help you to configure :

Figure 4.2. Screenshot for ABS_HOME selection

Figure 4.3. Screenshot for ABS workspace selection

Figure 4.4. Screenshot for component definition

In menu : "New" -> "Project" -> in ABS node select "New Project"

Figure 4.5. Screenshot for project creation

Figure 4.6. Screenshot for project description

When a new project is created, the wizard automatically add a module named "main" and a "localhost" deployment. You'll find in "PackageExplorer" view a module "project1_main" and a deploiement "project1_localhost_server".

Figure 4.7. Screenshot of package explorer view used to visualize project resources

A design model may be created for a component or project module.

4.3.1. UML modelization

Locate yourself in server/model/conception directory and create a model named conception.uml using menu "New" -> "Other..." -> "SharenGo Unified Modeling" -> "Step 3 - New Conception Model"

Figure 4.8. Screenshot for design model creation

This action create three files :

• conception.uml : this file contains all structural model element,

• conception.umldi : this file contains all diagrams description using the first one to reference element appearing in diagrams,

• conception.properties : this file is used to parametrize generation strategy. The default values are sensible for current use.

Note

You MUST name the model org::sharengo::component_name using the properties windows. ("::" is the package separator character used in UML) This notation permits to find the package name containing the generated files.

4.3.2. Logical architecture

In order to modelize the various components we need, we have define a logical architecture at the PIM (Platform Independant Model) level in the MDA way. The following schema shows the different layers of this architecture based on the MVC pattern.

Figure 4.9. Logical architecture representation

This architecture model may be seen as a metamodel because it will instanciated in each component and module. For historical reasons, we have choosen the UML language and not a DSL (Domain Specific Language). A UML profile has been designed to incorporated the various concepts used in the architecture metamodel. This profile contains a set of stereotypes and properties described in the next section.

4.3.2.1. Stereotypes

Stereotypes are used to add specfic semantic meaning to UML elements. The next figure shows how to apply a stereotype in Topcased modeler.

Figure 4.10. Applying a stereotype

A stereotype define a set of properties which can be valued in the "Stereotype attributes" tab.

4.3.2.2. <<Entity>> stereotype

Definition.  This stereotype is used to define business domain objects (which are persisted by the application).

Properties.  None

Usage context. 

Figure 4.11. Association between 2 entities

4.3.2.3. <<Dto>> stereotype

Definition.  This stereotype is used to specify transferable datas. The DTO (Data Transfert Objects) pattern is used to build a mediation layer between business processes and UI layer.

Properties.  None

Usage context.  Often used as an operation parameter.

4.3.2.4. <<EntitiesManager>> stereotype

Definition.  This stereotype is applied on class defining Data Access Objects following the well known pattern. This kind of class manage storage and retrieval for entities.

Properties.  None

Dependencies.  TODO ajouter un screenshot

4.3.2.5. <<Process>> stereotype

Definition.  Used on classes defining business services ou processes

Properties.  None

Usage context.  A "process" class may used others processes or EntitiesManager

Figure 4.12. Use of EntitiesMgr by a process class

4.3.2.6. <<Controller>> stereotype

Definition.  This stereotype is used to route user requests. It decodes transmitted datas and send them to the UI layer.

Properties.  None

Usage context. 

Figure 4.13. Use of UI class by a controller

4.3.2.7. <<Ui>> stereotype

Definition.  This stereotype is applied on classes orchestrating requests to business process and transmitting the results to view in order to show datas to end users.

Properties.  None

Usage context.  A UI class may used others UI, UI uses Process and views Une Ui peu utiliser d'autres Ui, faire appels à des Process et utiliser des View.

Figure 4.14. Process and view used by UI

4.3.2.8. <<View>> stereotype

Definition.  This stereotype is used to define user "screen".

Properties.  None

Usage context.  A view is used by UI.

4.3.2.9. <<Remote>> stereotype

Definition.  This stereotype express that an operation is remotely usable. In a UI context, that means that an AJAX kind of use is possible (call from web browser). In a Process context the operation is published as web service.

Properties.  TODO

4.3.2.10. <<Transactional>> stereotype

Definition.  Express the transactionnal semantic of a process operation.

Properties.  None

4.3.2.11. <<Config>> stereotype

Definition.  This stereotype is applied on classes defining configuration values. For example, in order to define a smtp server name, you have to define a "smtpserver" attribute of type String in a class supporting the "Config" stereotype.

Pproperties.  None

Usage context.  Config classes may be used by all classes of the architecture.

We are using the Acceleo transformation model to text tool to generate source code from UML model following the logical architecture. In order to run a transformation, you to define a transformation chain. In our case, we will define a specific chain calling a generic one for a given architecture.

To create the chain "conception.launch", select menu "New" -> "Others" -> "Acceleo" -> "Module Launcher" :

Figure 4.15. Screenshot for etape 1 of ModuleLauncher wizard

Choose chain : "Java Generator for Spring / Hibernate / Velocity Architecture" :

Figure 4.16. Screenshot for etape 2 of ModuleLauncher wizard

Click "Next" and set "conception.chain" as name :

Figure 4.17. Screenshot for etape 3 of ModuleLauncher wizard

click "Next", select the surce UML model source (conception.uml).

Figure 4.18. Screenshot for etape 4 of ModuleLauncher wizard

Cliquer sur "Next", sélectionner le modèle UML source conception.uml :

Figure 4.19. Screenshot for etape 5 of ModuleLauncher wizard

Double click on the file to edit the chain if you want to modify something

Figure 4.20. Screenshot for chain editing

Run the code source generation choosing the "Launch" option in the contextual menu of the conception.chain file.

Figure 4.21. Screenshot of generation run

4.4.1. Spring based physical architecture

Spring is a java library used to build technical frameworks for various architecture. It's a light container offering an environment comparable to Spring biggest strength is his use of IoC Inversion of Control) pattern described here :http://www.martinfowler.com/articles/injection.htmlby famous architect Martin Fowler. The reference documentation of the project is loacted here : http://www.springframework.org/docs/reference/

4.4.1.1. Prerequisite

In order to use Spring in a component or module, you must add a dependency to middleware/gluon-core component. This component defines all binary dependencies needed by Spring.

First, you have to retrieve this component from the repository using the option menu New / Project ... / ABS / Create a new Component from SCM repository :

Figure 4.22. Screenshot for retrieving an existing component step 1

Choose the target repository and input the component name.In our case we'll use the trunk version.

Figure 4.23. Screenshot for retrieving an existing component step 2

Add the dependency toward this component, editing the srcdep.txt file in component or module root directory and adding the following line :

Example 4.1. srcdep.txt file example

sharengo:middleware/gluon-core/trunk

Note

If you want to use work with web services, you must add one more dependency to the middleware/gluon-xfire component.

4.4.1.2. Generated files

You'll find thereafter an exhaustive list of all generated files for each kind of stereotype.

4.4.1.2.1. From <<Entity>>stereotype

For an entity class named "MyEntity1" located in the package "entitties" in a "org::sharengo::component1" model , the generated files are :

• server/main/src/org/sharengo/component1/entities/MyEntity1.java : business class

• server/resources/org/sharengo/component1/entities/hibernate/MyEntity.hbm.xml : hibernate mapping file

• server/test/src/org/sharengo/component1/entities/impl/MyEntityHelper.java : helper class used to create business object (used in unit tests)

4.4.1.2.2. From <<Dto>> stereotype

For a dto class named "MyDto1" located in the "dto" package in a "org::sharengo::component1" model, there is only one generated file :

• /server/main/src/org/sharengo/component1/dto/MyDto1.java

4.4.1.2.3. From <<EntitiesManager>> stereotype

For an EntitiesManager class named "MyEntity1Mgr" located in the package "entities"in a "org::sharengo::component1" model , the generated files are :

• server/main/src/org/sharengo/component1/entities/IMyEntity1Mgr.java : Data Access interface

• server/main/src/org/sharengo/component1/entities/impl/MyEntity1MgrImpl.java : Date Access implementation related to the previous interface

• server/test/src/org/sharengo/component1/entities/impl/MyEntity1MgrTest.java : unit tests for the implementation

• server/resources/META-INF/spring/org.sharengo.component1/layer-daos-hibernate.xml : Spring configuration file with entities manager declaration and related dependencies.

4.4.1.2.4. From <<Process>> stereotype

For a process class named "MyProcess1" located in the "process" package of a "org::sharengo::component1" model, the generated files are :

• server/main/src/org/sharengo/component1/process/IMyProcess1.java : business service interface

• server/main/src/org/sharengo/component1/process/impl/MyProcess1Impl.java : business service implementation

• server/test/src/org/sharengo/component1/process/impl/MyProcess1Test.java : unit tests for implementation

• server/resources/META-INF/spring/org.sharengo.component1/layer-services.xml : Spring configuration file with process class declaration and related dependencies. It also defines the transactional strategy for each operation supported the "Transactional" stereotype.

If some operations support the "Remote" stereotype, more files are generated :

• server/main/src/org/sharengo/component1/process/IMyProcess1WebService.java : interface containing only "remote" methods declaration.

• server/resources/META-INF/spring/org.sharengo.component1/layer-xfire-services.xml : Spring configuration file used to link the interface to the implementation and defining the URL access for each operations.

• server/test/src/org/sharengo/component1/process/impl/MyProcess1WebServiceTest : unit tests for remote methods.Those tests reuses the process unit tests providing a process instance used through remote access using an embedded jetty server.

• server/test/src/org/sharengo/component1/process/impl/MockMyProcess1WebService.java : mock object for unit tests

• client/main/src/org/sharengo/component1/ws/WSClientFactory.java : factory creating IMyProcess1WebService instance from URL like http://localhost/project1/services/IMyProcess1WebService

4.4.1.2.5. From <<Controller>> stereotype

For a controller class named "MyController1" located in a "ui" package in a "org::sharengo::component1", the generated files are :

• server/main/src/org/sharengo/component1/ui/MyController1.java : router class to "UI"

• server/resources/META-INF/spring/org.sharengo.component1/layer-controllers.xml : Spring configuration file containing controller implementation declaration and related dependencies.

4.4.1.2.6. From <<Ui>> stereotype

For a ui class named "MyUi1" located in the "ui" package of a "org::sharengo::component1" model, the generated files are :

• server/main/src/org/sharengo/component1/ui/IMyUi1.java : UI interface

• server/main/src/org/sharengo/component1/ui/impl/MyUi1Impl.java : ui implementation

• server/resources/META-INF/spring/org.sharengo.component1/layer-uis.xml : Spring configuration file containing ui implementation declaration and related dependencies.

4.4.1.2.7. From <<View>> stereotype

For a view class named "MyView1" located in the "ui" packagei of a "org::sharengo::component1" model, the generated files are :

• server/main/src/org/sharengo/component1/ui/impl/MyView1.java : view class

• server/main/src/org/sharengo/component1/ui/ViewFactory.java : view obect factory. the view objects are stateful and cannot be injected as the others elements of the architecture.

4.4.1.2.8. From <<Config>> stereotype

For a Config class named "MyConfig1" located in the "config" package of a "org::sharengo::component1", the generated files are :

• server/main/src/org/sharengo/component1/Confi/MyConfig1.java : configuration class

• server/resources/META-INF/spring/org.sharengo.component1/layer-configs.xml : Spring configuration file declaring the previous class.

4.4.1.2.9. From the model itself

• server/resources/META-INF/spring/component.xml : Spring configuration files defining what are the needed "layer*" configuration files for the current component

• server/resources/META-INF/spring/component-test.xml : same role as previous file but used in unit tests context and therefore modifiable

• server/resources/META-INF/spring/org.sharengo.component1/applicationContext-tests.xml : Spring configuration file defining hibernate resources and others resources used in unit tests.

• server/test/src/org/sharengo/component1/AbstractBusinessLayerTests.java : abstract class used by all unit tests.It"s used to initialize the components graphs.