Getting Started
This tutorial will get you started and have you Asserting Your Architecture! in a matter of minutes.
The steps that are covered include:
- Get the Library and Dependencies
- Write your architecture rules
- Write
- Write your unit test
- Write your Ant test
- Execute
- Execute your unit test
- Execute your Ant task
Get the Library and Dependencies
You can get the library from one of two locations.
First, the easiest and most common method is to download the pre-compiled package from the downloads page.
Or, you can get the latest development commit from subversion. Details on accessing subversion are available on the source page. Note however, that the code in subversion is not always stable. Be sure to run the tests to find out.
For a list of the dependencies that you will need to download, see the dependencies list.
Write your architecture rules
Next, you will create your architecture rules. This page will only discuss the XML configuration option, but be aware that you can also populate the configuration programmatically - or both with a configuration file and programmatically.
First, create the XML configuration file. The standard naming convention for this file is architecture-rules.xml but you are able to name this file whatever you want. Place this file in your classpath, such as src/test/resources.
Next, you’ll actually write your rules. This requires some though. Think about your layers and modules and strive for separation of concern and loosely coupled modules. See the sample configuration example to write your rules.
Write your unit test
First, note that if you are using the Ant task method of executing your test you don’t need to write the unit test. See the next section on writing the Ant task.
XML Configuration
To write the unit test,
- extend AbstractArchitectureRulesConfigurationTest
- implement String getConfigurationFileName() to return “architecture-rules.xml”
- implement void testArchitecture() which should simply call assertTrue(doTests());
A complete, simple example looks like:
/**
* Architecture test example.
*
* @author mikenereson
* @see AbstractArchitectureRulesConfigurationTest
*/
public class SimpleArchitectureTest
extends AbstractArchitectureRulesConfigurationTest {
/**
* @see AbstractArchitectureRulesConfigurationTest
*/
public String getConfigurationFileName() {
/**
* Provide the name of the rules configuration file.
* File file is loaded from the classpath.
*/
return "architecture-rules.xml";
}
/**
* @see AbstractArchitectureRulesConfigurationTest#testArchitecture
*/
public void testArchitecture() {
/**
* Run the test via doTest(). If any rules are broken,
* or if the configuration can not be loaded properly,
* then the appropriate Exception will be thrown.
*/
assertTrue(doTests());
}
}
Programmatic Configuration
You may also opt to provide only programmatic configuration, and provide no xml configuration. To do this, call getConfiguration() which will return and instance of com.seventytwomiles.architecturerules.configuration.Configuration for you to setup. Once configured, again, implement testArchitecture() to call assertTrue(doTests());. A complete example looks like:
public class SimpleProgramaticArchitectureTest
extends AbstractArchitectureRulesConfigurationTest {
/**
* Sets up the fixture, for example, open a network
* connection. This method is called before a test
* is executed.
*/
protected void setUp() throws Exception {
super.setUp();
/* get the configuration reference */
final Configuration configuration = getConfiguration();
/* add sources */
configuration.addSource(
new SourceDirectory("target\\test-classes", true));
/* set options */
configuration.setDoCyclicDependencyTest(false);
configuration.setThrowExceptionWhenNoPackages(true);
/* add Rules */
final Rule daoRule = new Rule("dao");
daoRule.setComment("dao may not access presentation.");
daoRule.addPackage("test.com.seventytwomiles.dao.hibernate");
daoRule.addViolation("test.com.seventytwomiles.web.spring");
configuration.addRule(daoRule);
}
/**
* @see AbstractArchitectureRulesConfigurationTest
*/
public String getConfigurationFileName() {
/**
* Provide the name of the rules configuration file.
* File file is loaded from the classpath.
*/
return "architecture-rules.xml";
}
/**
* @see AbstractArchitectureRulesConfigurationTest#testArchitecture
*/
public void testArchitecture() {
/**
* Run the test via doTest(). If any rules are broken,
* or if the configuration can not be loaded properly,
* then the appropriate Exception will be thrown.
*/
assertTrue(doTests());
}
}
Mixed Configuration
Finally, you may mix programmatic and xml configuration. To do this, implement String getConfigurationFileName() to return “architecture-rules.xml” and continue to getConfiguraiton() in onSetup();. This will give you an instance of the configuration which is preloaded with the configuration found in the XML file. You may not programmatically add to or modify that configuration
Write your Ant task
If you would prefer to utilize Ant rather than write a unit test you may do so by defining a new taskdef for com.seventytwomiles.architecturerules.ant.AssertArchitectureTask.
Complete details for this Task can be found here and the list of required dependencies is located here.
By choosing to use the ant Task, you give up the ability to provide programmatic configuration All configuration will be read from the XML configuration file. If you must provide programmatic configuration, there is still an alternative Ant route, that utilizes the junit task. Details are here.
Execute your unit test
This is tool dependent. You probably know how to run your unit tests already.
Execute your Ant task
Use your ant build, or IDE.
1 Comment »
RSS feed for comments on this post · TrackBack URI
Posted by Openversion blog » Blog Archive » Project highlight: Architecture Rules
July 3, 2008 @ 8:46 am
[...] Getting Started [...]