Important Announcement
PubHTML5 Scheduled Server Maintenance on (GMT) Sunday, June 26th, 2:00 am - 8:00 am.
PubHTML5 site will be inoperative during the times indicated!
EN
Home Explore Java.Power.Tools

Java.Power.Tools

Published by jack.zhang, 2014-07-28 04:28:37

Description: Java Power Tools
Overview
All true craftsmen need the best tools to do their finest work, and programmers are no
different. Java Power Tools delivers 30 open source tools designed to improve the
development practices of Java developers in any size team or organization. Each chapter
includes a series of short articles about one particular tool -- whether it's for build systems,
version control, or other aspects of the development process -- giving you the equivalent
of 30 short reference books in one package. No matter which development method your
team chooses, whether it's Agile, RUP, XP, SCRUM, or one of many others available, Java
Power Tools provides practical techniques and tools to help you optimize the process. The
book discusses key Java development problem areas and best practices, and focuses on
open source tools that can help increase productivity in each area of the development
cycle, including:
 Build tools including Ant and Maven 2
 Version control tools

Search

Read the Text Version

Java Power Tools This would display the Trac ticket # 123. The plug-in configuration for our Trac issue management system would be the following: <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>changes-maven-plugin</artifactId> <configuration> <link_template>%URL%/modelplanes/tickets/%ISSUE%</link_template> </configuration> </plugin> Figure 29-6 shows an example of a the generated change report. Figure 29-6. Example of a change report Another more development-oriented option is to use your SCM repository to track changes. The changelog plug-in generates a nice report describing which files have been changed and by whom: <reporting> <plugins> ... <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>changelog-maven-plugin</artifactId> </plugin> </plugins> </reporting> 1000

Java Power Tools Finally, if you use @todo tags to remind you of things to be done (which is a good coding practice), the taglist report will generate a list of all the items marked @todo or TODO: <reporting> <plugins> ... <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>taglist-maven-plugin</artifactId> </plugin> </plugins> </reporting> Section 29.4. Creating a Dedicated Maven Site Project Contributed by: Eric Redmond Although any individual project can have its own site, it is often easier to manage a separate site project. In the following sections, we will look at how to build and customize a separate site project. However, all of this information can just as easily apply to a project that contains code as well. The simplest way to bootstrap any Maven site development is to use the maven-archetype-site archetype, as shown here: $ mvn archetype:create -DarchetypeGroupId=org.apache.maven.archetypes \ -DarchetypeArtifactId=maven-archetype-site \ -DarchetypeVersion=1.0 \ -DgroupId=com.mycompany \ -DartifactId= This will generate a sample Maven site project, which may be built by executing the site build lifecycle. The structure of your new Maven site project should look like this: my-site |-- pom.xml `-- src `-- site |-- apt | |-- format.apt | `-- index.apt |-- fml 1001

Java Power Tools | `-- faq.fml |-- fr | |-- apt | | |-- format.apt | | `-- index.apt | |-- fml | | `-- faq.fml | `-- xdoc | `-- xdoc.xml |-- xdoc | `-- xdoc.xml |-- site.xml `-- site_fr.xml The items to note in the above structure are the site.xml file and the directories under src/site: apt, fml and xdoc; each representing a document notation type. You should have an index file somewhere (for example, a file called index.apt in the site/apt directory). This will be converted to a file called index.html, which will become the home page of your site. Without this file, Maven will generate a very boring home page. Finally, the site_fr.xml and src/site/fr subdirectories contain a French language version of the documents, rounding out Maven's commitment to built-in internationalization. To activate this locale, you simply add the French language version to the site plug-in's configuration in the POM, as shown here: <project> ... <build> <plugins> <plugin> <artifactId>maven-site-plugin</artifactId> <configuration> <locales>en,fr</locales> </configuration> </plugin> </plugins> </build> </project> Section 29.5. Defining the Site Outline Contributed by: Eric Redmond 1002

Java Power Tools The site.xml file is responsible for the structure of the site as a whole, defining the site's banners, the links (upper-right corner by default), and the left-hand side menu. A simple example is shown here: Code View: <project name=\"Spitfire\"> <bannerLeft> <name>Spitfire</name> <src>/images/spitfire-logo.jpg</src> <href>http://spitfire.mycompany.com/</href> </bannerLeft> <bannerRight> <src>/images/hurricane-small.jpg</src> </bannerRight> <body> <links> <item name=\"Apache\" href=\"http://www.apache.org/\" /> <item name=\"Maven 2\" href=\"http://maven.apache.org/maven2/\"/> <item name=\"Hibernate\" href=\"http://www.hibernate.org/\"/> </links> <menu name=\"The Spitfire project\"> <item name=\"Home\" href=\"index.html\"/> <item name=\"APT Format\" href=\"format.html\"/> <item name=\"FAQ\" href=\"faq.html\"/> <item name=\"Xdoc Example\" href=\"xdoc.html\"/> </menu> ${reports} </body> </project> Note that links in the menu defined below have similar names to the documents above, yet end with .html. This is because each of the document markups are converted to HTML by the site plug-in, more specifically, by Doxia. A common initial requirement is to incorporate project and/or company logos. This is easy to do. The <src> tag in each banner points to an image to be displayed there. You can either use an absolute URL, or refer to a local resource within your web site project. To do the latter, just place any images you need to access in the site/resources directory. From here, you can access them using a local reference such as the \"/images/spitfire-logo.jpg\" shown above. 1003

Java Power Tools You may or may not want to include the standard Maven project reports in your custom site. If you do, you need to include the ${reports} tag shown in the site.xml file above. This will be replaced by the \"Project Information\" and \"Project Reports\" menus that you have configured in your pom.xml file. The resulting web site is illustrated in Figure 29-7. Figure 29-7. A simple customized web site The site phase can easily generate sites of different languages. All you need to do is create a site descriptor file similar to the file above, yet suffix the filename with the language code of your choice. The archetype created a French language version for you, site_fr.xml. At this point, Maven will look for a matching language directory under src/site and generate that documentation for an audience of that particular language (usually by a web browser's language settings). If no matching language is found, the site.xml's language is the default (presumed to be English). Section 29.6. The Maven Site Generation Architecture Contributed by: Eric Redmond You can use a number of different formats to build the content of your Maven 2 web site. This is largely a matter of taste. We will examine the basic architecture of the Maven 2 content generation system and run through the formats that you can use. 29.6.1. Doxia The heart of the Maven site plug-in is the Doxia project, which is a self-contained subproject of Maven (http://maven.apache.org/doxia). Doxia is responsible for converting your chosen document markup to the html that can be deployed to a web site. 1004

Java Power Tools Doxia also has the ability to convert a document from any supported markup to any other supported markup. It does this with parsers and sinks. A Doxia parser implements the org.apache.maven.doxia.parser.Parser Plexus role and is responsible for converting the implemented markup into a given sink. A Doxia sink implements the org.apache.maven.doxia.sink.Sink Plexus role and caters for a particular output format, for example XHTML or PDF. This is important to know if you ever decide to write your own modules for Doxia to support. 29.6.2. APT Almost Plain Text, or APT,can be considered the default documentation method for Maven projects. It is a simple wiki-like syntax that is easily converted to a Doxia sink. If you built the site generated by maven-archetype-site, navigate to target/site/format.html and you will be treated to a comprehensive guide for using APT. A simple example is shown here: Code View: ----- The Hotel Database Vision Statement ----- The Wakaleo Team ----- January 2006 Introduction One of the nicer features of Maven is the ability to create an internal technical web site at very little cost. Maven 2 extends this functionality, and gives you powerful new ways to generate site content... * Sub-section title Team communication is an essential part of any project. And wasting time looking for technical project information can be costly and frustrating. Clearly, any IT project will benefit from having its own dedicated technical web site... * Item 1 * Item 2 * Item 2.1 1005

Java Power Tools * Item 2.2 The APT format is documented in excruciating detail on the Maven site, so we will just take you through the main things that you should know to get started. Your APT document typically begins with a heading. The heading starts with a line of dashes, and contains three parts—the document title, the author, and the date—separated by lines of dashes: ----- The Hotel Database Vision Statement ----- The Wakaleo Team ----- January 2006 Indentation and line spacing is important for APT. For example, section titles and subtitles cannot have any indenting, whereas normal text does need to be indented (more precisely, the first line of a normal paragraph needs to be indented). Subtitles are indicated with asterisks. You need a blank line between every element (paragraph, title, list item, and so on): Main Title Say some stuff... * Sub-title Some more detailed stuff... ** Sub-sub-title The heart of the matter... You can see this in action in Figure 29-8. Figure 29-8. Some APT titles 1006

Java Power Tools You can also include lists, tables, and other formatting niceties (see Figure 29-9). For example, the following listing illustrates a definition list and an ordinary bullet-point list: The application is comprised of several main packages: [com.mycompany.myapp.core] Core interface classes [com.mycompany.myapp.core.impl] Core implementation classes [] These are cool packages for several reasons * The interfaces rock * The implementations are groovy * They are really well documented [] Note how lists need to be terminated by an empty list element (\"[]\"). Figure 29-9. APT lists 1007

Java Power Tools It is often useful to include snippets of code in your documentation, to show how to use or configure a class, for example. You can do this by surrounding the code listing with lines of dashes, as shown here: You can configure this class in Spring as follows: ---------------------------------------- <bean id=\"taxCalculator\" class=\"com.mycompany.myapp.core.impl.TaxCalculatorImpl\" > ... </bean> ---------------------------------------- If you want to include images in your APT files, you need to add them in the resources directory. For example, in the following directory structure, we have placed a PNG image in the src/site/resources/images directory: my-site |-- pom.xml `-- src `-- site |-- ... |-- resources `-- images `-- domain-model.png |-- site.xml `-- site_fr.xml You can also refer to these images in your document as follows: The domain model is illustrated in the following class diagram: [images/domain-model.png] The application domain model 1008

Java Power Tools 29.6.3. FML FML is FAQ (frequently asked questions) markup language, and it specializes in the creation of the ubiquitous FAQ document. An example is as follows: Code View: <faqs id=\"faqs1\"> <part id=\"part1\"> <faq id=\"faq1\"> <question>What is a good question?</question> <answer> <p>Any valid XHTML can be placed in the <code>answer</code> element</p> </answer> </faq> </part> </faqs> The FML document can have any number of parts, and each part may have any number of FAQs, each with one question and one answer. When the document is generated, it will place all questions at the top of the page as links, which anchor to the answers later in the page (see Figure 29-10). Figure 29-10. A simple Maven-generated FAQ screen 29.6.4. XDoc XDoc is an XML markup for writing documents, and has been around since the early days of Maven 1 and Ant. It is similar to HTML, but it is document-centric with extra elements for sections and more constraints. All XDoc documents must be under the xdoc directory, with a .xml extension. Its support is mostly for historical reasons, and it is recommended that you write new documentation in APT format. 1009

Java Power Tools Section 29.7. Using Snippets Contributed by: Eric Redmond A useful feature of Doxia are snippets. Snippets are macros that are given a file and an id. They can be a useful way of inserting or referencing key blocks of code from within your project in your technical documentation. You define a snippet as follows: %{snippet|id= You define a snippet by encapsulating a block of code in specially formatted comments. The macro will search the file for the comment START SNIPPET: myID and ending comment END SNIPPET: myID. For example, add the following to your POM: <project> ... <!-- START SNIPPET: props --> <properties> <my.prop>value</my.prop> </properties> <!-- END SNIPPET: props --> </project> Then add the following to your format.apt file: %{snippet|id= Now run the site phase, and be amazed! The block of code will now figure in the generated web page (see Figure 29-11). Figure 29-11. An example of a snippet Hint: rather than running the site phase, try running the site:run goal. It will launch your documents under a web container accessible from port 8080 that will show your changes in real time. Section 29.8. Customizing the Look and Feel of Your Site Contributed by: Eric Redmond Whether it's just the company logo in the corner of the screen, or the whole site repainted using your company fonts and colors, adding that personal touch to your Maven site can do wonders for its appeal. You'd be surprised how many people pay more attention when 1010

Java Power Tools the site matches the company colors! Maven provides a number of ways for you to customize the look and feel of your Maven web site. Here, we look at several ways to add your own personal touch. 29.8.1. Changing Skins Like many sites, the look-and-feel of a Maven site is determined by what we call a \"skin.\" A skin is, in fact, a collection of CSS stylesheets and graphical resources. Changing skins in Maven is easy. Just alter your POM, and voilà! Your entire site's look and feel has been altered. Better yet, it is all consistent. To switch the my-site project to use the Stylus theme, alter the site.xml file (not the POM): <project> ... <skin> <groupId>org.apache.maven.skins</groupId> <artifactId>maven-stylus-skin</artifactId> <version>1.0</version> </skin> </project> This style is illustrated in Figure 29-12. The list of default skins available from the Maven Central Repository can be found at http://repo1.maven.org/maven2/org/apache/maven/skins/. At the time of this writing, the list is:  maven-classic-skin  maven-default-skin  maven-stylus-skin As you probably guessed, maven-default-skin is the default. Figure 29-12. The Stylus skin 1011

Java Power Tools 29.8.2. Creating Your Own Style The predefined Maven skins give you some flexibility, and they can help you learn how to customize your site's look and feel. They are often just fine for internal sites with a limited, technically minded audience. However, there are times when the default skins just don't cut it. Let's see how to create your own personalized skin. First, create a project with the following layout: my-skin |-- pom.xml `-- src `-- main `-- resources |-- css | `-- maven-theme.css `-- images You will also need a simple pom.xml: <project> <modelVersion>4.0.0</modelVersion> <groupId>com.mycompany</groupId> <artifactId>my-skin</artifactId> <version>1.0-SNAPSHOT</version> </project> The important file in a custom skin is the maven-theme.css. Also note the src/main/resource/images directory that allows you to add images into your CSS, accessible as \"/images/my-image.ext.\" Most control of the CSS is via the basics such as body or a, but there are a few important CSS ids generated by default: 1012

Java Power Tools breadcrumbs a sequence of data at the top of the page leftColumn represents the left column of the page navcolumn wraps the navigation elements in the left column banner contains the left and right banners defined in the site.xml bodyColumn wraps the contentBox of the page contentBox contains the main content of the page footer contains the data generated as a page footer 29.8.3. Velocity Manipulation Skin manipulation is nice to change the look of your site, but in order to change the way the site is generated requires creating your own Velocity (.vm) file. Apache Velocity is a templating engine that has been around for years, has proven its metal in projects such as Apache Turbine, and is a simple method for allowing users to overwrite the default templates. Rather than starting from scratch, it is far simpler to download the default default-site.vm file and manipulate it. The default renderer is available under the doxia-site-rendered project source code, available for download under the Doxia project. Doxia is available from the subversion repository at http://svn.apache.org/repos/asf/maven/doxia/trunk/ (if not found there, check the Doxia web site at http://maven.apache.org/doxia. From there, the doxia-site renderer project's resource contains the template, at doxia-site-renderer/src/main/resources/org/apache/maven/doxia/siterenderer /resources/default-site.vm. Copy this file to your project at src/site/my-site.vm, and point your my-site project's pom.xml to utilize it: <project> ... <build> <plugins> <plugin> <artifactId>maven-site-plugin</artifactId> <configuration> <templateFile>src/site/my-site.vm</templateFile> </configuration> </plugin> </plugins> </build> If you look at the my-site.vm, you will notice the XHTML and CSS generated by it. This gives you the power to alter 1013

Java Power Tools the structure of your generated Maven site, as well as allow your custom skins more control than merely the default (perhaps by adding more spans or more types of CSS classes). Or, better yet, you can add the template to your skin to src/main/resources/META-INF/maven/site.vm. This way, when a project uses your skin, it automatically uses your template. Section 29.9. Distributing Your Site Contributed by: Eric Redmond The final step in site generation is publishing it to a location from which a public web server can access it. There is a special element in the distributionManagement element called site, which gives the location and method of distribution. In your my-site POM, you will notice the element has been added for you. Now you merely need to set it like any other Maven distribution. The example uses secure copy protocol (scp): <project> ... <distributionManagement> <site> <id>website</id> <url>scp://webhost.company.com/www/website</url> </site> </distributionManagement> </project> If you need to supply a username and password when you copy to the remote site, you will also need to provide this information in your settings.xml file (see Section 2.7): <settings> ... <servers> <server> <id>website</id> <username>scott</username> <password>tiger</password> </server> </servers> </settings> Setting up an enterprise repository was covered in Section 2.19. With a suitable distribution setup, you merely run the site-deploy phase (which has bound to it the site:site.deploy goal): 1014

Java Power Tools mvn site-deploy That's it! Maven will generate the documentation using your chosen template and skin, and copy those files to the specified location. Chapter 30. Automatically Generating Technical Documentation Introduction Visualizing a Database Structure with SchemaSpy Generating Source Code Documentation with Doxygen Embedding UML Diagrams in Your Javadoc with UmlGraph Conclusion 30.1. Introduction Good-quality, reliable, and up-to-date technical documentation on a project is generally regarded as a Good Thing. Technical documentation is a great aid for the developers who are assigned to maintaining the product, once the original development team has been dispersed. Technical documentation can also help new developers come up to speed when they join a project. However, good technical documentation comes at a cost—the more documentation you have, the more effort you need to put into maintaining this documentation. And the effort that goes into maintaining technical documentation is, of course, effort that could be spent on writing code. In this chapter, we look at three tools that you can use to reduce the time you spend on maintaining your technical documentation, without compromising too much on the quality: SchemaSpy, for database models, and Doxygen and UmlGraph for source code documentation. Section 30.1. Introduction Visualizing a Database Structure with SchemaSpy Generating Source Code Documentation with Doxygen Embedding UML Diagrams in Your Javadoc with UmlGraph Conclusion 1015

Java Power Tools 30.1. Introduction Good-quality, reliable, and up-to-date technical documentation on a project is generally regarded as a Good Thing. Technical documentation is a great aid for the developers who are assigned to maintaining the product, once the original development team has been dispersed. Technical documentation can also help new developers come up to speed when they join a project. However, good technical documentation comes at a cost—the more documentation you have, the more effort you need to put into maintaining this documentation. And the effort that goes into maintaining technical documentation is, of course, effort that could be spent on writing code. In this chapter, we look at three tools that you can use to reduce the time you spend on maintaining your technical documentation, without compromising too much on the quality: SchemaSpy, for database models, and Doxygen and UmlGraph for source code documentation. Section 30.2. Visualizing a Database Structure with SchemaSpy 30.2.1. Introduction Relational databases play a key role in a majority of today's software applications, and database schemas are without doubt one of the most widely recognized and understood models in the IT field. Although they are relatively low-level, and lack some of the abstraction of an object-oriented class model, they can still be an extremely valuable asset when it comes to trying to understand the architecture of an application, both during the development phase and also during product maintenance once the application is in production. However, the main problem with database schemas, like all other design models and documents, is keeping them up-to-date. As a rule, the chances of a design document being kept up to date are inversely proportional to the effort required to maintain them. That is to say, if human intervention is required to maintain a document, it will soon become out of date in all but the most rigorous of projects. SchemaSpy can be a valuable asset in maintaining and publishing these models. Like Javadoc for Java source code, SchemaSpy provides an accurate, up-to-date view of the database structure, generated automatically from the actual database. As an automated tool, SchemaSpy incurs very little cost to set up and virtually no cost to maintain—the diagrams are automatically updated as the database schema evolves. This alone is a valuable time-saver for both development and maintenance teams. 30.2.2. An Overview of SchemaSpy Based on material contributed by: Masoud Kalali 1016

Java Power Tools SchemaSpy [111] is a free, open source Java tool written by John Currier that can generate a rich interactive HTML view of your database, showing detailed information about the tables, views and relations that make up the database. SchemaSpy works by analyzing the metadata from a JDBC connection, and producing a set of detailed HTML reports describing the database. The HTML reports are richly annotated with hyperlinks letting you navigate between parents and children by simply clicking on the appropriate foreign key field. Primary keys, foreign keys, and indexes are visible at a glance. [111] http://schemaspy.sourceforge.net/ Figure 30-1 shows a view of a typical SchemaSpy report. Information is categorized under a number of intuitively-titled tabs, such as \"Tables,\" \"Relationships,\" \"Utility Tables,\" and so on. Hyperlinks make it easy to drill down to see details about particular tables. Figure 30-1. SchemaSpy provides a detailed view of your database structure 1017

Java Power Tools SchemaSpy displays a wealth of useful information about your database, including:  A list of all tables and views in the database, displayed appropriately enough in the Tables tab. This view also shows the number of rows in each table, as well as the number of parents and children for each table (see [4] in Figure 30-1).  A graphical view of the relationships between tables in the database (see Figure 30-2). This view provides a powerful and succinct overview of the database structure, much appreciated by developers. This diagram is generated using Graphviz, and is enriched with HTML map and area tags that allow the user to click directly on a table in order to display the details for that table.  Detailed information about any constraints present in the database (in the Constraints tab).  A list of utility tables. Utility tables are tables that have no relation to any other tables. Utilities tables are typically used to store information such as counters. Any other tables appearing in this list should be considered suspect, and should be checked for possible missing foreign keys.  Anomalies that are present in your database. This is another nice feature, where SchemaSpy checks your database for simple structural errors. SchemaSpy can detect several types of anomalies, such as columns that are flagged as both \"nullable\" and \"must be unique,\" single column tables, tables without indexes, foreign keys that appear to be missing, and so on.  A list of all the columns present in the database with detailed information such as related columns, constraints, and comments. This can act as a handy data dictionary, especially if the columns have been commented in the SQL creation script. As shown in (3) in Figure 30-1, SchemaSpy can also be used to generate an XML representation of your database, as well as the correct drop and create sequences for database tables. Drop and create sequences let you avoid those unresolved constraints during creation and dependency problems when you create or drop tables from the database. Figure 30-2. SchemaSpy generates an Entity-Relationship model of your database 1018

Java Power Tools The graphical view illustrated in Figure 30-2 is a great way of getting a global picture of your database structure. If you are interested in a particular table, it is easy to drill down into a table for more details. If you click on a table, either in the tables list or from one of the graphs, SchemaSpy will display detailed information about that table (see Figure 30-3). This view contains information such as:  Column details—name, type, constraints, default value, related columns with table name, and so on  Index-related information: index name, type, column(s) name  A diagram showing relations with other tables Figure 30-3. Details about a given table 1019

Java Power Tools Once again, you can click on any of these tables to drill down to a more detailed view about that specific table. Each table also displays some numbers in the bottom left and right corners. These numbers represent, respectively, how many parent tables a given table is associated with (left corner), and how many children it has (right corner). 30.2.3. Installing SchemaSpy Now that we have a better idea of what SchemaSpy does, let's see how to install it. SchemaSpy is bundled as a simple JAR file that you can download SchemaSpy from the project web site. [*] [*] http://schemaspy.sourceforge.net/ SchemaSpy relies on the Graphviz library to generate the graphical views of the database structure. Graphviz is a collection of tools for manipulating and generating graphs, based on the dot language. Graphviz is not a Java tool but, rather, a native executable that SchemaSpy invokes from the command line. Therefore SchemaSpy expects to find the 1020

Java Power Tools Graphviz dot application on your PATH. You can download the Graphviz package from the Graphviz web site. [113] There are installation packages for Windows and for most flavors of UNIX and Linux. Alternatively, you can download the source code and compile and install the library following a fairly standard Unix installation procedure, which is, again, well documented on the Graphviz web site. [113] http://www.graphviz.org/ 30.2.4. Using SchemaSpy Based on material contributed by: Masoud Kalali By default, SchemaSpy comes as a no-frills, command-line tool. You run it simply by executing the Jar file, using a set of command-line options to specify the connection details for your database. A typical execution from the command line looks something like this: $ java -jar schemaSpy_3.1.1.jar \ -t mysql \ -u root \ -o db-schema-report \ -host localhost \ -db bookstore \ -s bookstore \ -cp mysql-connector-java-5.0.5.jar \ Using database properties: [/usr/local/tools/schemaSpy/schemaSpy_3.1.1.jar]/net/sourceforge/schemaspy /dbTypes/mysql.properties Connected to MySQL - 5.0.24a-Debian_9ubuntu2-log Gathering schema details.......................................................(0sec) Writing/graphing summary........(12sec) Writing/graphing results.......................................................(0sec) Wrote relationship details of 55 tables/views to directory 'db-schema-report' in 13 seconds. Start with db-schema-report/index.html You need to provide the JDBC driver yourself, either on the Java classpath or using the -cp option. The other options are described briefly here: 1021

Java Power Tools -t databaseType This parameter lets you specify the database type you are working with. SchemaSpy provides built-in support for most of the major databases, including Oracle (\"ora,\" which is the default value, or \"orathin\" for the 100% Java type-4 JDBC driver.), mysql, pgsql, db2, and mssql (Microsoft SQL Server). Database configurations are stored in properties files, which can be found in the schemaSpy.jar file, under the net/sourceforge/schemaspy/dbTypes directory. If your database is not supported, you can copy and adapt one of these properties files, and provide the path to your own customized properties file instead. -db dbName The name of database that SchemaSpy will analyze. -u user A valid database user with at least read access to the target database. -p password The password for this user. -o outputDirectory The generated HTML report will be placed in this directory. Using SchemaSpy from the command line is a bit unwieldy. In the next two sections, we'll look at how to automate the process with Ant and Maven. 30.2.5. Using SchemaSpy in Ant A tool like SchemaSpy really begins to excel when you can integrate it into your build process. At the time of writing, SchemaSpy did not come packaged with an Ant task, but it is possible to execute the SchemaSpy JAR file from within Ant using the <java> tag. SchemaSpy comes packaged as an executable JAR file, so you need to invoke the <java> tag using the jar attribute to specify the SchemaSpy JAR file. You also need to provide the JDBC driver using the -cp command line option. You provide the command-line options simply by using the <arg> parameter. Note that SchemaSpy does accept command-line 1022

Java Power Tools options using a \"property=value\" syntax, which saves some space and reduces the number of <arg> lines. This technique is illustrated here: Code View: <!-- SchemaSpy property values --> <property name=\"schemaspy.report.dir\" value=\"${build.dir}/schemaspy\"/> <property name=\"schemaspy.jdbc.driver\" value=\"${lib}/mysql-connector- java-5.0.5.jar\"/> <property name=\"schemaspy.database\" value=\"mydatabase\" /> <property name=\"schemaspy.driverClassName\" value=\"com.mysql .jdbc.Driver\" /> <property name=\"schemaspy.database.host\" value=\"localhost\" /> <property name=\"schemaspy.username\" value=\"scott\" /> <property name=\"schemaspy.password\" value=\"tiger\" /> // ... <target name=\"schemaspy\"> <echo>Generating database schemas in ${schemaspy.report.dir}</echo> <java jar=\"${lib}/schemaSpy_3.1.1.jar\" output=\"${schemaspy.report.dir}/schemaspy-out.log\" error=\"${schemaspy.report.dir}/schemaspy-error.log\" fork=\"true\"> <arg line=\"-t=mysql\"/> <arg line=\"-db=${schemaspy.database}\"/> <arg line=\"-u=${schemaspy.username}\"/> <arg line=\"-p=${schemaspy.password}\"/> <arg line=\"-cp=${schemaspy.jdbc.driver}\"/> <arg line=\"-host=${schemaspy.database.host}\"/> <arg line=\"-o=${schemaspy.report.dir}\"/> </java> </target> This will generate the SchemaSpy web pages into the target/schemaspy directory. 30.2.6. Using SchemaSpy in Maven If you are using Maven on your project, there are obvious advantages to incorporating SchemaSpy reports in the automatically generated Maven site. At the time of writing, however, there is no Maven 2 plug-in for SchemaSpy. 1023

Java Power Tools Integrating SchemaSpy with Maven is not a simple task. For one thing, SchemaSpy is bundled as an executable tool, not as an API, so you won't find it in any Maven repositories. You need to download and install it yourself (along with Graphvis), and make it available to Maven. In its simplest form, you can get Maven to generate the SchemaSpy reports during Maven site generation by incorporating a slightly adapted version of the Ant script listed above directly within your POM file: Code View: </project> ... <build> <!-- SchemaSpy --> <plugin> <artifactId>maven-antrun-plugin</artifactId> <executions> <execution> <phase>site</phase> <configuration> <tasks> <echo> Generating database schemas in ${schemaspy.report.dir} </echo> <java jar=\"${schemaspy.home}/schemaSpy_${schemaspy.version}.jar\" output=\"${schemaspy.report.dir}/schemaspy-out.log\" error=\"${schemaspy.report.dir}/schemaspy-error.log\" fork=\"true\"> <arg line=\"-t=mysql\" /> <arg line=\"-db=${schemaspy.database}\" /> <arg line=\"-u=${schemaspy.username}\" /> <arg line=\"-p=${schemaspy.password}\" /> <arg line=\"-cp=${schemaspy.jdbc.driver}\" /> <arg line=\"-host=${schemaspy.database.host}\" /> <arg line=\"-o=${schemaspy.report.dir}\" /> </java> </tasks> </configuration> <goals> <goal>run</goal> </goals> </execution> </executions> </plugin> </plugins> </build> 1024

Java Power Tools <dependencies> ... <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>5.0.5</version> </dependency> ... </dependencies> ... <properties> <schemaspy.home>${user.home}/.schemaspy</schemaspy.home> <schemaspy.version>3.1.1</schemaspy.version> <schemaspy.report.dir>${project.build.directory}/site/schemaspy</schemaspy. report.dir> <schemaspy.jdbc.driver> ${settings.localRepository}/mysql/mysql-connector-java/5.0.5/mysql-connector- java-5.0.5.jar </schemaspy.jdbc.driver> <schemaspy.database>planestore_test</schemaspy.database> <schemaspy.driverClassName>com.mysql.jdbc.Driver</schemaspy.driverClassName> <schemaspy.username>scott</schemaspy.username> <schemaspy.password>tiger</schemaspy.password> <schemaspy.database.host>localhost</schemaspy.database.host> </properties> </project> We have placed the property values in a <properties> block at the end of the POM file. In a real-world application, these properties would probably find themselves placed in profiles (see Section 2.4.9\" in Section 2.4) and/or in the local user's settings.xml file (see Section 2.7). This will generate the SchemaSpy reports in a subdirectory of the site directory called schemaspy. We need to pass a reference to the JDBC library we are using to SchemaSpy via the -cp command-line parameter. Because this JDBC library will certainly be listed in the project dependencies, one of the simpler approaches is to use the ${settings.localRepository} property to refer to the copy of this library in our local repository. 1025

Java Power Tools Now we can generate the SchemaSpy report whenever the Maven site is built, we need to display it. Because SchemaSpy does not have a report plug-in, it is not easy to integrate a link to the SchemaSpy pages into the standard Maven report list. The simplest approach is to add a manual link to the page at an appropriate place on your site. (Chapter 29 discussed how to customize your Maven site in more detail.) Section 30.3. Generating Source Code Documentation with Doxygen 30.3.1. Introduction Doxygen is a tool for generating technical documentation from your Java source code [*] written by Dimitri van Heesch. Doxygen is similar to the standard Javadoc tool: both tools analyze Java source code to produce interactive HTML documentation. However, Doxygen goes further than Javadoc: as well as documenting the classes, it also can generate a variety of diagrams, such as class diagrams, collaboration diagrams, and dependency graphs. Doxygen is not limited to Java source code. It also can document C, C++, and C# projects. It also can produce technical documentation in other formats, such as PDF, RTF, or LaTeX. [*] http:// www.doxygen.org Another advantage of Doxygen is that it is much less obtrusive than Javadoc, making it easier to document your classes without having to think about formatting issues. For example, Doxygen will automatically recognize references to other classes (no need for @link commands), and uses a simple wiki-style notation for formatting, eliminating the need to add HTML code within your comments. This smooths the documentation process and makes for higher-quality, more relevent technical documentation. 30.3.2. The Doxygen Reports Doxygen generates a rich set of browsable HTML documentation (see Figure 30-4). By way of comparison, Doxygen-generated documentation is similar to but more extensive than documentation generated by Javadoc. In addition to the lists of classes, packages, and files that you would expect, Doxygen can generate UML class diagrams and collaboration diagrams which can provide a better understanding of how the classes work together. Collaboration diagrams are based on structural relations (inheritance and member variables), but they do not include class usage within individual methods. Figure 30-4. View of a class in the Doxygen report 1026

Java Power Tools The reports also include annotated and cross-referenced source code in HTML form. 30.3.3. Installing Doxygen Doxygen is not a Java API: it is a command-line utility that you need to download and install on your machine. There are precompiled binary installations for many Linux platforms such as Red Hat, SuSE, and the Debian family. Otherwise, you will need to download, compile, and install the tool. This fairly straightforward procedure is described here. First, download and unpack the Doxygen source code: $ tar xvfz doxygen-1.5.2.src.tar.gz Next, configure and compile the source code: $ ./configure $ make Finally, to install, just run the standard \"make install\": # make install If you run into any trouble, the Doxygen web site has some useful tips for particular [*] installation issues with certain platforms. [*] http://www.stack.nl/~dimitri/doxygen/install.html On Windows, you can use the packaged Windows installer to install Doxygen very easily. Like SchemaSpy (see Section 30.2), Doxygen uses Graphviz to generate its graphs. So you will need to download and install this tool as well to get the best our of Doxygen. This is fairly straightforward and is explained in Section 30.2.3,\" in Section 30.2. 1027

Java Power Tools 30.3.4. Configuring Doxygen Before you can run Doxygen, you need to set up a configuration file, which tells Doxygen what files to analyze and how to format the generated documentation. This configuration file is a simple text file with a Makefile-like format, containing a set of configuration options. You can generate a sample configuration file using the -g option, as shown here: $ doxygen -g A simple configuration file, suitable for a Java project, is illustrated here: Code View: PROJECT_NAME = Planestore-core PROJECT_NUMBER = 0.1 OUTPUT_DIRECTORY = P:/projects/planestore-core/planestore-core/target/doxygen JAVADOC_AUTOBRIEF = YES TAB_SIZE = 4 OPTIMIZE_OUTPUT_JAVA = YES INPUT = P:/projects/planestore-core/planestore-core/src RECURSIVE = YES HAVE_DOT = YES UML_LOOK = YES CLASS_GRAPH = YES COLLABORATION_GRAPH = YES GROUP_GRAPHS = YES GRAPHICAL_HIERARCHY = YES DIRECTORY_GRAPH = YES SHOW_DIRECTORIES = YES SOURCE_BROWSER = YES STRIP_CODE_COMMENTS = NO GENERATE_LATEX = NO GENERATE_TREEVIEW = YES This file is a not-quite-minimal configuration you would need for a Java project. As well as the strict minimum, there are a few useful extras added in along the way. You need the HAVE_DOT option to indicate that Graphviz dot tool is installed and available: in this case, Doxygen can generate a full range of graphs and diagrams, including class diagrams, collaboration diagrams and call graphs. The UML_LOOK option will instruct Doxygen to produce proper UML-style diagrams. The GENERATE_TREEVIEW option produces a JavaScript tree structure, which is displayed in a side panel (see Figure 30-4). The 1028

Java Power Tools SOURCE_BROWSER option lets you generate a cross-referenced, browsable, HTML view of your application source code. All the available configuration options are described in detail in the Doxygen documentation. I will discuss some of the more useful ones later in the chapter. [*] [*] See http://www.doxygen.org/config.html. Rather than configuring this file by hand, you can also use the Doxygen graphical frontend tool, if it has been installed on your machine. (It comes bundled with the Windows installer, but for *NIX installations, you may need to configure and build Doxygen from the source code using the --with-doxywizard option.) The graphical frontend (doxywizard) is useful for learning how to use Doxygen (see Figure 30-5), and is also a good way to obtain an initial Doxygen configuration file, which you may want to tailor afterward. The wizard mode (shown in Figure 30-5) lets you configure Doxygen quickly and intuitively, using just the most important configuration options, and sensible default values. Figure 30-5. The graphical frontend for Doxygen 1029

Java Power Tools For a Java project, make sure that you tick the \"Scan recursively\" option on the Project page, and \"Optimize for Java output\" on the Mode page. It is also handy to include cross-referenced source code in the generated web site (this option is on the Mode page). You should also configure the graphs and diagrams you would like to be generated. You do this on the Diagrams tab. By default, only simple class diagrams are generated. However, for the more sophisticated (and useful) diagrams, you need to use the Graphviz command-line tools. Just select the \"Use dot tool from the Graphviz package\" option, and choose the diagrams you want to produce. The expert mode (see Figure 30-6) provides access to all the nitty-gritty details, and refers to configuration variables by their internal names, rather than the more readable labels used in the wizard mode. However, there are some useful options for Java projects which are not set by default, and which are only accessible from the Expert mode (or directly from the configuration file, of course). For example, the JAVADOC_A⁠U⁠TO⁠BRIEF option, which I discuss below, is not set by default. By default, the TAB_SIZE option is set to the rather strange value of 6, rather than the more common values of 4 or possibly 8. And, if you want the more familiar UML-style class diagrams, you need to select the UML_LOOK option on the Dot tab. Figure 30-6. The doxywizard expert mode When you are happy with your configuration file, save it into your project home directory. 30.3.5. Running Doxygen from the Command Line Running Doxygen from the command line is easy. By default, Doxygen will look for a configuration file called Doxyfile in the current directory. If your configuration file is called Doxyfile, all you need to do is to run the Doxygen command: $ doxygen Searching for include files... 1030

Java Power Tools Searching for example files... Searching for images... Searching for dot files... Searching for files to exclude Searching for files to process... Searching for files in directory P:/projects/planestore-core/planestore-core/src ... Generating namespace member index... Generating graph info page... Generating file index... Generating example index... Generating file member index... Generating page index... Alternatively, you can provide the configuration file explicitly: $ doxygen src/config/doxyfile.conf This will analyze your project's source code and generate a web site in the designated output directory. Depending on the size of your project, this may take some time. 30.3.6. Using Doxygen with Ant It is a straightforward task to use Doxygen with Ant. Karthik Kumar maintains an Ant plugin for Doxygen, which you can download from the project web site. As you would [*] expect, Doxygen and Graphviz need to be installed for this task to work. [*] http://ant-doxygen.sourceforge.net/ Download and extract the binary distribution into an appropriate place on your local machine. Alternatively, you can use a bootstrap script along the following lines for more portability: Code View: <project name=\"DOxygen Bootstrap script\" default=\"bootstrap\" basedir=\".\" > <!-- Define the environment-specific \"doxygen.ant.home\" and \"doxygen.ant.version\" variables in this file if required. --> <property file=\"${user.home}/ant-global.properties\"/> <!-- This default value is used if no properties file is present --> <property name=\"doxygen.ant.home\" value=\"${user.home}/.doxygen-ant\"/> <property name=\"doxygen.ant.version\" value=\"1.4\"/> <echo>Installing the DOxygen Ant task into ${doxygen.ant.home}</echo> <property name=\"sourceforge.mirror\" 1031

Java Power Tools value=\"http://optusnet.dl.sourceforge.net/sourceforge/ant-doxygen\" /> <available file=\"${doxygen.ant.home}/ant_doxygen-bin-${doxygen.ant.version}.tgz\" property=\"doxygen.ant.installed\"/> <echo>Bootstrap DOxygen</echo> <target name=\"bootstrap\" unless=\"doxygen.ant.installed\"> <echo>Installing DOxygen task</echo> <mkdir dir=\"${doxygen.ant.home}\" /> <get src=\"${sourceforge.mirror}/ant_doxygen-bin-${doxygen.ant.version}.tgz\" dest=\"${doxygen.ant.home}/ant_doxygen-bin-${doxygen.ant.version}.tgz\" usetimestamp=\"true\"/> <gunzip src=\"${doxygen.ant.home}/ant_doxygen-bin-${doxygen.ant.version}.tgz\" dest=\"${doxygen.ant.home}/ant_doxygen-bin-${doxygen.ant.version}.tar\"/> <untar src=\"${doxygen.ant.home}/ant_doxygen-bin-${doxygen.ant.version}.tar\" dest=\"${doxygen.ant.home}/ant_doxygen-bin-${doxygen.ant.version}\"/> <move todir=\"${doxygen.ant.home}\"> <fileset dir=\"${doxygen.ant.home}/ant_doxygen-bin-${doxygen.ant.version}\"> <include name=\"**/*\"/> </fileset> </move> <delete dir=\"${doxygen.ant.home}/ant_doxygen-bin-${doxygen.ant.version}\"/> </target> </project> Running Doxygen is now a simple matter: just declare the doxygen task using the JAR file we just downloaded, and invoke the task using the configFilename attribute to specify the configuration file: <!-- This default value is used if no properties file is present --> <property name=\"doxygen.ant.home\" value=\"${user.home}/.doxygen-ant\"/> <property name=\"doxygen.ant.version\" value=\"1.4\"/> ... <!-- Doxygen --> 1032

Java Power Tools <ant antfile=\"bootstrap-doxygen.xml\" /> <taskdef name=\"doxygen\" classname=\"org.doxygen.tools.DoxygenTask\" classpath=\"${doxygen.ant.home}/lib/ant_doxygen.jar\" /> <target name=\"doxygen\"> <doxygen configFilename=\"src/config/doxyfile.conf\" /> </target> You can also explicitly specify configuration values, which allows more flexibility in the build parameters, as shown here: Code View: <target name=\"doxygen\"> <mkdir dir=\"build/doxygen\" /> <doxygen> <property name=\"PROJECT_NAME\" value=\"Planestore-core\" /> <property name=\"PROJECT_NUMBER\" value=\"0.1\" /> <property name=\"OUTPUT_DIRECTORY\" value=\"target/doxygen\" /> <property name=\"JAVADOC_AUTOBRIEF\" value=\"YES\" /> <property name=\"TAB_SIZE\" value=\"4\" /> <property name=\"OPTIMIZE_OUTPUT_JAVA\" value=\"YES\" /> <property name=\"INPUT\" value=\"src\" /> <property name=\"RECURSIVE\" value=\"YES\" /> <property name=\"HAVE_DOT\" value=\"YES\" /> <property name=\"UML_LOOK\" value=\"YES\" /> <property name=\"CLASS_GRAPH\" value=\"YES\" /> <property name=\"COLLABORATION_GRAPH\" value=\"YES\" /> <property name=\"GROUP_GRAPHS\" value=\"YES\" /> <property name=\"GRAPHICAL_HIERARCHY\" value=\"YES\" /> <property name=\"DIRECTORY_GRAPH\" value=\"YES\" /> <property name=\"SHOW_DIRECTORIES\" value=\"YES\" /> <property name=\"SOURCE_BROWSER\" value=\"YES\" /> <property name=\"STRIP_CODE_COMMENTS\" value=\"NO\" /> <property name=\"GENERATE_LATEX\" value=\"NO\" /> <property name=\"GENERATE_TREEVIEW\" value=\"YES\" /> </doxygen> </target> 30.3.7. How to Make Your Java Classes Doxygen-Friendly Doxygen (and Javadoc, for that matter) will try their best to document your source code in a readable way, but there is always a limit to what a machine can do. 1033

Java Power Tools Automatically-generated technical documentation of any quality requires a bit of effort when it comes to documenting your code. (Of course, writing well-documented code is a recommended best practice for any programming language, and not just where automatic documentation is to be used.) In this section, we look at a few tips for creating decent documentation when using Doxygen. 30.3.7.1. Using the brief descriptions If you set the JAVADOC_AUTOBRIEF option to true, Doxygen will use the first sentence of a Javadoc comment as the brief description. The brief description is used in summary tables to give a—well—brief description of a class or method. There are other ways to do this, but this is by far the easiest and the most Java-friendly. 30.3.7.2. Lists You can include lists in your documentation in a number of ways. If you are using both Javadoc and Doxygen, you should probably use standard HTML lists. However, if you are only using Doxygen, you can use the more convenient wiki-style lists such as the one shown here: /** * This class handles three types of widget orders: * - Orders received online * - Orders received by phone: * - By voice * - By SMS * - Orders received by carrier pigeon. */ This would generate something along the following lines: This class handles three types of widget orders:  Orders received online  Orders received by phone: o By Voice o By SMS  Orders received by carrier pigeon. 1034

Java Power Tools 30.3.7.3. Links and references Doxygen handles cross-references between classes particularly well. This means that, when you write your comments, you can add references to other classes with very little effort. Any qualified or unqualified class name that appears in your Javadoc comments will be automatically detected and rendered as a HTML link to the details page for the corresponding class. And you can refer to methods or variables using the \"#\" notation. Both techniques are shown here: Code View: /** * A generic DAO interface. * All DAO interfaces derive from this one, and all DAO implementation classes * implement this interface. * A typical example is AircraftModelDAO and AircraftModelDAOImpl. * In particular, refer to the AircraftModelDAOImpl#findAll implementation for a * good example of how to implement this method. */ In the generated site, the class names and method name will be rendered as HTML links to the corresponding page. Similarly, any email addresses or URLs included in your documentation will be correctly rendered as HTML links. You should note that Doxygen does not recognize the Javadoc-style @link or @see notations. 30.3.7.4. Documenting packages Documenting packages is a much-neglected art. A little high-level documentation about your key packages can go a long way in making your application architecture easier to understand and more consistent. Take the time to sit down and write a few architectural notes for your key packages—what does this package do? How does it fit in to the overall application? How should the classes in this package be used? What patterns should be used when writing a new class in this package? In Javadoc, you can use the \"package.html\" to do this. Unfortunately, at the time of writing, Doxygen didn't know much about this file, so if you want package-level documentation in your Doxygen reports, you need to do something a little more proprietary. In Doxygen, you can use the \"\package\" or \"@package\" notation, placed 1035

Java Power Tools within a Java class, to document a package. The simplest approach is to place this block in one of the principal classes of a package, as shown here: Code View: package com.javapowertools.planestore.core.dao; /** * @package com.javapowertools.planestore.core.dao * Each DAO class provide basic database-related functions for a particular domain * object. Each DAO is written as an interface and an implementing class. * Implementation classes are derived from the GenericDAOImpl class, and * interfaces from the GenericDAO interface. The interface is used by other * classes in the application - the implementation class is referenced in the * Spring configuration file... * */ ... /** * A generic DAO interface. * All DAO interfaces should derive from this one... * * @param AnyType the domain object this DAO handles. * @param KeyType the type of the primary key of this domain object. */ public interface GenericDAO<AnyType, KeyType> { ... } 30.3.7.5. Documenting the home page You can customize the (by default empty) home page using the \"\homepage\" (or \"@homepage\") tag. You can also use the @section, @subsection, and @subsubsection tags to structure your text: Code View: package com.javapowertools.planestore.core.domain; /** * @mainpage The Planestore Core API package * * @section intro_sec Introduction * * This web site contains the technical documentation for the Planestore-Core API. 1036

Java Power Tools * This page contains a high-level introduction to the application architecture. * etc... */ ... This block can be placed anywhere, but preferably you should place it in one of the main classes of your application, although, admittedly, this can be hard to find with a web application. Section 30.4. Embedding UML Diagrams in Your Javadoc with UmlGraph Source-generated UML diagrams are an excellent way to communicate details of your application architecture and domain model. UML can provides a clear and (usually) readable representation of the state of your code. It can also highlight architectural flaws such as redundant dependencies or overly complex classes. You can use generated diagrams both to learn about an API and also to verify that an application has been correctly implemented. For example, it is much easier to review and explain a domain model implementation using interactive UML diagrams than by just reading the source code. Typically, a modeling tool might be used to design a clean domain model. Round-trip UML tools are not particularly widespread, however, and in most organisation, most application coding ends up being done directly in the IDE. Generating UML diagrams directly from source code can let you make sure that the implemented classes correspond to the target model. Diomidis D. Spinellis has written, and maintains, another interesting tool in this domain, [*] called UmlGraph. [119] This quite brilliant tool lets you insert detailed UML class diagrams seamlessly into your Javadoc. It does not go as far as Doxygen in the documentation that it generates—indeed, this tool is exclusively devoted to generating UML diagrams from your code. However, it does this very well. [*] http://www.spinellis.gr/index.html.var [119] http://www.spinellis.gr/sw/umlgraph/ Like Doxygen, UmlGraph relies on the Graphvis tool, so this needs to be installed on your system before you can use UmlGraph. The most convenient way to use UmlGraph is via the UmlGraph doclet. This enables you to integrate UML class diagrams seamlessly in to your Javadoc (see Figure 30-7). Figure 30-7. Javadoc embedded with UML class diagrams 1037

Java Power Tools These graphs are interactive, so you can click on a class to go to the Javadoc page (and corresponding UML class diagram) of that class. This provides a clear, intuitive way of navigating though the application architecture. UmlGraph is a command-line tool, but, in a real-world project, this is not necessarily the most convenient way to generate your graphs. It is far easier to integrate UmlGraph into your build process. To this end, UmlGraph also comes in the much more useful form of a Javadoc doclet, making it easy to integrate into your javadoc generation. This approach works perfectly with Ant and Maven. UmlGraph is a flexible tool, with a large number of configuration options that you can use to fine-tune the layout of your diagrams. Some of the more interesting options are discussed here: inferrel This option tells UmlGraph to derive relationships between classes from the fields of each class. For example, if a Client class has a member variable of type Account, UmlGraph will draw a relationship between these two classes in the class diagram. This option is deactivated by default. inferdep Similar to inferrel, the inferdep option tells UmlGraph to draw any dependencies it can find within the class, based on method and parameter types. This is useful to give a real idea of what classes a particular class uses. 1038

Java Power Tools hide The hide option can be used to mask out certain classes from your diagrams. For example, you may not want the JDK classes to appear in your class diagrams. collpackages This tells UmlGraph what classes it should consider to be collections. This is mainly used to depict cardinality in relationships. attributes Show class attributes. operations Show class operations. enumerations Show enumerations as separate objects. enumconstants List the constant values for enum types. link You can use this parameter to provide the address of external Javadoc for classes that your application uses. This way, a user will be able to navigate directly to the external Javadoc. This is useful for the Java API itself, and key libraries such as Spring and Hibernate. 30.4.1. Using UmlGraph in Ant 1039

Java Power Tools UmlGraph integrates smoothly into Ant, using the UmlGraphDoc doclet wrapper. Simply embed a <doclet> tag in your <javadoc> task, as shown below. You can use the <param> tag to specify command-line options. The following configuration will produce a set of fairly complete and detailed UML diagrams embedded into your Javadoc: Code View: <target name=\"javadoc\" depends=\"compile,init\" description=\"Generate JavaDocs.\"> <javadoc sourcepath=\"${src.dir}\" destdir=\"${reports.javadoc}\" access=\"private\" classpathref=\"compile.classpath\"> <doclet name=\"org.umlgraph.doclet.UmlGraphDoc\" path=\"lib/UmlGraph.jar\"> <param name=\"-inferrel\"/> <param name=\"-inferdep\"/> <param name=\"-quiet\"/> <param name=\"-hide\" value=\"java.*\"/> <param name=\"-collpackages\" value=\"java.util.*\"/> <param name=\"-qualify\"/> <param name=\"-postfixpackage\"/> <param name=\"-nodefontsize\" value=\"9\"/> <param name=\"-nodefontpackagesize\" value=\"7\"/> <param name=\"-attributes\"/> <param name=\"-operations\"/> <param name=\"-enumerations\"/> <param name=\"-enumconstants\"/> <param name=\"-visibility\"/> <param name=\"-link\" value=\"http://java.sun.com/j2se/1.5/docs /api/\"/> <param name=\"-link\" value=\"//static.springframework.org/spring/ docs/2.0.x/api/\"/> <param name=\"-link\" value=\"http://www.hibernate.org/hib_docs/ v3/api\"/> </doclet> </javadoc> </target> 30.4.2. Using UmlGraph in Maven To integrate UmlGraph into Maven, you will need to configure the maven-javadoc-plugin in the <reporting> section of your POM file. You use the <additionalparam> tag to list the numerous UmlGraph options that you need to fine-tune your diagrams: 1040

Java Power Tools Code View: <project...> ... <reporting> <plugins> <!-- UML-enabled javadoc --> <plugin> <artifactId>maven-javadoc-plugin</artifactId> <configuration> <source>1.5</source> <doclet> gr.spinellis.umlgraph.doclet.UmlGraphDoc </doclet> <docletArtifact> <groupId>gr.spinellis</groupId> <artifactId>UmlGraph</artifactId> <version>4.4</version> </docletArtifact> <additionalparam> -inferrel -inferdep -quiet -hide java.* -collpackages java.util.* -qualify -postfixpackage -nodefontsize 9 -nodefontpackagesize 7 -attributes -operations -enumerations -enumconstants -visibility -link \"http://java.sun.com/j2se/1.5/docs/api/\" -link \"http://static.springframework.org/spring/docs/2.0.x/api/\" -link \"http://www.hibernate.org/hib_docs/v3/api/\" </additionalparam> </configuration> </plugin> </plugins> </reporting> ... </project> Section 30.5. Conclusion Good technical documentation is a valuable asset for any project. Now, really good technical documentation can only be produced by a combination of human-written text and automatically generated documentation. Some high-profile open source projects such as Hibernate and the Spring framework [ ] can be said to have high-quality [*] 1041

Java Power Tools documentation, combining well-crafted human-written documentation alongside automatically generated API documentation. It would be a mistake to think that the latter can replace the former. [*] http://www.hibernate.org/5.html [ ] http://www.springframework.org/documentation However, for typical enterprise projects, budgetary constraints may not allow for such high-quality documentation, nor is it absolutely essential for all types of projects to have this level of technical documentation. Tools such as SchemaSpy, Doxygen, and UmlGraph—although not producing truly great documentation—can certainly go a long way to producing adequate documentation. Combined with good-quality and strategically placed comments, they can still provide valuable insight into the architecture and inner workings of an application, at a relatively small cost. 1042

Java Power Tools Bibliography Paul Brown The 2nd most useful Java-Oracle Tool for 2006 April 2006 A short blog entry in which SchemaSpy was named the second most useful Java/Oracle tool in 2006. http://www.oreillynet.com/onjava/blog/2006/04/the_2nd_most_useful_javaoracle.html Casey John, Vincent Massol, Brett Porter, and Carlos Sanchez Better Builds with Maven March 2006 DevZuz Mike Clark Pragmatic Project Automation July 2004 0-9745140-3-9 Pragmatic Programmers Mike Clark Continuous Performance Testing With JUnitPerf July 2003 http://www.javapronews.com Brian W. Fitzpatrick, and C. Michael Pilato Collins-Sussman Ben Version Control with Subversion O'Reilly Media Paul, Steve Matyas, and Andrew Glover Duvall Continuous Integration June 2007 0-3213363-8-0 Addison-Wesley Edgewall Software The Trac Project Website: http://trac.edgewall.org/ Katherine and David Goodwin Developing more effectively with Trac 58 1 HME Publishing Limited January, 2006 Linux User & Developers January, 2006 Chris Grindstaff FindBugs, Part 1: Improve the quality of your code May 2004 IBM DeveloperWorks Chris Grindstaff FindBugs, Part 2: Writing custom detectors May 2004 IBM DeveloperWorks Andrew Glover In pursuit of code quality: Performance testing with JUnitPerf November 2006 IBM DeveloperWorks Andrew Glover The Disco Blog Andy Glover's blog on code quality, testing, Groovy, and other related matters. http://www.thediscoblog.com Steven Holzner Ant: The Definitive Guide, 2nd Edition April 2005 978-0596006099 O'Reilly Media William Pugh Hovemeyer, David and Finding Bugs is Easy December 2004 OOPSLA 2004 Companion Andy and Dave Thomas Hunt Pragmatic Unit Testing in Java with JUnit September 2003 978-0974514017 The Pragmatic Programmers Steve and Hatcher, Eric Loughran Ant int Action 2007 1-932394-80-X Manning Publications Mike Mason Pragmatic Version Control: Using Subversion May 2006 The Pragmatic Programmers Eric Redmond The Maven 2 POM demystified May 2006 Javaworld Schneider David and Koedderitzsch, Lars (project admins) The Eclipse Checkstyle plug-in web site: http://eclipse-cs.sourceforge.net/basic_setup_project.html Martin Streicher Eclipse Test and Performance Tools Platform Tutorial (Parts 1, 2 and 3) February 2006 IBM DeveloperWorks John Smart Test-Driven Development Using StrutsTestCase October 2005 1043

Java Power Tools OnJava.com John Smart Get the most out of Maven site generation February 2006 JavaWorld John Smart Maintain Better Coding Standards with Ease Using Checkstyle March 2006 DevX John Smart PMD Squashes Code Bugs April 2006 DevX John Smart Continuous Integration with Continuum May 2006 Java.net John Smart Peer Code Reviews Made Easy with Eclipse Plug-In June 2006 DevX John Smart Mastering Subversion in the Eclipse IDE July 2006 InformIT John Smart Profiling Your Applications with Eclipse Callisto August 2006 OnJava.com John Smart Which open source CI tool is best suited for your application's environment? November 2006 JavaWorld Dave, and Andy Hunt Thomas Pragmatic Version Control Using CVS September 2003 The Pragmatic Programmers Mihalis Tsoukalos An Introduction to GraphViz September 2004 Linux Journal Jeroen van Wilgenburg Getting started with Cobertura—A Java Code Coverage Tool April 2006 AMIS Technology blog Zyl, Jason van, John Casey, and Eric Redmond Maven: The Definitive Guide to be announced Sonatype (http://www.sonatype.com) 1044

Java Power Tools Colophon The image on the cover of Java Power Tools is a drill press, a necessity in any workshop because of its high-precision drilling capabilities. A drill press consists of a base, column (or pillar), table, spindle (or quill), and drill head, which is usually driven by an induction motor. There are several advantages to working with a drill press rather than a handheld drill: less effort is required to apply the drill to the workpiece, and a lever working on a rack and pinion controls the movement of the chuck and spindle, giving the operator a considerable mechanical advantage; the drill can be mounted on a stand or secured to a workbench, making the operation more secure; and the angle of the spindle is fixed in relation to the table, allowing holes to be drilled accurately and repetitively. The cover image is an original photograph by Frank Deras. The cover font is Adobe ITC Garamond. The text font is Linotype Birka; the heading font is Adobe Myriad Condensed; and the code font is LucasFont's TheSans Mono Condensed. 1045

Java Power Tools Index [SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] SYMBOL [SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] @AfterClass @AfterMethod @AfterSuite @BeforeClass @BeforeMethod @BeforeSuite @SuppressWarnings @Test A [SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] Abbot AccountManage plug-in add-maven-repo aggregation agile development 2nd 3rd Agnew, Brian 2nd AJAX Almost Plain Text (APT) annotations 2nd Ant bootstrapping build scripts 2nd Checkstyle and Cobertura and 2nd 3rd code coverage in compiling Java code Continuum and 1046

Java Power Tools CruiseControl and DbUnit and dependencies dependency management 2nd depends attribute deployment described 2nd description attribute directory structure documenting Doxygen and in Eclipse FindBugs in functional testing in Hudson and installing Javadoc and JUnit and assertions build file compiling unit tests 2nd conditional tests directory structure forking formatters generating reports haltonfailure attribute 2nd junit task 2nd multiple test cases overview single tests JUnitPerf and in Maven Maven in 2nd Maven tasks Maven vs. 2nd Mojos in NetBeans packaging applications 2nd path definitions performance testing plug-ins PMD in POM files and 2nd 3rd 4th projects 1047

Java Power Tools properties 2nd proxy connections 2nd QAlab and SchemaSpy in Selenium and SoapUI and 2nd StatSVN Subversion in targets tasks TestNG and 2nd UmlGraph in unit testing 2nd 3rd 4th 5th XMLTask controlling builds with editing XML 2nd ANT_ARGS ANT_HOME 2nd ANT_OPTS Apache BCEL library Apache Derby Apache Velocity APT (Almost Plain Text) archetype plug-in Archiva adding files browsing repositories changing ports configuring Maven configuring repositories installing managing users proxy connections 2nd remote repositories artifactId element Artifactory adding artifacts adding repositories as mirror backing up repositories configuring Maven configuring repositories described installing proxy connections 1048

Java Power Tools on Tomcat artifacts 2nd assemblies assertions in JUnit 2nd in Selenium 2nd in SoapUI 2nd 3rd in TestNG Atlassian atomic commits atomic tests atomic updates available task B [SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] backups Artifactory Subversion Bamboo 2nd batchtest task 2nd Beck, Kent Berkeley DB Beust, Cédric 2nd bootstrapping 2nd branch coverage Broadcast plug-in bug patterns Bugzilla classifications configuring creating an issue customizing fields described installing milestones Mylyn and notification options searching for bugs setting up a product user accounts 1049


jack.zhang

Java.Power.Tools
Share
Like this book? You can publish your book online for free in a few minutes!
Create your own flipbook

TOP SEARCH

business design fashion music health life sports home marketing children

RELATED PUBLICATIONS