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 eitan@ubuntu:~/projects/ashkelon/apis$
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.. /home/eitan/projects/sourcecache/dom4j/src/java/org/dom4j/io/HTMLWriter.java:181: warning - Tag @link: missing '#': "OutputFormat.isXHTML() OutputFormat.isXHTML()" /home/eitan/projects/sourcecache/dom4j/src/java/org/dom4j/io/HTMLWriter.java:181: 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 eitan@ubuntu:~/projects/ashkelon/apis$
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