4.3. Example: Populating DOM4J

Let's run through a quick example. We first produce dom4j.xml:

eitan@ubuntu:~/devel/dom4j/docs/apidocs$ apixml package-list > dom4j.xml

Check out apis/dom4j.xml to see how the base XML descriptor produced by apixml was completed. We're now ready to ask ashkelon to put DOM4J into our database. Let's first see what we have already..

eitan@ubuntu:~/projects/ashkelon/apis$ ashkelon list
Ashkelon: 9 APIs in ashkelon:
Ashkelon:    Hibernate
Ashkelon:    jEdit
Ashkelon:    FlexDock
Ashkelon:    Servlet
Ashkelon:    L2FProd.com Common Components
Ashkelon:    log4j
Ashkelon:    JiBX
Ashkelon:    JUnit
Ashkelon:    J2SE

Ok, let's add dom4j:

eitan@ubuntu:~/projects/ashkelon/apis$ ashkelon add dom4j.xml

And here's the output (less the javadoc warnings)

add: cmd is: cvs -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/dom4j -q update -d  -r HEAD dom4j/src/java
Loading source files for package org.dom4j...
Loading source files for package org.dom4j.bean...
Loading source files for package org.dom4j.datatype...
Loading source files for package org.dom4j.dom...
Loading source files for package org.dom4j.dtd...
Loading source files for package org.dom4j.io...
Loading source files for package org.dom4j.jaxb...
Loading source files for package org.dom4j.rule...
Loading source files for package org.dom4j.rule.pattern...
Loading source files for package org.dom4j.swing...
Loading source files for package org.dom4j.tree...
Loading source files for package org.dom4j.util...
Loading source files for package org.dom4j.xpath...
Loading source files for package org.dom4j.xpp...
Constructing Javadoc information...
[a bunch of javadoc side-effect warnings suppressed]
Ashkelon: 14 packages to process..
Ashkelon: Processing package org.dom4j..
Ashkelon: Processing package org.dom4j.bean..
Ashkelon: Processing package org.dom4j.datatype..
Ashkelon: Processing package org.dom4j.dom..
Ashkelon: Processing package org.dom4j.dtd..
Ashkelon: Processing package org.dom4j.io..
warning - Tag @link: missing '#': "OutputFormat.isXHTML() OutputFormat.isXHTML()"
warning - Tag @link: can't find OutputFormat.isXHTML() in org.dom4j.io.HTMLWriter
Ashkelon: Processing package org.dom4j.jaxb..
Ashkelon: Processing package org.dom4j.rule..
Ashkelon: Processing package org.dom4j.rule.pattern..
Ashkelon: Processing package org.dom4j.swing..
Ashkelon: Processing package org.dom4j.tree..
Ashkelon: Processing package org.dom4j.util..
Ashkelon: Processing package org.dom4j.xpath..
Ashkelon: Processing package org.dom4j.xpp..
Ashkelon: Add Time: 7 seconds
Ashkelon: Updating Internal References..
Ashkelon:       Processing FIELD references..
Ashkelon:       Processing METHOD references..
Ashkelon:       Processing IMPL_INTERFACE references..
Ashkelon:       Processing THROWNEXCEPTION references..
Ashkelon:       Processing PARAMETER references..
Ashkelon:       Processing SUPERCLASS references..
Ashkelon:       Processing seetag PACKAGE references..
Ashkelon:       Processing seetag CLASSTYPE references..
Ashkelon:       Processing seetag MEMBER references..
Ashkelon:       Processing seetag EXECMEMBER references..
Ashkelon: Ref. Time: 8 seconds
Ashkelon: done
102 warnings

The warnings are harmless. They're a side effect of the javadoc parser attempting to resolve referenced libraries from the DOM4J classes. We see there were a couple of javadoc syntax warnings that we might want to fix. Otherwise, ashkelon ensured that its source cache was up to date by doing a CVS update. It then proceeded to process the 14 packages that comprise the dom4j javadocs. This took seven seconds. Eight more seconds were spent resolving inter-api references between existing APIs in the database and the newly added one.

Oftentimes you'll want to update an API you've already populated into your database with an updated version. You do this with the ashkelon update command. This command first deletes the api from the repository, and then proceeds to fetch, parse, and populate the updated version.

Say, for example, that dom4j released a new version. You'd update the xml descriptor, maybe the tag name in cvs to fetch the code from. Then you'd invoke:

         ashkelon update dom4j