Getting Started With SLC
From ArgeoWiki
SLC is a framework on top of which systems related to software life cycle can be built. Therefore, using SLC as such requires a development environment and an understanding of its various components. In order to leverage the open source nature of SLC it is recommanded to check out the project and look at the code, the unit tests and the provided example. The purpose of this page is to ease the setting up of the development environment and give a high-level overview of the code.
If you are looking on how to use an application built on top of SLC, please refer to the tool documentation.
Contents |
Technologies used
Spring
Although the SLC core is made of Plain Old Java Objects (POJO) and has not direct dependency on any framework it is meant to be configured with the Spring Inversion of Control (IoC) container (or any other IoC container).
A high-level of Spring is required in order to understand the unit tests and examples.
The introduction to Spring by its creator, Rod Johnson, is a must read: http://www.theserverside.com/tt/articles/article.tss?l=IntrotoSpring25
The excellent reference documentation of Spring can be used thereafter to dig into more precise points: http://static.springframework.org/spring/docs/2.5.x/reference/index.html
Ant
A basic understanding of Ant is preferable in order to understand the examples (most unit tests are not using Ant).
The manual is obviously the best place to start: http://ant.apache.org/manual/index.html
In order to understand the code of the Ant extensions provided with SLC, this section of the manual can be useful : http://ant.apache.org/manual/develop.html#writingowntask
Hibernate
The persistence of the various objects is done via Hibernate (although other technologies could be used as well). If you are interested in this part you should refer to their reference documentation: http://www.hibernate.org/hib_docs/reference/en/html/index.html
Eclipse and Maven
SLC has no dependency with the Eclipse IDE as such, but the projects code provides .project file configuring the Eclipse project.
The dependencies of SLC are managed by Maven. If the required Eclipse plugins are installed, everything should work directly. But the Maven plugin is still quite unstable and you may need to tinker a little bit with Maven, in such cases information about Maven can be found here: http://maven.apache.org .
Setting up the development environment
(You can also look at the more general page Setting Up The Argeo Development Environment)
Eclipse installation
You need to have an Eclipse IDE with the Java development features (JDT). The version currently supported is v3.3 (Europa). Eclipse can be downloaded from: http://www.eclipse.org
Note: in order to install additional plugins via update sites:
- Start Eclipse
- Go into the menu: Help > Software update > Find And Install... > Search for new features to install
- Add the update site, select it, click next
- Select the features you need
- Accept license, download and install (don't worry about the unsigned warning)
In order to check-out the project code, you will need a Subversion plugin. We are using Subclipse (http://subclipse.tigris.org), whose update site is: http://subclipse.tigris.org/update_1.2.x/
In order to automatically retrieve the dependencies via Maven and set up the project classpath, you will need the M2Eclipse plugin (http://m2eclipse.codehaus.org/) whose update site is: http://m2eclipse.codehaus.org/update/ It is recommended to activate the source download from Window > Preferences... > Maven.
Optional but useful plugins
The Eclipse Web Tools Project (WTP) contains a practical XML editor which provides formatting, auto-completion (if a DTD or XSD schema is declared) and schema validation. Update site: http://download.eclipse.org/webtools/updates/
Spring provides the Spring IDE with plugins easing Spring development. The extensions of the above mentioned XML editor are especially practical since it allows auto-completion of Java class names and bean properties. Update site: http://springide.org/updatesite
Checking out the projects
SLC is made out of three projects:
- SLC parent (org.argeo.slc): common Maven configurations
- SLC core (org.argeo.slc.core): code and low level unit tests
- SLC Example (org.argeo.slc.example): a dummy application build on top of SLC
- SLC UI Launch (eclipse/org.argeo.slc.ui.launch): an Eclipse plugin to easily launch SLC applications
The projects should be checked out in this order from the Subversion repository: https://www.argeo.org/svn/slc/trunk . (the order is not required as such but it is consistent with the dependencies and should ease the first Maven initialization).
Except if you are specifically interested in it, you do not need to check out the SLC UI Launch Eclipse plugin. The three other projects should be checked out in the same directory (the default, that is your Eclipse workspace, will work fine).
When the projects have been checked out, the Maven plugin should set up the dependencies, and all projects should easily build.
If you encounter problems at this stage:
- Check that you have access to Argeo's Maven repository: http://www.argeo.org/maven/proxy/
- Try to open/close the various projects (it sometime helps the M2Eclipse plugin...)
- Install Maven (download and unzip the package and put the ./bin directory in your PATH) and go into the directory where you checked out org.argeo.slc and run 'mvn -cpu -U clean install'
- When you tried all this, contact us (contact [a] argeo.org)
Core Project Structure (org.argeo.slc.core)
The directory structure of the core project follows Maven conventions, that is:
- src/main/java contains the Java code
- src/main/resource the additional resources
- src/test/java the code of the unit tests
- src/test/resources the resources of the unit tests (test data, Spring context files, etc.)
The code itself consists of the following areas:
- Core
- Build (org.argeo.slc.core.build.*): interfaces modelling build processes
- Deploy (org.argeo.slc.core.deploy.*): interfaces modelling deploy processes
- Test (org.argeo.slc.core.test.*): interfaces modelling test processes (the most developed as of v0.8)
- Context (org.argeo.slc.core.test.context.*): test context associating values that can be shared between different tests and expected values.
- Structure (org.argeo.slc.core.structure.*): identification of processes and results into an abstract structure of data, used to organize test results, monitoring data, logs, etc.
- Ant (org.argeo.slc.ant.*): bridge between Ant and Spring, plus specific SLC Ant tasks.
- DAO (org.argeo.slc.dao.*): interfaces to persisted objects for reporting purposes
- Hibernate DAOs (org.argeo.slc.hibernate.*): Hibernate implementation of the DAOs
- Diff (org.argeo.slc.diff.*): abstraction of diff tools, in order to easily integrate various implementations
- Unit (org.argeo.slc.unit.*): helpers for unit tests
It is recommended to review the Javadoc of these classes. To generate them, simply create a package via Maven:
- Right-click on pom.xml (at the root of the project), Maven > Maven Install
- When it is done, the Javadocs have been generated under target/apidocs.
To see how to use the Ant features, refer to the documentation of the org.argeo.slc.ant packages (which itself points to the javadoc of the SlcAntConfig and AntRegistryUtil classes)
Example Project (org.argeo.slc.example)
A dummy but functioning SLC application is defined in this project.
The directory structure of the project follows Maven conventions, that is:
- src/main/java contains the Java code of the specific componetns
- src/test/java allows to start the application as unit tests (handy when in an IDE)
The SLC application itself is located under: ./exampleSlcAppli (see the Javadoc of the SlcAntConfig class for an explanation of this structure).
To run the example, simply run the unit tests.
