Table of Contents
List of Tables
- 6.1. ID ranges
Table of Contents
Regarding its global architecture, Scarab uses the MVC (Model-View-Controller) design pattern. The part that interacts with the user (View) is decoupled from the data defining the application state (Model) by a Controller that managing the navigation in Scarab.
A framework is a way of building applications, plus tools to help building them. The Turbine framework (http://jakarta.apache.org/trubine) is a doctrine to program web applications according to the MVC design pattern. Turbine also brings quite a set of tools (components, projects) to help code your application. Some of these components are detailed below, as they are used by Scarab.
The form data sent by the user may be submitted to a validation process (required fields, well-formed answers,...). This preliminary check is performed by a Turbine component called Intake.
Intake is now a part of Fulcrum (see below).
Note
Intake plays in Turbine the same role as the Struts Validator in Struts, if you're familiar with this well-known framework.
Intake validation rules are expressed in XML in the
src/conf/intake.xml
file.
The Intake documentation is available at this URL: http://jakarta.apache.org/turbine/fulcrum/fulcrum-intake.
It's the heart of the framework. As in others MVC2 frameworks, there is only one entry point in the application, the
scarab
servlet, that is an instance of the
org.apache.turbine.Turbine
class.
The behaviour of this servlet is ruled by five properties files, declared in the TurbineConfiguration.xml deployment descriptor :
-
custom.properties -
defaultCustom.properties -
PermissionMapping.properties -
TurbineResources.properties -
Torque.properties
Note
Which version of Turbine ?
If you know Turbine or if you have read the documentation on the Jakarta web site, you have probably realized that the architecture of the different versions of Turbine (2.3 and 2.4 are currently available) is quite different.
In fact, Scarab has been developed initially by members of the Turbine project and it used a pre-version of Turbine 3 -- that will probably never be released. So the current development team spends some energy trying to bring Scarab back in the current Turbine development flow by "downgrading" the version of some of the components and integrating some of the Turbine 3 evolutions back in Turbine 2.4.
Configuration files mentioned above are in the
src/conf/conf/
directory of the Scarab distribution, and under
WEB-INF/conf
in the web application.
Turbine itself is a jar in www/repository/turbine/jars (and the corresponding source files in www/repository/turbine/src). As explained above, it is an intermediary release to which you probably cannot sustitute another tagged release.
The Turbine project documentation is available at this URL: http://jakarta.apache.org/turbine.
The Turbine architecture in 2.4= versions is based on the concept of services and uses a microcontainer of the Avalon family. Some of these services (among which Intake, mentioned earlier) are part of Fulcrum and used by Scarab.
The Fulcrum project documentation is available at this URL: http://jakarta.apache.org/turbine/fulcrum/
The services used by Scarab are implemented on top of a microcontainer, member of the Avalon family. (By the way, YAAFI is just an acronym for Yet Another Avalon Framework Implementation.)
The YAAFI project documentation and its interface with Fulcrum are available at this URL: http://jakarta.apache.org/turbine/fulcrum/fulcrum-yaafi.
Scarab Java objects are populated from, and persisted to, a relational database (RDBMS) using a software component that was once part of Turbine but became independent since: Torque (Torque now belongs to the Apache database project).
From an XML high-level description of the database schema, Torque can generate:
- database schema creation scripts (SQL/DDL), for various RDBMS;
- Java classes that map the various database tables to JavaBeans, with finders and accessor methods.
If you are interested in further details about the database schema, read chapter 3.
The three XML files describing the database schema are in the src/schema of the Scarab distribution.
The documentation of the Torque project is available at this URL: http://db.apache.org/torque
Turbine can use JSP (JavaServer Pages) but the first Scarab developers chose to use the Velocity technology for the dynamic pages sent to the user.
Velocity is a template language: at runtime, the values of JavaBeans placed in the Velocity "Context" are inserted in a predefined (static) content.
There are two differences with the JSP technology that are worth a mention here, that may well have been the motives of the initial Scarab development team:
- first, there is a point about architecture. There are control structures in Velocity (such as conditions, loops, etc.) but it is not possible to insert Java code in a template, there is no way to insert the so-called "scriptlets". This should make the maintenance easier in the long term because the view and the controller are completely decoupled from each other.
- in practice, the JSP can only be used to generate web pages (HTML or XML); Velocity is a more general templating language and can be used to generate mails, SQL scripts, PostScript and quite a lot of other funny things.
The Velocity templates for the Scarab web pages (and emails, etc.) are under src/webapp/WEB-INF/templates, grouped by functionality.
The documentation of the Velocity project is available at this URL: http://jakarta.apache.org/velocity.
Table of Contents
Abstract
The Scarab application currently may be built by the end user using Ant. Ant is used to create and initialize the database.
This is the main build file.
The default target, deploy, is used to generate the code of the OM (Object Mapping) classes and to compile and build the Scarab application.
The second main target, create-db, is used to create and initialize the Scarab database. It does this by calling the second ant build file, described in the second section.
The target dependency graph below may help you visualize how targets are related to each other and the order in which they are called.
Abstract
Though Scarab end-users are more likely to use Ant to build Scarab, as a developer you will need Maven to access all development functionalities, among which documentation generation.
Though Maven 2 is getting momentum and has officially become the mainstream version at the end of 2005, Scarab still uses Maven 1.
Maven 1 and Maven 2 are functionnally equivalent but they are not syntactically compatible and use different build files.
So you will need to install Maven 1 and refer to the Maven 1 documentation at this URL: http://maven.apache.org/maven-1.x/
Go to the $SCARAB_ROOT directory.
Launch Maven:
maven war -Dmaven.test.skip
-Dmaven.test.skip skips the execution of unit tests.
Scarab unit tests have been designed to be executed against a database; if yours is not (yet) configured, they will most certainly fail.
Just launch:
maven test
The results of the tests will be in $(SCARAB_HOME)/target/test-results/
If you'd like to make your tests with another db environment, follow these steps:
-
maven clean(you better start from scratch if you gonna test) - Configure your
build.propertiesto contain at least the correctscarab.database.typevalue. - maven war
- maven scarab:create-db (make sure you choose the same database than before!!)
- maven test
Table of Contents
You will need the Subclipse plugin to connect to the Subversion repository that hosts and manages the Scarab source code base.
If you do not have this plugin already installed, you will find detailed installation instructions at this URL : http://subclipse.tigris.org/install.html
Select the 'SVN Repository Exploring' perspective :
Right-click in the SVN Repository view to connect to a new Subversion repository :
The connection URL is :: http://scarab.tigris.org/svn/scarab
and the Root URL is : http://scarab.tigris.org/svn
If you are a Scarab committer, use your tigris.org login and password to connect; otherwise you do not need any particular identification and you may leave the User and Password fields blank (though it seems that any User/Password will work here).
To get the current version, choose the 'trunk' branch (equivalent to CVS HEAD for those who have used this version control system before).
You can then use 'Checkout As Project', which allows you to rename the project (otherwise Eclipse would name it trunk, which is not that meaningful).
The 'New Project' wizard appears. Choose 'Java project'.
You now have to fill in the project name (you may choose scarab or any other name that suits you best).
If you are using Eclipse 3.1, you must choose J2SDK compatibility. At the moment, the development team has chosen to preserve JDK 1.3 compatibility.
Last step : it is best to change the Default output folder to :scarab/target/webapps/scarab/scarab/WEB-INF/classes
The Sysdeo Tomcat plugin allows you to start and stop Tomcat from Eclipse and makes debugging the application under development easier.
Download the 3.1 beta version from this URL: http://www.sysdeo.com/eclipse/tomcatplugin.
To install this plugin, all you need is to uncompress the ZIP archive in the plugins directory of your Eclipse installation.
At the root of your project, type the following commands :
maven war:inplace
maven eclipse
This command generates the .project file used by Eclipse.
In Window | Preferences... | Tomcat :
- Select the 4.0.x version
- Tomcat directory : the
tomcatdirectory in your Scarab project - Context declaration in server.xml
Table of Contents
The current implementation of a Subversion client for Netbeans (code named "teepee", available from http://subversion.netbeans.org/) is only a prototype. So, at the moment, you need to use another client to check the sources out of the Scarab Subversion repository. If you use Windows as your development environment, you'll probably want to use TortoiseSVN - another Tigris project.
Your best option to develop Scarab in Netbeans is certainly to use the Mevenide plug-in (which is, by the way, much more stable and functional in Netbeans than in Eclipse, not to mention JBuilder).
Download Mevenide for Netbeans at this URL: http://mevenide.codehaus.org/mevenide-netbeans-project/index.html
You will get a ZIP file with 16 nbm (Netbeans modules) inside. Unzip the file to a temporary directory.
Tip
If you are familiar with Netbeans modules installation, you will probably want to skip this section.
In the Tools menu, choose Update Center
Check 'Install Manually Downloaded Modules (.nbm Files)'
Use the 'Add...' button to add the 16 files you have downloaded.
Just click 'Next >'.
You will have to accept the different licences. The modules are then ready for installation.
View the certificate (there is only one here) and click 'Finish' to install the modules.
You need now to restart Netbeans to use the Mevenide plug-in you have just installed.
Accessing the Scarab project is now as easy as it can be. In the File menu, choose 'Open Project...'
Choose the directory in which you checked out Scarab from the Subversion repository.
There it is !
You have direct access to Scarab custom Maven goals by right-clicking the Scarab project.
Table of Contents
Scarab data are accessed via Torque, the OR mapping developed for and with the Turbine framework (but Torque is today independent in its way).
The Scarab database schema is formally described in XML. This schema will be explained in three parts, corresponding to the three XML files under ./src/schema.
- the table associated to the primary key broker (
id-table-schema.xml); - the tables used to manage the Scarab users (for authentification and other purposes) and the permissions in the Turbine framework (
turbine-schema.xml); - the tables of the Scarab application itself (
scarab-schema.xml).
From this formal definition of the database schema, Torque generates:
- SQL (DDL) scripts to create tables in the various RDBMS;
- a set of java classes that map the database entities as objects (the so called "peers").
Most tables in the Scarab schema have meaningless (large) integers as primary keys. Many RDBMS offer a native mechanism to generate such primary keys (integers, not necessarily in sequence): Oracle SEQUENCE's, auto-incremented columns in MySQL or MSSQL, etc.
One of the Scarab design goals was to be portable across many RDBMS; thus, the generation of primary keys could hardly rely on such native mechanisms. So Scarab uses for this a Torque functionality ("id broker").
The
id_table
table is used to generate primary keys for the various tables in the Scarab schema.
As a rule, everything under 10000 is reserved for development use (default data, sample data etc.)
These tables are used to authenticate and manage the Scarab users, their roles and permissions in the different modules.
The tables in this part of the model are:
-
turbine_user: stores data about the Scarab users, their logins, passwords, etc.. -
turbine_role: stores the list of roles. Roles are common to all Scarab modules. -
turbine_permission: stores the different permissions defined in the Scarab application. -
turbine_group: this table may be required by Turbine at runtime but it is not used by Scarab. It is always empty. - The
turbine_user_group_roleandturbine_role_permissiontables are many-to-many relations. Their role is explained in the ERD below:
The following screenshot shows the definition of roles in Scarab (with the example data):
This is an illustration of the corresponding data model:
The following screenshot shows the definition of a user's roles (in the example data):
This is an illustration of the corresponding data model:
Before entering the heart of the Scarab data model, let us mention two series of simple entities related to the users as defined just above.
The list of modules and the corresponding data are stored in the scarab_module table.
Tip
Our QA manager asked one day for a table that would give a correspondance between the module codes and their names. The slight difficulty here is that the module name is often meaningful with the name of the parent module. It is easy to obtain this kind of table from SCARAB_MODULE with the following SQL request:
select M1.MODULE_CODE, M2.MODULE_NAME, M1.MODULE_NAME from SCARAB_MODULE M1, SCARAB_MODULE M2 where M1.PARENT_ID = M2.MODULE_ID order by M1.MODULE_CODE;
There it is!
Issue types are stored in the scarab_issue_type table. Modules and issue types are related to each other in a many-to-many relationship through the scarab_r_module_issue_type relation table.
The global issue types, as illustrated below, are related to the "Global" module (the ID of this module is always 0).
Table of Contents
As has been said in the Workflow chapter of the Scarab User's Guide, Scarab has no "hard-coded" workflow. When saving issues, all state transitions are allowed and there is no interaction with any external system ever.
Now let's have a look at how this is implemented.
At the programming level, a workflow is any java class that implements the org.tigris.scarab.workflow.Workflow interface (the source code of this interface is located under src/java).
The workflow is then instantiated dynamically at runtime by Turbine, according to a declaration in Scarab.properties (this file is located at runtime in the web application tree under WEB-INF/conf).
# The workflow tool
# scarab.workflow.classname=org.tigris.scarab.workflow.DefaultWorkflow
scarab.workflow.classname=org.tigris.scarab.workflow.CheapWorkflow
This was the default workflow for all versions of Scarab until milestone 19.
This workflow is implemented in the org.tigris.scarab.workflow.DefaultWorkflow class. This class is a stub, that does nothing and allows all transitions.
This is the default workflow for all Scarab versions from milestone 20. The way it works from the user point of view is explained in the User's Guide.
This workflow is implemented in the org.tigris.scarab.workflow.CheapWorkflow class (againts the odds). It implements the Workflow interface indirectly by inheriting from the default workflow, DefaultWorkflow probably not to redefine certain default behaviours.
To define a new workflow, using other mechanismes, communicating with one or several external systems or more adapted to the needs or processes of your organization, you just need to:
- write a java class that implements the
org.tigris.scarab.workflow.Workflowinterface (either directly or by inheriting fromorg.tigris.scarab.workflow.DefaultWorkflow); - set the name of this class in the
Scarab.propertiesmentioned above.
Someone wrote an interface between Scarab and the WfmOpen open-source workflow engine. This implementation, or the base of it, is currently stored in the SourceForge tracker at thie URL: http://sourceforge.net/tracker/index.php?func=detail&aid=961620&group_id=76143&atid=546206.
The status of this development is unknown.
It is possible to access remotely the Scarab functionalities via XML-RPC.
An example is supplied in the Scarab sources (under src/java):
- la classe
org.tigris.scarab.util.SimpleHandler.java(server, in Scarab) is used by the Scarab-Subversion integration (read the corresponding chapter in the Scarab User's Guide); - la classe
org.tigris.scarab.util.SimpleHandlerClient.java(client, in another application) is a simple example of using the server above.