Ryan Heaton's Blog

OAuth is Handy

OAuth for Spring Security was released this week, and I thought I'd take a stab at why you might be interested.

What is OAuth?

I like to explain OAuth by describing the problem it is trying to solve. So here goes.

Let's say you're a sizeable social networking site and you'd like to offer a feature to your users to allow them to search their webmail contacts for import into their social network. The problem is, you (the "consumer") need access to a resource that is protected by a another site (a.k.a. "service provider"). How do you go about doing that?

Option 1: Just ask the user for his/her credentials and promise that you won't store them or do anything bad with them. Well, it works, I suppose, but this isn't a great general-purpose practice for online applications. And it's not hard to see why. Sure, you might be trustworthy, but there are plenty of other sites who are not. And what about the service provider? How would you feel about your users giving out their credentials to other sites that want access to the resources you protect?

Option 2: Use OAuth. OAuth is a protocol that was defined to address this problem. Continuing the above example, let's say that you've established a trust with the webmail service providers. You share a "secret" (which in practical terms is a passphrase or a public key or something) that you can use to gain access to the webmail contacts—provided, of course, that the user approves it. In order to gain this approval, all you have to do is redirect the user to the login page of the webmail service provider and have the user tell the service provider that it's okay that you access his/her contacts.

OAuth is a protocol standard that can be used to enable this mechanism.

How do I try it out?

OAuth for Spring Security has a really nice tutorial that walks you through setting up both a service provider and a consumer on your local box. Once those are set up, you can see OAuth in action by walking through the user flow.

How do learn more?

OAuth
Spec
FAQ
Getting Started
Illustration (Eran Hammer-Lahav)
Presentation (Leah Culver)

Enunciate 1.7: Security and Custom Content Types

Enunciate 1.7 has been released!

The primary feature of Enunciate 1.7 is support for securing your Web service endpoints using Spring Security. There is additional support for OAuth, with OpenID and WS-Security planned for 1.8.

In addition, Enunciate 1.7 introduces the concept of custom REST content types, which you can use to support custom serialization formats for REST responses (beyond the default XML and JSON endpoints).

Enjoy!

http://enunciate.codehaus.org

Web Service Programming for the Masses, Part II: Developing the RIA

The first part of this tutorial walked through the development of a Web service API that exposes its endpoints via SOAP, REST/XML, JSON, GWT-RPC, and AMF. In this second part of the tutorial, we intend to prove out this API. We will walk through building a rich AJAX application with an embedded Flash component. The AJAX application will use GWT-RPC to access the API while the Flash movie will use AMF.

For those of you who would like to see the example code on your local filesystem, you can check it out of SVN at http://svn.codehaus.org/enunciate/trunk/enunciate/src/samples/addressbook/.

Step 1: Set up the GWT application.

We first have to create our GWT application. We will use the name “net.java.apps.addressbook.AddressBookApp” to identify our application to Enunciate and GWT.

Before we continue, we have to add a project dependency on the main GWT client-side library. The added dependency declaration will go in the “dependencies” section of our pom.xml file:



  com.google.gwt
  gwt-user
  1.4.60

Then, we create our main GWT application structure. For more information, see the GWT documentation:

addressbook/src/main/gwt/net/java/apps/addressbook/AddressBookApp.gwt.xml:

addressbook/src/main/gwt/net/java/apps/addressbook/public/addressbook.html:




  AddressBook Application
  


  
  
  AddressBook Application

addressbook/src/main/gwt/net/java/apps/addressbook/client/AddressBookApp.java:


package net.java.apps.addressbook.client;

import com.google.gwt.core.client.EntryPoint;
import com.google.gwt.user.client.ui.*;

/**
 * Basic entry point for the GWT address book application.
 *
 * @author Ryan Heaton
 */
public class AddressBookApp implements EntryPoint {
  public void onModuleLoad() {
  }
}

Finally, we edit the Enunciate configuration file to point to our application so it will be compiled during the normal compile process.

addressbook/enunciate.xml:

Step 2: Set up the Flex Application

Having created the skeleton for our AJAX application using GWT, we can now set up the skeleton for developing our Flex application. This takes only a single MXML file and editing the Enunciate configuration file to point to our Flex source directory. For more information, see Adobe's documentation on developing a Flex application.

addressbook/src/main/flex/net/java/apps/addressbook/bytype.mxml:

addressbook/enunciate.xml:

*At this point, it might be convenient to rebuild our project file using Maven. The new project will contain references to the new generated code and to our GWT application.

Step 3: Write the Flex Application

We can now write our Flash component that will lookup contacts by type. Our application has only three components: a DataGrid to display the information, a ComboBox used to select the contact type, and a Button that will invoke the find and populate the DataGrid with the data. The Script tag is where we put our logic to invoke the AMF Web service method:

addressbook/src/main/flex/net/java/apps/addressbook/bytype.mxml:

You'll notice that the remote interface that we're working with in our Flex application is strongly typed (inasmuch as Flex allows it). This is because Enunciate generates the client-side ActionScript classes that are used to access the AMF endpoints (these can be found in addressbook/target/enunciate-generate/amf/client). This is a big advantage over using an ActionScript RemoteObject directly since you get compile-time type safety.

Step 4: Write the GWT Application

Our GWT Application will be a tab-based UI, with two tabs. The first tab will be a lookup of contacts by name via suggestion box. The second tab will display our Flash component that looks up contacts by type. Because we are using GWT, we have the advantage of writing the AJAX UI in Java. We'll let Enunciate handle the process of invoking GWT to compile our Java source code into JavaScript. Since this isn't a tutorial on GWT, we'll let the code do the talking.

addressbook/src/main/gwt/net/java/apps/addressbook/client/AddressBookApp.java:


package net.java.apps.addressbook.client;

import com.google.gwt.core.client.EntryPoint;
import com.google.gwt.user.client.ui.*;
import net.java.ws.addressbook.client.services.AddressBook;
import net.java.ws.addressbook.client.domain.ContactList;
import net.java.ws.addressbook.client.domain.Contact;

import java.util.Iterator;
import java.util.Collection;
import java.util.ArrayList;

/**
 * Basic entry point for the GWT address book application.
 *
 * @author Ryan Heaton
 */
public class AddressBookApp implements EntryPoint {
  public void onModuleLoad() {
    //the panel that will hold the widgets that will look up by name.
    VerticalPanel byNamePanel = new VerticalPanel();

    //the Enunciate-generated client-side GWT address book service
    final AddressBook book = new AddressBook();

    //the grid we will use to display the contacts that are found.
    final Grid contactGrid = new Grid();

    //the oracle that will make a remote call to populate the suggest box.
    SuggestOracle oracle = new SuggestOracle() {
      public void requestSuggestions(final Request request, final Callback callback) {
        String query = request.getQuery();

        //call the method to find contacts by name.
        book.findContactsByName(query, new AddressBook.FindContactsByNameResponseCallback() {
          public void onResponse(ContactList response) {
            Iterator contactIt = response.getContacts().iterator();
            Collection suggestions = new ArrayList();
            while (contactIt.hasNext()) {
              final Contact contact = (Contact) contactIt.next();

              //add the suggestion.
              suggestions.add(new Suggestion() {
                public String getDisplayString() {
                  return contact.getName();
                }

                public String getReplacementString() {
                  return contact.getName();
                }
              });
            }

            contactGrid.clear(); //clear the grid.
            callback.onSuggestionsReady(request, new Response(suggestions));
          }

          public void onError(Throwable throwable) {
            //do nothing if an error occurs while asking for suggestions
          }
        });
      }
    };

    //the suggest box (instantiated with our oracle).
    final SuggestBox suggestBox = new SuggestBox(oracle);

    //The panel that will hold the suggest box and the "find" button.
    HorizontalPanel findForm = new HorizontalPanel();
    findForm.add(suggestBox);

    //the "find" button.
    Button findButton = new Button("find");
    findButton.addClickListener(new ClickListener() {
      public void onClick(Widget widget) {
        //when "find" is clicked, make the query and populate the grid.
        String text = suggestBox.getText();
        book.findContactsByName(text, new AddressBook.FindContactsByNameResponseCallback() {
          public void onResponse(ContactList response) {
            contactGrid.resize(6 * response.getContacts().size(), 2);
            Iterator contactIt = response.getContacts().iterator();
            int i = 0;
            while (contactIt.hasNext()) {
              Contact contact = (Contact) contactIt.next();
              contactGrid.setWidget(++i, 0, new Label("Name:"));
              contactGrid.setWidget(i, 1, new Label(contact.getName()));
              contactGrid.setWidget(++i, 0, new Label("Phone:"));
              contactGrid.setWidget(i, 1, new Label(contact.getPhone()));
              contactGrid.setWidget(++i, 0, new Label("Address:"));
              contactGrid.setWidget(i, 1, new Label(contact.getAddress1()));
              contactGrid.setWidget(++i, 0, new Label("City:"));
              contactGrid.setWidget(i, 1, new Label(contact.getCity()));
              contactGrid.setWidget(++i, 0, new Label("Type:"));
              contactGrid.setWidget(i, 1, new Label(contact.getContactType()));
              contactGrid.setWidget(++i, 0, new HTML(""));
              contactGrid.setWidget(i, 1, new HTML(""));
            }
          }

          public void onError(Throwable throwable) {
            //if an error while doing a "find," display it in the grid.
            contactGrid.resize(1, 1);
            contactGrid.setWidget(0, 0, new Label("ERROR: " + throwable.getMessage()));
          }
        });
      }
    });

    //add the find button.
    findForm.add(findButton);

    //add the find form to the panel.
    byNamePanel.add(findForm);

    //add the display grid to the panel.
    byNamePanel.add(contactGrid);

    //create the tab panel.
    TabPanel panel = new TabPanel();

    //add the find by name panel to the tab panel.
    panel.add(byNamePanel, " by name ", true);

    //create some HTML that will embed our flash component.
    HTML flashHTML = new HTML("\n" +
              "\n" +
              "\n" +
              "\n" +
              "");

    //add the flash component to the other tab in the tab panel.
    panel.add(flashHTML, " by type ", true);

    //add the tab panel to the root HTML.
    RootPanel.get().add(panel);
  }
}

You'll notice that Enunciate has also generated client-side code for accessing our Web service API via GWT. Again, this adds significant benefits in terms of type safety and simplifies the creation of the initial environment.

Step 5: Build, Package, and Run the Application

Once again, we run

mvn jetty:run-war

Assuming everything builds correctly, we can navigate to http://localhost:8080/addressbook/addressbook.html and see our Rich AJAX Application with an embedded Flash component, both of which make dynamic calls to our Web service API.

Web Service Programming for the Masses, Part I: Developing the Web Service API

So you've got a web application that needs to expose a Web service API. Maybe you're going to be writing a Rich Internet Application (RIA) using Flex or some AJAX Framework. Or maybe you'll be developing a desktop application that needs to interface with your online data. Or perhaps you've got a few business partners that want to integrate with your application.

Whatever the reason, you need a solution that not only fits your client-side requirements, but one that is also easy to develop, easy to debug, easy to maintain, and easy to enhance. Don't be too hasty with your choice of a Web service implementation technology. REST is not always the best answer. It might be, but not always. Take some time to research your needs, gather your requirements, and look at other remoting technologies that are available. Then decide what you need.

This is the first part of a tutorial will walk you through developing a Web service API that could meet the requirements of all of the above-mentioned use cases. For the sake of clarity and brevity, we'll keep the operations simple, but by the time we're done, we'll have a fully-functional Web service API that exposes a bouquet of endpoints: SOAP, REST/XML, JSON, GWT-RPC, and even AMF (for all you Flex developers). In Part II of this tutorial, we'll prove out the Web service API by building a rich AJAX application with an embedded Flash component that accesses it.

By the end of this two-part tutorial, we'll have established a good custom-fit Web service development process for maintaining your Web service API in your favorite development environment.

For those of you who would like to see the example code on your local filesystem, you can check it out of SVN at http://svn.codehaus.org/enunciate/trunk/enunciate/src/samples/addressbook/.

Step 1: Create Your Project

We will be exposing a Web service API for an address book application. We will be using Maven 2 and Enunciate 1.6 to build and package our application. (Note that we could also use Ant to build the application, but Maven will get us started more quickly.)

We'll label our application “addressbook” and assign it a group id “net.java.ws.addressbook”. Assuming Maven is already installed, we can use its archetype plugin to bootstrap the project from the command line:

mvn archetype:create -DgroupId=net.java.ws.addressbook -DartifactId=addressbook

This will create a simple project for us with an empty Java source file and an associated test. You can open up the project in your favorite IDE; Maven has plugins available that will create project files for whichever one you like to work with.

Before our project is fully usable, we need to tweak it to declare our dependencies, configure the compile settings, and add any additional build tools. As for our dependencies, we need only one additional dependency on Enunciate's runtime libraries (groupId: org.codehaus.enunciate, artifactId:enunciate-rt). We also need to declare a Maven plugin for Enunciate to build the Web service application (with the “assemble” goal). For deployment, we can use the Maven Jetty plugin to deploy and run the application. Finally, we need to configure Maven's compiler plugin to compile for JDK 1.5 compatability and make sure we're using “war” packaging since we're building a web application. In the end, our project descriptor looks like this:

addressbook/pom.xml:



  4.0.0
  net.java.ws.addressbook
  addressbook
  war
  1.0-SNAPSHOT
  addressbook
  
    
      
        org.codehaus.enunciate
        maven-enunciate-plugin
        1.6
        
          
            
              assemble
            
          
        
      

      
        org.mortbay.jetty
        maven-jetty-plugin
      

      
        org.apache.maven.plugins
        maven-compiler-plugin
        
          1.5
          1.5
        
      
    
  
  
    
      org.codehaus.enunciate
      enunciate-rt
      1.6
    

    
      junit
      junit
      3.8.1
      test

Step 2: Create Your Domain

The domain of an address book application is very simple. It consists of a basic Contact object. The Contact has fields for an id, name, phone number, two address fields, and city. We'll also add a contact type enumeration object ("friend", "family", or "professional") and create an object representing a contact list for use when we want to retrieve multiple contacts from a Web service request. You'll also note that we've annotated Contact and ContactList with a JAXB annotation, @javax.xml.bind.annotation.XmlRootElement, which will allow us to return these types as XML elements from a REST request (see below).

addressbook/src/main/java/net/java/ws/addressbook/domain/Contact.java:


package net.java.ws.addressbook.domain;

import javax.xml.bind.annotation.XmlRootElement;

/**
 * A contact in the address book.
 *
 * @author Ryan Heaton
 */
@XmlRootElement
public class Contact {

  private int id;
  private String name;
  private String phone;
  private String address1;
  private String address2;
  private String city;
  private ContactType contactType;

  /**
   * The id of the contact.
   *
   * @return The id of the contact.
   */
  public int getId() {
    return id;
  }

  /**
   * The id of the contact.
   *
   * @param id The id of the contact.
   */
  public void setId(int id) {
    this.id = id;
  }

  /**
   * The name of the contact.
   *
   * @return The name of the contact.
   */
  public String getName() {
    return name;
  }

  /**
   * The name of the contact.
   *
   * @param name The name of the contact.
   */
  public void setName(String name) {
    this.name = name;
  }

  /**
   * The phone of the contact.
   *
   * @return The phone of the contact.
   */
  public String getPhone() {
    return phone;
  }

  /**
   * TThe phone of the contact.
   *
   * @param phone The phone of the contact.
   */
  public void setPhone(String phone) {
    this.phone = phone;
  }

  /**
   * The first address field of the contact.
   *
   * @return The first address field of the contact.
   */
  public String getAddress1() {
    return address1;
  }

  /**
   * The first address field of the contact.
   *
   * @param address1 The first address field of the contact.
   */
  public void setAddress1(String address1) {
    this.address1 = address1;
  }

  /**
   * The second address field of the contact.
   *
   * @return The second address field of the contact.
   */
  public String getAddress2() {
    return address2;
  }

  /**
   * The second address field of the contact.
   *
   * @param address2 The second address field of the contact.
   */
  public void setAddress2(String address2) {
    this.address2 = address2;
  }

  /**
   * The city of the contact.
   *
   * @return The city of the contact.
   */
  public String getCity() {
    return city;
  }

  /**
   * The city of the contact.
   *
   * @param city The city of the contact.
   */
  public void setCity(String city) {
    this.city = city;
  }

  /**
   * The contact type.
   *
   * @return The contact type.
   */
  public ContactType getContactType() {
    return contactType;
  }

  /**
   * The contact type.
   *
   * @param contactType The contact type.
   */
  public void setContactType(ContactType contactType) {
    this.contactType = contactType;
  }
}

addressbook/src/main/java/net/java/ws/addressbook/domain/ContactType.java:


package net.java.ws.addressbook.domain;

/**
 * A contact type.
 *
 * @author Ryan Heaton
 */
public enum ContactType {

  friend,

  family,

  professional

}

addressbook/src/main/java/net/java/ws/addressbook/domain/ContactList.java:


package net.java.ws.addressbook.domain;

import javax.xml.bind.annotation.XmlRootElement;
import java.util.Collection;

/**
 * A list of contacts.
 *
 * @author Ryan Heaton
 */
@XmlRootElement
public class ContactList {

  private Collection contacts;

  /**
   * The contact list.
   *
   * @return The contact list.
   */
  public Collection getContacts() {
    return contacts;
  }

  /**
   * The contact list.
   *
   * @param contacts The contact list.
   */
  public void setContacts(Collection contacts) {
    this.contacts = contacts;
  }
}

Step 3: Create Your Services

The next step involves creating the services that will comprise our Web service API. We'll create an AddressBook interface that defines three operations: getContact, findContactsByName, and findContactsByType, each of them throwing an AddressBookException in case something goes wrong.

Furthermore, we have to identify our interface as a Web service. We do this by applying the JAX-WS annotation @javax.jws.WebService to the interface. As it turns out, this service interface also lends itself nicely to a mapping to a REST endpoint. We can decide, for example, to map the getContact method to an HTTP GET that will take the id parameter from the URL in the form of a context parameter. To perform the mapping to a resource-oriented interface, we use Enunciate's proprietary REST annotations (@RESTEndpoint, @Noun, @Verb, @ProperNoun, etc.)

addressbook/src/main/java/net/java/ws/addressbook/services/AddressBook.java:


package net.java.ws.addressbook.services;

import net.java.ws.addressbook.domain.ContactList;
import net.java.ws.addressbook.domain.Contact;
import net.java.ws.addressbook.domain.ContactType;

import javax.jws.WebService;

import org.codehaus.enunciate.rest.annotations.*;

/**
 * An address book that provides access to a set of contacts.
 *
 * @author Ryan Heaton
 */
@WebService
@RESTEndpoint
public interface AddressBook {

  /**
   * Get a contact by id.
   *
   * @param id The id of the contact.
   * @return The contact.
   * @throws AddressBookException If the contact wasn't found.
   */
  @Noun (
    "contact"
  )
  @Verb (
    VerbType.read
  )
  Contact getContact(@ProperNoun Integer id) throws AddressBookException;

  /**
   * Find contacts by name.
   *
   * @param name The name to search for.
   * @return The contacts that were found.
   */
  ContactList findContactsByName(String name) throws AddressBookException;

  /**
   * Find contats by type.
   *
   * @param type The type of contact.
   * @return The contacts.
   */
  ContactList findContactsByType(ContactType type) throws AddressBookException;
}

addressbook/src/main/java/net/java/ws/addressbook/services/AddressBookException.java:


package net.java.ws.addressbook.services;

/**
 * @author Ryan Heaton
 */
public class AddressBookException extends Exception {

  public AddressBookException(String message) {
    super(message);
  }
}

Of course, we have to create an implementation of the AddressBook. This is what will query our database and perform the business logic of our application. For the purposes of this tutorial, we'll just create a simple in-memory store of contacts.

Our implementation must also reference its Web service interface in order to be identified as the implementation for the Web service. We again use the JAX-WS-specified @javax.jws.WebService and the Enunciate-specific @RESTEndpoint annotation to accomplish this.

addressbook/src/main/java/net/java/ws/addressbook/impl/AddressBookImpl.java:


package net.java.ws.addressbook.impl;

import net.java.ws.addressbook.services.AddressBook;
import net.java.ws.addressbook.services.AddressBookException;
import net.java.ws.addressbook.domain.Contact;
import net.java.ws.addressbook.domain.ContactList;
import net.java.ws.addressbook.domain.ContactType;

import java.util.*;

import org.codehaus.enunciate.rest.annotations.RESTEndpoint;

import javax.jws.WebService;

/**
 * @author Ryan Heaton
 */
@WebService (
  endpointInterface = "net.java.ws.addressbook.services.AddressBook"
)
@RESTEndpoint
public class AddressBookImpl implements AddressBook {

  private static final Map STORE = loadContacts();

  public Contact getContact(Integer id) throws AddressBookException {
    Contact contact = STORE.get(id);
    if (contact == null) {
      throw new AddressBookException("contact not found: " + id);
    }
    return contact;
  }

  public ContactList findContactsByName(String name) throws AddressBookException {
    ArrayList contacts = new ArrayList();
    if (name != null) {
      for (Contact contact : STORE.values()) {
        if (contact.getName().toLowerCase().contains(name.toLowerCase())) {
          contacts.add(contact);
        }
      }
    }
    ContactList list = new ContactList();
    list.setContacts(contacts);
    return list;
  }

  public ContactList findContactsByType(ContactType type) throws AddressBookException {
    ArrayList contacts = new ArrayList();
    for (Contact contact : STORE.values()) {
      if (contact.getContactType().equals(type)) {
        contacts.add(contact);
      }
    }
    ContactList list = new ContactList();
    list.setContacts(contacts);
    return list;
  }

  private static Map loadContacts() {
    final int size = 20;
    Random random = new Random();
    String[] firstNames = new String[]{"Sally", "George", "Harold", "Tammy", "Robert", "Daniel", "Jane", "Mike", "David", "John"};
    String[] lastNames = new String[]{"Beach", "Jobs", "Gates", "Bush", "Clinton", "Gore", "Moore", "Jones", "Adams", "Washington", "Smith"};
    String[] addresses = new String[]{"1 First Street", "2 Second Street", "3 Third Street"};
    String[] cities = new String[]{"Long Beach, CA", "New York, NY", "Orlando, FL", "Honolulu, HI", "Oklahoma City, OK"};
    String[] phoneNumbers = new String[]{"111-1111", "222-2222", "333-3333", "444-4444", "555-5555", "666-6666", "777-7777"};

    HashMap contacts = new HashMap();
    for (int i = 0; i < size; i++) {
      Contact contact = new Contact();
      contact.setId(i);
      contact.setName(firstNames[random.nextInt(firstNames.length)] + " " + lastNames[random.nextInt(lastNames.length)]);
      contact.setAddress1(addresses[random.nextInt(addresses.length)]);
      contact.setCity(cities[random.nextInt(cities.length)]);
      contact.setPhone(phoneNumbers[random.nextInt(phoneNumbers.length)]);
      contact.setContactType(ContactType.values()[random.nextInt(ContactType.values().length)]);
      contacts.put(i, contact);
    }

    return Collections.unmodifiableMap(contacts);
  }
}

Step 4: Enable and Configure GWT and AMF (Flex Data Services) Endpoints.

Enunciate will publish your Web service API as GWT-RPC endpoints and AMF (Flex Data Services) endpoints if you enable this option in the Enunciate configuration file. The configuration for the GWT module requires a path to the installed Google Web Toolkit and a name for the client module that will be generated (see the GWT documentation for details). The configuration for the AMF module requires a path to the installed Flex SDK.

addressbook/enunciate.xml:

Step 5: Build, Package, and Run the Application

Since we've got everything set up and all our endpoints configured, we can now use Maven to invoke Enunciate, build, package, and even deploy our application to Jetty by running the command:

mvn jetty:run-war

Assuming everything builds as expected, Jetty should be running your Web service API. Things to note:

You can see the documentation for your Web service API by browsing to http://localhost:8080/addressbook/index.html. You'll notice that Enunciate generated full documentation for your Web service API scraped from your JavaDocs. You've got your SOAP endpoints and REST endpoints documented along with the documentation for the data types.
Each of the endpoints are up and running and servicing requests. Your browser doesn't know how to format requests for the SOAP endpoints, GWT endpoints, or the AMF endpoints, but you can see that the endpoints are at least responding to invalid requests by browsing to http://localhost:8080/addressbook/soap/AddressBookService, http://localhost:8080/addressbook/gwt/AddressBookService, and http://localhost:8080/addressbook/amf/AddressBookService.
Your browser does, however, know how to format a REST request. You can see the XML for a contact by making a request to http://localhost:8080/addressbook/rest/contact/4, for example. Or, to see the same contact in JSON format, browse to http://localhost:8080/addressbook/json/contact/4.
Enunciate automatically generates client-side code that can be used to access your SOAP endpoints, GWT endpoints, and AMF endpoints (ActionScript classes). By default, the client-side libraries that can access your SOAP endpoints are provided as downloads from your Web service API. To see these downloads, navigate to http://localhost:8080/addressbook/downloads.html. You can also configure Enunciate to make the client-side GWT code and ActionScript classes available for download from the download page. They are not available as a download by default because they are subject to cross-site scripting restrictions and are usually for internal consumption (see Part II).

Enunciate 1.6: AMF Endpoints for Flex Developers

If you haven't checked out the Enunciate project recently, you may want to give it another look to see how it can improve the development, deployment, and consumption of your Web service API.

Enunciate 1.6 was just released with support for mounting your JAX-WS endpoint classes via AMF (thanks to Adobe's release of BlazeDS). This should be really interesting to Flex developers. Not only will you be able to make Web service calls via AMF, but Enunciate will also generate type-safe client-side ActionScript classes that will access those endpoints.

Enunciate will also publish your endpoints via SOAP, REST/XML, JSON, and GWT. You'll also get your WSDLs, schemas, and full user-level documentation of your Web service API.

I'll be shortly posting a two-part tutorial on how to publish this kind of a rich API with your service endpoints and how to write an AJAX app with an embedded Flash component that consumes it.

Enunciate 1.5 Released

Enunciate 1.5 makes some dramatic improvements in the GWT application development experience. Included in the distribution bundle is a new pet clinic sample application that will demonstrate how to publish the pet clinic Web service API and how to develop a nice AJAX app for the pet clinic using GWT.

http://enunciate.codehaus.org

Why ROI vs. SOI (read "REST vs. SOAP") Still Matters

The honeymoon with RESTful Web services is over. Now that we've had some time to get over the infatuation, let's take a fresh look at the principles of sound Web service API design. Despite how rocky our relationship with SOAP has been, it's time to confront our prejudices and accept both technologies for their virtues and vices.

In fact, I propose we give this discussion a new identity in order to help us put the painful memories, bitter tears, and long, sleepless nights behind us. Because it's not really about REST vs. SOAP anymore, is it? A well-designed Web service API is so much more important than the technology we use to implement it. So after we get past the name-calling and mud slinging, what we're left with is a set of fundamental architectural principles for Web service API design.

On the REST side of the playing field we have engineers who have a set of well-defined resources that they want to make available by defining a constrained set of basic operations that can be applied. On the other side, we have engineers whose operations are much more complex, maybe contextual, and perhaps interdependent. These engineers may or may not have a well-defined set of resources to which these operations apply. Rather than making a set of resources available, these engineers have a set of services they want to make available.

So on one end of the spectrum we have the need to design a Resource-Oriented Interface (ROI). On the other end, we have the need to design a Service-Oriented Interface (SOI).

Determining what kind of an API is to be published should be the first step in designing a good Web service API. And, trust me, it's not always easy to determine where your API fits. You may, for example, have a well-defined set of Gismo objects to which you can limit your operations to be create, read, update, and delete. But what if you want to provide a search operation for Gismos? In this case, the boundaries of the resource and the operation are less clear.

In any case, you will be able to make a much better choice of a development technology if you can first define whether your API is more Resource-Oriented or Service-Oriented. (By the way, it'll probably fit somewhere in between.) Choosing the development technology first is letting the tail wag the dog.

Still unconvinced? May I suggest that you subscribe to one or more of the common misconceptions about the current state of Web service development? Let's debunk those right now, shall we?

It is not easier to design a good Resource-Oriented Interface (think "REST") than it is to design a good Service-Oriented Interface. Actually, I'd suggest that for most engineers, an SOI is more intuitive than a ROI.
It is not easier to implement an ROI than it is to implement an SOI. In fact, the tools these days are much more mature for SOI. I've found that ROI developers often have to work directly with low-level protocol APIs, although that's changing fast.
It is not easier to consume an ROI than it is to consume an SOI. Which type of interface is easier to consume always depends on the platform of the consumers. Are they using a high-level, compiled programming language or are they in looser, more interpreted environment?
An SOI is not any less interoperable than an ROI. I'm going to assert that we've pretty much solved the issue of interoperability. I'm sure there are many of you who might disagree. Bring it on.
SOAP is not the only technology for implementing an SOI. Really. Just because you have a more service-oriented API doesn't mean you have to use SOAP. (Really? Whew!)
ROI is not always the best choice for supporting RIAs. Many AJAX frameworks (e.g. GWT) have their own RPC mechanisms that are much more SOI than they are ROI. Another example for Flash is AMF.

So what do you think? I say let's adopt a rational, reasonable approach to Web service API design and stop letting the tail wag the dog.

Enunciate 1.4: Your JAX-WS endpoint published as a GWT-RPC endpoint

When you use Enunciate 1.4 to publish your Web service API, Enunciate will build you a war that you can drop into your favorite webapp container. The war will supply any or all of the following, depending on your configuration:

Full documentation (scraped from the JavaDocs)
Your service beans mounted via SOAP, along with the formal contract (WSDL, schemas, etc.)
Those same service beans mounted via REST/XML.
Those same service beans mounted via JSON.
Those same service beans mounted as GWT-RPC endpoints.
Client-side libraries for download (used for invoking your API programatically via SOAP).
Client-side GWT Java libraries that can be used with GWT to support an AJAX app.
Etc.

If you want to know more, I suggest a quick walk through the getting started guide.

http://enunciate.codehaus.org/

Enunciate 1.3 Released

Enunciate 1.3 includes support for applying aspects to service beans, customization of endpoint URLs, and many bug fixes and minor enhancements. See the release notes for details.

Enunciate 1.2 Released

Maps and support for type adapters were the two features most requested from those using Enunciate (and the two features that most often precluded more use from those wanting to use Enunciate).

Of course, the release includes numerous bug fixes and some user experience enhancements.

http://enunciate.codehaus.org

Enunciate 1.1 Released

Enunciate 1.1 was released yesterday, adding support for Maven 2. There were also some bug fixes and usability enhancements that were added, thanks to user feedback.

Enunciate is a Web service development platform. Starting from the source code of your Web service API, Enunciate will produce a fully-functional webapp runnable from your favorite J2EE container that supports SOAP, REST/XML, and REST/JSON endpoints. Enunciate will also publish user-level HTML documentation for your API and make fully-compatible client libraries available for download from the deployed application.

My Two-Edged Arsenal

I'm Ryan Heaton, and I'm delighted to be given blog space at Java.net. I hope my contributions will add something of value to this terrific community.

My expertise pivots around Web service design and development, so I often find myself wielding some pretty sharp two-edged tools: WSDL, XML Schema, JAX-WS, JAXB 2.0, SOAP, REST, etc. Believe me, I've got plenty of experience nursing the wounds that come from using such dangerous gear. But by now, I'm pretty good at avoiding these kinds of injuries, and I strongly believe there are no better tools for the job.

And I want to help make life less hazardous for other Web service developers. To this end, I authored the compiled contract model for Web service development and an associated Web service development framework called Enunciate. They also let me on the expert group for JSR 311.

I consider myself both a SOAP advocate and a REST advocate, depending on the problem at hand. I also strongly believe that contract-first Web service development should only be used as a last resort.

I'm currently employed as the lead engineer of the Web service API for FamilySearch.org. We're developing an online web application designed to be a free and open database for genealogical information. The goal is to become a common repository of family history records and information for the entire world in an effort to reduce duplication and consolidate effort in genealogical research.

I'm a graduate of Brigham Young University. I currently reside in Salt Lake City, and I'm the father of four boys.

I love life.