<html lang="en-us">
<head>
<meta http-equiv="Content-Language" content="en-us">
<title>VerifyDesign Ant Task</title>
</head>
<body>
<h2>VerifyDesign Ant Task</h2>
<p>Creator: Dean Hiller (<a href="mailto:dean@xsoftware.biz">dean@xsoftware.biz</a>)</p>
<p>Feedback on task and documentation are welcome!</p>
<h3>Description</h3>
<p>Describe your design dependencies in an xml file, and this task will enforce them so they are not violated</p>
<p>For example, if there are three packages in one source tree
<ul>
<li>biz.xsoftware.presentation</li>
<li>biz.xsoftware.business</li>
<li>biz.xsoftware.dataaccess</li>
</ul>
and naturally presentation should only depend on business package, and business should depend on dataaccess. If you define your design this way and it is violated the build will fail when the verifydesign ant task is called. For example, if I created a class in biz.xsoftware.presentation and that class depended on a class in biz.xsoftware.dataaccess, the build would fail. This ensures the design actually follows what is documented(to some degree at least). This is especially nice with automated builds</p>
<h3>Getting Started</h3>
Download bcel jar from this link <a href="http://jakarta.apache.org/site/binindex.cgi#bcel">Bcel download</a> as this ant task uses the jar built from the <a href="http://jakarta.apache.org/bcel/">bcel project</a> on jakarta. Choose a directory to put in place of the XXXXXX below and add the ant-contrib jar as well as the bcel jar to that directory. You should now be all set to use the verifydesign element in your build.xml file as well as any other ant-contrib tasks. If you want to use this with 5.0jdk, you must download the bcel from the head of cvs until something better than 5.1 is released. This version of ant-contrib will work with both 5.0jdk and 1.4 jdk. 1.3 and before is not tested.
<pre>
<taskdef resource="net/sf/antcontrib/antlib.xml">
<classpath>
<fileset dir="XXXXXX">
<include name="**/*.jar"/>
</fileset>
</classpath>
</taskdef>
</pre>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">jar</td>
<td valign="top">The jar file of who's design we want to validate</td>
<td align="center" valign="top">required</td>
</tr>
<tr>
<td valign="top">design</td>
<td valign="top">The file that specifies the design in xml format(Examples below)</td>
<td align="center" valign="top">required</td>
</tr>
<tr>
<td valign="top">circularDesign</td>
<td valign="top">I strongly encourage you not to use this. This turns on allowing circular dependencies. There is always a way to get around circular dependencies, and I suggest you use it instead of introducing a circular dependency. If you think you have found one you can't work around, send me mail and maybe I can give you some ideas.</td>
<td align="center" valign="top">optional(default=false)</td>
</tr>
</table>
<h3>Parameters specified as nested elements</h3>
<p>No nested elements allowed
</p>
<h2>Design File</h2>
<p>
The design file is an xml based file specifying dependencies that are ok. Any dependencies not specified will not be allowed and will make sure the build fails. Examples of the contents of the design file can be found below.
</p>
<h3>design Root Element</h3>
<p>The root element of the design file is 'design'. Here are design's allowed subelements.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Subelement</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">package</td>
<td valign="top">subelement representing a package and it's dependencies</td>
<td align="center" valign="top">One or more Required</td>
</tr>
</table>
<h3>package SubElement</h3>
<p>Here are package elements allowed attributes and subelements</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">name</td>
<td valign="top">A smaller nickname for the package to reference in the depends subelement or attribute</td>
<td align="center" valign="top">Required</td>
</tr>
<tr>
<td valign="top">package</td>
<td valign="top">The package to compile such as biz.xsoftware.presentation</td>
<td align="center" valign="top">Required</td>
</tr>
<tr>
<td valign="top">depends</td>
<td valign="top">Contains one and only one 'name' of a package to depend on(taken from name attribute above). If you want to specify more, use the depends subelement</td>
<td align="center" valign="top">Optional(Default=no dependencies)</td>
</tr>
<tr>
<td valign="top">subpackages</td>
<td valign="top">Can be set to include or exclude. Basically allows classes in subpackages to be part of the package specified.(see examples below)</td>
<td align="center" valign="top">Optional(default=exclude)</td>
</tr>
<tr>
<td valign="top">needdeclarations</td>
<td valign="top">Can be set to true or false. True means if other packages depend on this package, a depends subelement or attribute must exist stating the dependency. False means other packages need not declare they depend on this package. This should be used sparingly for things like java.lang. By default "java" package and all subpackages are set to false. This can be overridden if you need however so you can make sure only certain packages depend on java.util or something if you really need that. (see examples below)</td>
<td align="center" valign="top">Optional(default=true)</td>
</tr>
</table>
<br/>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Subelement</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">depends</td>
<td valign="top">Contains one and only one 'name' of a package to depend on(taken from name attribute above)</td>
<td align="center" valign="top">One or more Optional</td>
</tr>
</table>
<h3>depends SubElement</h3>
Contents contain the 'name' of a package found in the package element's name attribute
<h3>Examples</h3>
<h4>Ant's build.xml File</h4>
<pre>
<verifydesign jar="application.jar" design="design.xml"/>
</pre>
<p>
That is simple enough. application.jar is the jar I am verifying the design of. design.xml contains the design I want the jar file to adhere to. If it does not adhere to that design, the build fails. Now let's move on to define the contents of design.xml file.
</p>
<h4>design.xml File</h4>
<pre>
These lines would be in dependencies.xml.....
<design>
<package name="alljavax" package="javax" subpackages="include" needdeclarations="false"/>
<package name="util" package="biz.xsoftware.util" subpackages="include"/>
<package name="dataaccess" package="biz.xsoftware.dataaccess"/>
<package name="business" package="biz.xsoftware.business" depends="dataaccess"/>
<package name="presentation" package="biz.xsoftware.presentation">
<depends>business</depends>
<depends>util</depends>
</package>
</design>
</pre>
<p>Notice in this example, if biz.xsoftware.dataaccess.XYZClass depended on biz.xsoftware.util.Util, the build would fail since that package dependency is not defined. Similarly, any class in biz.xsoftware.presentation cannot depend on any class in biz.xsoftware.dataaccess</p>
<p>Also, notice that biz.xsoftware.presentation.Gui is allowed to depend on biz.xsoftware.util.pres.ClassInSubpackage because subpackages is set to include. This allows subpackages of biz.xsoftware.util to also be included in the design without having to define every subpackage.</p>
<p>Lastly, notice the first line so javax and all javax subpackages can be depended on without declaring them. Use this sparingly though as sometimes you might want to isolate dependencies like depending on JMX to a certain package. For example, you may want only biz.xsoftware.management to depend on JMX and nothing else to depend on it. If you declare the same declaration I declared here for javax, you will not be able to guarantee that.</p>
<h4>The wad design.xml file</h4>
If you really want to, you could design for a wad. This is not suggested and if you want to do this, don't use this ant task please.
<pre>
<design>
<package name="wad" package="<default package>" subpackages="include"/>
</design>
</pre>
<h4>Including subpackages design.xml</h4>
<pre>
<design>
<package name="service1" package="biz.xsoftware.service1" subpackages="include"/>
<package name="client1" package="biz.xsoftware.client1" depends="service1"/>
<package name="service2" package="biz.xsoftware.service2"/>
<package name="client2" package="biz.xsoftware.client2" depends="service2" subpackages="include"/>
</design>
</pre>
<p>
Note that here for service 1, classes in package biz.xsoftware.client1 can depend on any classes in biz.xsoftware.service1 and can also depend on classes in subpackages of biz.xsoftware.service1.
</p>
<p>
Note that for service 2, classes in biz.xsoftware.client2 and client2's subpackages are all allowed to depend on classes in biz.xsoftware.service2.
</p>
<h4>One Design Note</h4>
One big note to consider, there is one design dependency that verifydesign cannot see from the class file. This is due to the String constants(This only happens with static final <b>Strings</b> and static final <b>primitives</b> being compiled into the class file. Here is example code demonstrating this task cannot catch these dependencies....
<pre>
public class Client {
public void fakeMethod() {
String s = Dependency.CONSTANT; //verifydesign task can't tell this depends on
//DependencyClass as that info is lost after compiling
}
}
public class DependencyClass {
public static final String CONSTANT = "asdf";
}
</pre>
<hr>
<p align="center">Copyright © 2002-2004 Ant-Contrib Project. All
rights Reserved.</p>
</body>
</html>
distrib
>
Fedora
>
13
>
i386
>
media
>
os
>
by-pkgid
>
8c4c0a6398d7e2b9ffef69a1dc5840d8
>
files
>
38
