Creating a Client for the New Service

Writing a Basic Service

In the BasicAPI example, you saw only the client side of the protocol at work. Also hosted on the Caucho Web site is a Burlap Web service that handles all requests from potential clients. In this section, we look at the steps required to build your own service.

Let's build a Web service that allows you to get weather information about a city. The methods provided are:

 double getRainTotals(city); string getCurrentWeather(city); 

Creating the Interface

The first step in writing your own service is to build the interface that can be shared with potential clients as well as used in building the service. Listing 8.2 shows an example of the API.

Listing 8.2: The CAServiceAPI interface code.

 package weather; import com.caucho.burlap.server.BurlapSkeleton; public interface WeatherAPI {   public double getRainTotals(String city);   public String getCurrentWeather(String city); } 

The Build Interface JAR

Just as we saw in the BasicAPI example, you need to compile the interface and placed it in a JAR file for distribution. Here are the commands for accomplishing this task. First you have to save the code in Listing 8.2 in a file called WeatherAPI.java:

 javac -d . WeatherAPI.java jar -cf WeatherAPI.jar weather 

Your Burlap service is going to be hosted by the Resin-EE server, so place the API JAR in the /resin-ee-<version>/lib directory so it can be found when needed.

Writing the Authentication Service

Now you need to write the actual code behind the server. Listing 8.3 contains the service code.

Listing 8.3: The CAService Web service.

 package weather; import com.caucho.burlap.server.BurlapServlet; public class WeatherService extends BurlapServlet implements  WeatherAPI {   public WeatherService() {   }   public double getRainTotals(String city) {   if (city.equals("Denver")) {    return 7.5;  }  else if (city.equals("Atlanta")) {    return 15.35;  } }  public String getCurrentWeather(String city) {  if (city.equals("Denver")) {    return "Snow!"; }  else if (city.equals("Atlanta")) {    return "Sunny and Warm";    }  } } 

As you can see from the signature line for the WeatherService class, a class called BurlapServlet handles most of the work for the service—all you need to do is define your exposed methods. We show both the getRainTotals() and getCurrentWeather() methods with some example code in them.

Compile the new service using a command like this one:

 java -d . WeatherService.java 

Since the service uses servlets, you need to have Java 2 Enterprise Edition (J2EE) installed. In addition, include the WeatherAPI.jar and Burlap-<version>.jar files in your classpath.

The Server Structure

As you've seen, Resin requires that applications be placed in specific directories under the /doc directory. At this point, create a new directory structure like the following:

 /doc/weather/WEB-INF/classes 

Place the WeatherService.java file into the /classes directory. So that Resin can "see" the new application, add a new <web-app> entry to the resin.conf file:

 <web-app /> 

When Resin is restarted or reads the change configuration file, the Web service will automatically be compiled and ready to be accessed.

Before you start using the new service, you also need to create a web.xml file in the new application directory. Create a file called web.xml in the /doc/weather/WEB-INF directory. Add the following to the file:

 <web-app>   <servlet-mapping>     <url-pattern>/weather/WeatherService</url-pattern>     <servlet-class>weather.WeatherService</servlet-class>   </servlet-mapping> </web-app> 

This web.xml file tells your system to execute your weather. WeatherService servlet if a URL with the pattern /weather/WeatherService is found.