Enunciate Example

Russell Bateman
February 2014
last update:

I decided to get more intimately acquainted with Enunciate. Enunciate is an engine for enhancing a Java web service API that creates full HTML documentation, client-side libraries for consumers of your web service, interface-definition documents such as WADLs.

So, I did the quick-start example in order to start from scratch. This example creates a tiny ReSTful web service. It's a little over-elaborated if only to have something show up in the documentation.

The example was pretty simple:

  1. I created an Eclipse Dynamic Web Project, without Maven.

  2. I typed in all the classes (whose source code is linked to in the quick-start guide page), pretty much as-is: 
    ~/dev $ tree enunciate-quick-start
enunciate-quick-start
`-- src
    `-- com
        `-- ifyouwannabecool
            +-- api
            |   +-- ExclusiveGroupException.java
            |   +-- PermissionDeniedException.java
            |   +-- PersonaService.java
            |   `-- SocialGroupService.java
            +-- domain
            |   +-- link
            |   |   +-- Link.java
            |   |   `-- SocialGroup.java
            |   `-- persona
            |       +-- Name.java
            |       `-- Persona.java
            `-- impl
                +-- PersonaServiceImpl.java
                `-- SocialGroupServiceImpl.java

9 directories, 11 files
  3. I first dug up all the libraries on my own (jersey-server.191.1.jar, etc.) until I finally downloaded Enunciate where I found all the libraries I'd need for the project in its lib subdirectory (darn, I could have just used those, but below you can see the ones I did use in case you find it interesting).

  4. Then I doctored up a quick-and-dirty ant script (remember, I chose not to use Maven), build.xml. I also chose not to use Spring so I commented out those lines. I mucked with it to do things a tiny bit differently (but I commented out the suggested lines from the article rather than delete them). Basically, what's in bold below is mine, while the rest is copied directly from the illustration on the web page: 
    
<?xml version="1.0" ?>
<!DOCTYPE project>
<project name="enunciate-quick-start">

    <property name="enunciate.home" location="${basedir}/lib/enunciate" />
    <property name="build.dir"      location="${basedir}/build" />

    <path id="enunciate.classpath">
      <!--<fileset dir="${enunciate.home}/lib">-->
      <fileset dir="${enunciate.home}">
        <include name="*.jar"/>
      </fileset>
      <!--include (optional) spring module
      <fileset dir="${enunciate.home}/lib/modules/spring">
        <include name="*.jar"/>
      </fileset>-->;
      <fileset dir="${java.home}">
        <include name="lib/tools.jar"/>
      </fileset>
    </path>

    <taskdef name="enunciate" classname="org.codehaus.enunciate.main.EnunciateTask">
      <classpath refid="enunciate.classpath"/>
    </taskdef>

    <!--<enunciate basedir="src/main/java">-->
    <enunciate basedir="src">
      <include name="**/*.java"/>
      <classpath refid="enunciate.classpath"/>
      <--<export artifactId="war.file" destination="${tomcat.home}/webapps/myapp.war"/>-->
      <export artifactId="war.file" destination="${build.dir}/webapps/${ant.project.name}.war"/>
      <javacArgument argument="-g"/>
    </enunciate>
</project>

    Before running Enunciate (via ant), I did the download from CodeHaus. I blew open the tarball, then copied the contents of the lib subdirectory to my project's lib subdirectory whence ant accesses them—as hinted by the ant script if you looked closely above. 

    ~/dev $ tree enunciate-quick-start/lib
enunciate-quick-start
`--lib
   +-- asm-3.2.jar
   +-- enunciate
   |   +-- activation-1.1.jar
   |   +-- ...
   |   +-- enunciate-c-1.27.jar
   |   +-- enunciate-core-1.27.jar
   |   +-- enunciate-core-annotations-1.27.jar
   |   +-- enunciate-core-rt-1.27.jar
   |   +-- enunciate-csharp-1.27.jar
   |   +-- enunciate-docs-1.27.jar
   |   +-- enunciate-java-client-1.27.jar
   |   +-- enunciate-jaxws-ri-1.27.jar
   |   +-- enunciate-jaxws-support-1.27.jar
   |   +-- enunciate-jersey-1.27.jar
   |   +-- enunciate-jersey-rt-1.27.jar
   |   +-- enunciate-obj-c-1.27.jar
   |   +-- enunciate-php-1.27.jar
   |   +-- enunciate-ruby-1.27.jar
   |   +-- enunciate-xml-1.27.jar
   |   `-- ...
   +-- jersey-bundle-1.9-ea01.jar
   +-- jersey-client-1.9.1.jar
   +-- jersey-json-1.9.1.jar
   +-- jersey-server-1.9.jar
   `-- jsr311-api-1.1.1.jar
  5. Then I invoked Enunciate from the root of my project, getting some errors, but fixing them up (see commented lines in ant script) until it ran (this is step 2 of the Enunciate quick-start). Remember, I've spent less than half an hour working in this up till now. 
    $ ant
Buildfile: /home/russ/dev/enunciate-quick-start/build.xml
Loading modules from the specified classpath....
Discovered module c
Discovered module csharp
Discovered module docs
Discovered module java-client
Discovered module jaxws-ri
Discovered module jaxws-support
Discovered module jersey
...
[enunciate] warning: [options] bootstrap class path not set in conjunction with -source 1.5
[enunciate] 1 warning
[enunciate]
[enunciate]
[enunciate]
[enunciate]
[enunciate]

BUILD SUCCESSFUL
Total time: 5 seconds
  6. After that, I looked at the WAR file built, enunciate-quick-start.war and decided to try it out. I installed Tomcat 6 on my host (as I had not done that yet since I don't ordinarily use Tomcat on my development host except from within Eclipse or IntelliJ to debug stuff): 
    $ sudo apt-get install tomcat6
  7. Then, I copied the Enunciate WAR to Tomcat to deploy it (this is step 3 of the Enunciate quick-start): 
    $ sudo cp enunciate-quick-start.war /var/lib/tomcat6/webapps
$ pu /var/lib/tomcat6/webapps/
$ ll
total 4220
drwxrwxr-x 4 tomcat6 tomcat6    4096 May  9 10:41 .
drwxr-xr-x 6 root    root       4096 May  9 10:39 ..
drwxr-xr-x 6 tomcat6 tomcat6    4096 May  9 10:41 enunciate-quick-start
-rw-r--r-- 1 root    root    4302032 May  9 10:41 enunciate-quick-start.war
drwxr-xr-x 3 root    root       4096 May  9 10:39 ROOT
  8. Finally, I launched my browser to see what it looked like. If at this point you were acquainted with the sample application in the quick-start, you'd recognize some of what shows up here—thereby bolstering your amazement.

  9. Now, knowing that I hadn't written any Javadoc in the examples as I typed them in, and that there was none to begin with either, I thought clicking on the PersonalServiceImpl link was instructive:

  10. Last, I clicked down at the bottom on the persona element link which brought up this page describing the Persona POJO. Remember, I've typed in no Javadoc: