23.3. An example web service

The example code that follows is from the seamBay example application, which can be found in Seam's /examples directory, and follows the recommended strategy outlined in the previous section. First, we will look at the web service class and one of its web service methods:

@Stateless
@WebService(name = "AuctionService", serviceName = "AuctionService")
public class AuctionService implements AuctionServiceRemote
{
  @WebMethod
  public boolean login(String username, String password)
  {
    Identity.instance().setUsername(username);
    Identity.instance().setPassword(password);
    Identity.instance().login();
    return Identity.instance().isLoggedIn();
  }

  // snip
}

Here, the web service is a stateless session bean annotated with the JWS annotations from the javax.jws package, as defined by JSR-181. The @WebService annotation tells the container that this class implements a web service. The @WebMethod annotation on the login() method identifies the method as a web service method. The name and serviceName attributes in the @WebService annotation are optional.

When the web service is a stateless session bean, each method that will be exposed as a web service method must also be declared in the remote interface of the web service class. In the previous example, since the AuctionServiceRemote interface is annotated as a @WebService, it must declare the login() method.

In the previous example, the web service implements a login() method that delegates to Seam's built-in Identity component. As our recommended strategy suggests, the web service is written as a simple facade. The real work takes place in a Seam component. This means that business logic is reused efficiently between web services and other clients.

In the following example, the web service method begins a new conversation by delegating to the AuctionAction.createAuction() method:

@WebMethod
public void createAuction(String title, String description, int categoryId)
{
  AuctionAction action = 
    (AuctionAction) Component.getInstance(AuctionAction.class, true);
  action.createAuction();
  action.setDetails(title, description, categoryId);
}

The code from AuctionAction is as follows:

@Begin
public void createAuction()
{
  auction = new Auction();
  auction.setAccount(authenticatedAccount);
  auction.setStatus(Auction.STATUS_UNLISTED);        
  durationDays = DEFAULT_AUCTION_DURATION;
}

Here, we see how web services can participate in long-running conversations by acting as a facade and delegating the real work to a conversational Seam component.