Thursday, January 31, 2008

Enunciate!

Overview
Starting from scratch to write a web service, getting a WAR built, deployed into JBoss or your favorite container can be a pain. I always start with an existing ant script and project, remove all the existing artifacts, then start fresh. This means, typically, an hour or so of deleting unneeded jars/classes/relics, search-n-replacing, fixing built script to remove any references to the old project-specific crud, deploying to my container to test a simple hello-world-ish app.

I hate doing this "setup" type work. It's boring and lame. .NET makes it really easy to startup a new project, so why do I hate doing it in Java?

So, what options are there for Java? One I have recently run across is Enunciate from our XFire friends at CodeHaus.

Enunciate appears to solve a nice little java pain point -- "How can I rapidly deploy a webservice without bothering with all the infrastructure crud?"

With a few simple JSR 181 annotations, and using enunciate, you can quickly wrap up a complete, deployable WAR which contains a WS-I Basic Profile compliant web service, nice browsable service documentation, client code in the form of a JAR, WSDL, etc.

If it sounds like a lot of effort, don't be fooled. I loosely followed the enunciate Quick Start and had my own simple web service up and running within a few minutes. This included setting up the eclipse project, downloading and unpacking enunciate, creating the ant build script, deploying to JBoss, and playing with the created application.

Let's go through a quick example on setting up enunciate, building a sample project, and deploying it to JBoss.

Enunciate is very module. In fact, all of the default functionality is provided via a set of modules that come with enunciate out of the box. If there is a deployable artifact that you want and there isn't a module for your desired functionality, then you are free to create your own module and donate it back to the project.

Getting Set Up
I'll assume you already have a JDK, IDE, and a container installed. Download enunciate from http://enunciate.codehaus.org/downloads.html. The latest at the time of this post is 1.6, release on January 8, 2008. The download is only 9.2 megs.

Extract the archive to some location. I extracted it to $HOME/bin.

If you want to run enunciate from cmd line versus ant script, then add enunciate/bin to your path. I'm going to walk through setting up enunciate as an ant task.
PATH=$PATH:$HOME/bin/enunciate-1.6/bin
Example Project
My sample project doesn't vary much from the enunciate Quick Start. I just like to try things myself in hopes that I hit something new. The example project I quickly thought of is a music service which will have admin and search capabilities for artists, albums, and songs. It is pretty simple, but just to illustrate the simplicity of enunciate and how it can handle some complexities of a "real-world" example.

My example will have artists who can have zero-or-more albums which can have zero-or-more songs. The service will allow adding relationships and searching.

First, I created the project structure and created the simple directory structure:
src
|----build.xml (I'll be using ant)
|----com
........|----music
................|----api
................|----domain
................|----impl
api -- contains interfaces and exceptions which define the exposed service
model -- contains business models and relationships
impl -- implementation classes for the interfaces

Next, I defined the interface for the service. The service will be simple and define the following operations. Note the @WebService annotation (from jsr-181)

import javax.jws.WebService;

import com.music.model.Album;
import com.music.model.Artist;
import com.music.model.Song;

@WebService
public interface MusicServiceInterface {
public Artist addArtist(Artist artist) throws AlreadyExistsException;
public Album addAlbum(Artist artist, Album album) throws AlreadyExistsException;
public Song addSong(Album album, Song song) throws AlreadyExistsException;
public Song[] searchSongs(String someSearchText);
}

Now create skeletons for Album, Artist, and Song as well as AlreadyExistsException, just to get things to compile. For this example, I'm NOT interested in implementing the actual functionality of a music search service; instead, I am only interested in how we expose a service quickly using enunciate.

Next up is to define the implementation class as follows. Note the reference to the implementation class in the @WebService annotation.

import javax.jws.WebService;

import com.music.api.AlreadyExistsException;
import com.music.api.MusicServiceInterface;
import com.music.model.Album;
import com.music.model.Artist;
import com.music.model.Song;

@WebService (
endpointInterface = "com.music.api.MusicServiceInterface"
)
public class MusicServiceImpl implements MusicServiceInterface {

public Album addAlbum(Artist artist, Album album)
throws AlreadyExistsException {
// TODO Auto-generated method stub
return null;
}

public Artist addArtist(Artist artist) throws AlreadyExistsException {
// TODO Auto-generated method stub
return null;
}

public Song addSong(Album album, Song song) throws AlreadyExistsException {
// TODO Auto-generated method stub
return null;
}

public Song[] searchSongs(String someSearchText) {
// TODO Auto-generated method stub
return null;
}

}

Now I have a compilable, but not-yet-functional application. Let's go ahead and see what happens when we use enunciate to create the WAR artifact and deploy it to JBoss.

I want to use ant for this example, so here's a sample build.xml file that you can modify to meet your needs:

    <project name="music-enunciate-example" default="package">

<target name="init">
<property name="enunciate.home" value="/home/dbreese/bin/enunciate-1.6" />
<property name="jdk.home" value="/opt/java/" />

<path id="enunciate.classpath">
<fileset dir="${enunciate.home}/lib">
<include name="**/*.jar" />
</fileset>
<fileset dir="${enunciate.home}">
<include name="enunciate-full-*.jar" />
</fileset>
<fileset dir="${jdk.home}/lib">
<include name="tools.jar"/>
</fileset>
</path>

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

</target>

<target name="clean">
<delete dir="dist"/>
</target>

<target name="package" depends="clean,init">
<mkdir dir="dist"/>
<enunciate basedir="src">
<include name="**/*.java" />
<classpath refid="enunciate.classpath" />
<export artifactId="spring.war.file" destination="dist/${ant.project.name}.war" />
</enunciate>
</target>
</project>


NOTE: I ran into an issue where it was complaining about "java.lang.NoClassDefFoundError: com/sun/mirror/apt/AnnotationProcessorFactory". To fix, I had to add jdk.home/lib/tools.jar to my classpath. I literally spent 50% of my time on this sample project trying to fix this stupid little error!

Notice the "artifactId" which is "spring.war.file". This indicates that a fully functional WAR FILE will be created. Another possible value is "spring.war.dir" which is an exploded WAR directory.

Enunciate can also produce FLEX-compatible artifacts.

Build the project by running "ant package".

Once it is successfully built, deploy dist/music-enunciate-example.war to your container. Since I'm using a default instance of jboss, I just copy it into $JBOSS_HOME/server/default/deploy and JBoss will deploy it.

Now, open your browser and hit "http://localhost:8080/music-enunciate-example". You should see the following sample page:



The web page has all the complete documentation, wsdl, and even includes a downloadable client.

Documentation is generated directly from javadocs, so as long as you follow good javadoc practices, the html documentation generated by enunciate will be great.

Customization and Modules

You can provide a configuration file that allows you to personalize URLs, namespaces, package names, documentation pages, etc. The configuration file can be provided in the enunciate ant task with the configFile attribute, or the "-f" cmd line option. It appears enunciate also makes use of a "package-info.java" class for annotations which will drive namespaces, documentation, etc.

Enunciate can be extended with modules. The core functionality of enunciate is implemented with modules. For example, the xfire-client module is responsible for generating the downloadable xfire client. The enunciate configuration file has a section which is used to configure each module. Check out this link for information on the core modules that come with enunciate.

REST
Enunciate can also generate restful services for you. This is accomplished using the "rest" module. (See Constraints enunciate places on exposing REST models)

I want to dive more into how enunciate can help with REST APIs in a future article.

Misc Questions
  1. WTF is "artifactId" in the enunciate ant target? Here's a good link which articulates what is available.

Some things I still want to investigate:
  1. How easily is it incorporated into existing projects?
    It seems that you can easily incorporate enunciate into existing projects, but you'd then have multiple ways of exposing your web services which adds project complexity.
  2. Can it handle WSDL/contract-first development?
    Enunciate is more aimed at code-first approach. Still trying to get mind around it and see if WSDL-First is possible.
  3. How does it incorporate into ant/maven? Easy. Plus, see above for a working ant script using the enunciate task.

Friday, January 04, 2008

Synergy -- Sharing a single keyboard and mouse

Synergy is a nifty little software package I just started using. It hasn't been very active for over a year, but what it provides is EXACTLY what I've needed for a long, long time.

My office desk at home is a corner/L-shaped desk with "hidden" drawers for the keyboard. I hate these hidden keyboards (or at least mine!) because my hand can't fit into the crack to grab the mouse to use it effectively. I do consider myself a fast and efficient typer, but I don't really follow a good form; therefore, reaching into a crevice at an odd angle and trying to get my bearing on a hidden keyboard is quite a challenge.

About the only thing I use my desktop for is for editing my digital photos (Canon 40D, in case you were wondering), editing some simple video of the family, and of course, playing my music from iTunes.

I work at home about 60% of the time and have a nice laptop. There are many times when I want to switch over to my desktop and do a simple quick task such as just changing the song, etc. But I'm lazy and dread scooting back my chair, pulling out the keyboard and mouse, changing the song, and then putting everything back into place.

Solution: Synergy! Synergy allows you to set up screen edges to control multiple other computers. You specify one keyboard and mouse that controls them all. Best of all, it runs on just about any OS, including Mac OS 10.2+.

I run Ubuntu 7.10 Gutsy Gibbon on laptop and Windows, so these steps are more tailored for a linux server, but it looks very trivial to set up a Windows Synergy server, too.

Step 1: Determine which computer will act as the controller ("server" in Synergy)

Step 2: Download and install Synergy on all computers you want to control.
For Ubuntu, it is as easy as "sudo apt-get install synergy"

For Windows, just run the executable.

Step 3: Configure the server
My server will be Ubuntu. The config file is located in my $HOME directory:
$ cat .synergy.conf
section: screens
ulaptop:
desktop:
end
section: links
ulaptop:
right = desktop
desktop:
left = ulaptop
end

What the config file shows is 1) what servers/clients you have and 2) how they fit together.

"section:screens" shows that I have only two computers: my server (ulaptop) and one client (desktop).

"section:links" shows where the displays are located in respect to each other. For example, for my laptop, the desktop is on the right. Vice versa, for my desktop, my laptop is on the left.

To configure a Windows Synergy server, launch Synergy and select the "Share this computer's keyboard and mouse (server)" option and then click the "Configure..." button.

These settings just tell Synergy which edges of which screens will cause transfer of the mouse and keyboard to the other computer.

Step 4: Start the server
For linux, $ synergys

For Windows, launch Synergy and select "Share this computer's keyboard and mouse (server)" option.

Step 5: Start the clients
Specify the IP address of the Synergy server. There is a test mode on the Windows client which will indicate if a successful connection is made.

Step 6: Install synergy client as a service
Optionally, you can click the "AutoStart..." button and configure Synergy as either a log-in service or a system service for Windows clients.

That's it! Took me about 10 minutes the first time I tried it and now LOVE it!

Blogging New Year!

I'm promising myself I'm going to do a better job at blogging and putting some useful, thought-inspiring content out here in 2008.

Gotta get into the practice of doing what I should have been doing for years!

Prior to this posting, you'll find a lot of useless crap; mainly just some notes I took while figuring out things in Linux, Development, etc. I figured I'd jot it down on my personal BLOG. From time-to-time I get an email letting me know it helped someone, but you'll probably find it useless.

We'll start with a quick technical note about Synergy.