Chapter 3 Service Endpoint Design

81

A Web service application may encounter two types of error conditions. One

type of error might be an irrecoverable system error, such as an error due to a

network connection problem. When an error such as this occurs, the JAX RPC

runtime on the client throws the client platform's equivalent of an irrecoverable

system exception. For Java clients, this translates to a 

RemoteException

.

A Web service application may also encounter a recoverable application error

condition. This type of error is called a service specific exception. The error is

particular to the specific service. For example, a weather Web service might indi 

cate an error if it cannot find weather information for a specified city.

To illustrate the Web service exception handling mechanism, let's examine it

in the context of the weather Web service example. When designing the weather

service, you want the service to be able to handle a scenario in which the client

requests weather information for a nonexistent city. You might design the service

to throw a service specific exception, such as 

CityNotFoundException

, to the

client that made the request. You might code the service interface so that the

getWeather

 method throws this exception. (See Code Example 3.9.)

public interface WeatherService extends Remote {

public String getWeather(String city) throws 

CityNotFoundException, RemoteException;

}

Code Example 3.9

Throwing a Service Specific Exception

Service specific exceptions like 

CityNotFoundException

, which are thrown

by the Web service to indicate application specific error conditions, must be

checked exceptions that directly or indirectly extend 

java.lang.Exception

. They

cannot be unchecked exceptions. Code Example 3.10 shows a typical implemen 

tation of a service specific exception, such as for 

CityNotFoundException

.

public class CityNotFoundException extends Exception {

private String message;

public CityNotFoundException(String message) {

super(message);

this.message = message;

}

public String getMessage() {

return message;