Defining a Service Endpoint Interface

The first step in the creation of a JAX-WS web service is to create a Service Endpoint Interface, a Java interface that defines the methods that clients can call when they’re using the web service.

The SquareRootServer web service you are developing this hour is a service that can handle two simple tasks:

• Calculating the square root of a number

• Displaying the current date and time

An interface is a set of methods that provides names, arguments, and return types but does not contain code that implements the methods. The interface serves as a contract between objects—if an object implements an interface, other objects know they can call all the interface’s methods on that object.

In Hour 15, “Responding to User Input,” you had to implement the ActionListener interface in any Java class that needed to receive action events when a button was clicked.

For this project, you’re handling the other side of the contract. The SquareRootServer interface defines two methods that must be present in a class that implements the web service: squareRoot(double) and getTime().

The following statements define the interface:

public interface SquareRootServer {
    double getSquareRoot(double input);
    String getTime();
}

The method definitions in an interface are followed by a semicolon rather than { and } characters around a block statement. Interfaces don’t define the behavior of methods; that’s handled by classes that implement the interface.

Because these methods can be called as a JAX-WS web service, an extra modifier must be added in front of each one, the annotation @WebMethod:

public interface SquareRootServer {
    @WebMethod double getSquareRoot(double input);
    @WebMethod String getTime();
}

Using Annotations to Simplify Java Code

Annotations are a smarter form of comments that can be understood by the Java interpreter, compiler, and programming tools. They provide a way to define information about a program that’s not part of the program itself but which can trigger actions when the program is compiled or run.

Annotations begin with an @ sign followed by the name of the annotation.

One of the most common annotations is @Override, which indicates a method overrides a superclass method. Here’s an example:

@Overrides public void paintComponent(Graphics comp) {
    // definition of method here
}

If you’ve made an error and it does not override a method—which would happen if you used the wrong type or number of parameters—the compiler can catch the error.

The @WebMethod annotation indicates that a method can be called as a web service. The SquareRootServer interface also uses an @WebService annotation that indicates the interface defines a service endpoint interface.

Annotations can take parameters that provide further customization. SquareRootServer includes one final annotation:

@SOAPBinding(style = Style.RPC)

This annotation helps define the contract between the web service and the client programs that call the service. You learn more about this later in the hour.

For now, it’s time to begin coding the web service. Create a new empty Java file in NetBeans with the class name SquareRootServer and the package name com.java24hours.ws. Enter the contents of Listing 22.1 into the file.

Listing 22.1. The Full Text of SquareRootServer.java

 1: package com.java24hours.ws;
 2:
 3: import javax.jws.*;
 4: import javax.jws.soap.*;
 5: import javax.jws.soap.SOAPBinding.*;
 6:
 7: @WebService
 8:
 9: @SOAPBinding(style = Style.RPC)
10:
11: public interface SquareRootServer {
12:     // get the square root of a number
13:     @WebMethod double getSquareRoot(double input);
14:
15:     // get the current time and date as a string
16:     @WebMethod String getTime();
17:
18: }

This class has been placed in the com.java24hours.ws package, a design decision that makes it easier for the web service to be deployed for other software to access over the Internet.

Now that you’ve finished defining this interface, you’re ready to write the code that implements its two methods: getSquareRoot() and getTime().