3 Developing and Deploying Java Class Web Services

3.2.2.1 Defining a Java Class Containing Methods for the Web Service

Create a Java Web Service by writing or supplying a Java class with methods that are deployed as a Web Service. In the sample supplied in the java_services sample directory, the .ear file, ws_example.ear contains the Web Service source, class, and configuration files. In the expanded .ear file, the class StatefulExampleImpl provides the stateful Java service and StatelessExampleImpl provides the stateless Java service.

When writing a Java Web Service, if you want to place the Java service in a package, use the Java package specification to name the package. The first line of StatefulExampleImpl.java specifies the package name, as follows:

package oracle.j2ee.ws_example;

The stateless sample Web Service is implemented with StatelessExampleImpl, a public class. The class defines a public method, helloWorld(). In general, a Java class for a Web Service defines one or more public methods.

Example 3-1 shows StatelessExampleImpl.

The stateful sample Web Service is implemented with StatefulExampleImpl, a public class. The class initializes the count and defines two public methods, count() and helloWorld().

Example 3-2 shows StatefulExampleImpl.

package oracle.j2ee.ws_example;

public class StatelessExampleImpl {
    public StatelessExampleImpl() {
  }
  public String helloWorld(String param) {
    return "Hello World, " + param;
  }
}

package oracle.j2ee.ws_example;

public class StatefulExampleImpl {
  int count = 0;
  public StatefulExampleImpl() {
  }
  public int count() {
    return count++;
  }
  public String helloWorld(String param) {
    return "Hello World, " + param;
  }
}

There are several additional steps required to implement a Java Web Service if you need to handle or process SOAP request header entries.

3.2.2.2 Defining an Interface for Explicit Method Exposure

Oracle Application Server Web Services allows you to limit the methods you expose as Web Services by supplying a public interface. To limit the methods exposed in a Web Service, include a public interface that lists the method signatures for the methods that you want to expose. Example 3-3 shows an interface to the method in the class StatelessExampleImpl. Example 3-4 shows an interface to the methods in the class StatefulExampleImpl.

package oracle.j2ee.ws_example;

public interface StatelessExample {
  String helloWorld(String param);
}

package oracle.j2ee.ws_example;

public interface StatefulExample {
   int count();
   String helloWorld(String param);
}

Use a Web Services interface for the following purposes:

1. To limit the exposure of methods to a subset of the public methods within a class.

2. To expand the set of methods that are exposed as Web Services to include methods within the superclass of a class.

3. To limit the exposure of methods to a subset of the public methods within a class, where the subset contains only the methods that use supported types for parameters or return values. Table 3-1 lists the supported types for parameters and return values for Java methods that implement Web Services.

   
   

   See Also: "Using Supported Data Types for Java Web Services"

   
   

3.2.2.3 Writing a WSDL File (Optional)

The WebServicesAssembler supports the <wsdl-gen> and <proxy-gen> tags to allow a Web Service developer to generate WSDL files and client-side proxy files. You can use these tags to control whether the WSDL file and the client-side proxy are generated. Using these tags you can also specify that the generated WSDL file or a WSDL file that you write is packaged with the Web Service J2EE .ear.

A client-side developer either uses the WSDL file that is obtained from a deployed Web Service, or the client-side proxy that is generated from the WSDL to build an application that uses the Web Service.

3.3.1.1 Adding Web Service Top Level Tags

Table 3-2 describes the top level WebServicesAssembler configuration file tags. Add these tags to provide top level information describing the Java Stateless Web Service or a Java Stateful Web Service. These tags are included within a <web-service> tag in the configuration file.

Example 3-5 shows a complete config.xml file, including the top level tags.

<option name="source-path" contextroot="/test">/myTestArea/ws/src/statefull.war</option>

3.3.1.2 Adding Java Stateless Service Tags

Prepare Java Stateless Web Services using the WebServicesAssembler <stateless-java-service> tag. This tag is included within a <web-service> tag in the configuration file. Add this tag to provide information required for generating a Stateless Java Web Service.

Table 3-3 shows the <stateless-java-service> sub-tags and the <stateful-java-service> sub-tags. As noted in Table 3-3, some of the sub-tags listed only apply when using a <stateful-java-service>.

Example 3-5 shows a complete config.xml file, including <stateless-java-service>.

3.3.1.3 Adding Java Stateful Service Tags

Prepare Java Stateful Web Services using the WebServicesAssembler <stateful-java-service> tag. This tag is included within a <web-service> tag in the configuration file. Add this tag to provide information required for generating a Stateful Java Web Service.

To support a clustered environment, for stateful Java Web Services with serializable java classes, the WebServicesAssembler adds a <distributable> tag in the web.xml of the Web Service's generated J2EE.ear file.

Table 3-3 shows the <stateful-java-service> sub-tags.

Example 3-5 shows a complete config.xml file, including <stateful-java-service>.

<web-service>
    <display-name>Web Services Example</display-name>
    <description>Java Web Service Example</description>
    <!-- Specifies the resulting web service archive will be stored in
         ./ws_example.ear -->
    <destination-path>./ws_example.ear</destination-path>
    <!-- Specifies the temporary directory that web service assembly 
         tool can create temporary files. -->
    <temporary-directory>./tmp</temporary-directory>
    <!-- Specifies the web service will be accessed in the servlet context
         named "/webservices". -->
    <context>/webservices</context>

    <!-- Specifies the web service will be stateless -->
    <stateless-java-service>
        <interface-name>oracle.j2ee.ws_example.StatelessExample</interface-name>
        <class-name>oracle.j2ee.ws_example.StatelessExampleImpl</class-name>
        <!-- Specifies the web service will be accessed in the uri named
             "statelessTest" within the servlet context. -->
        <uri>/statelessTest</uri>
        <!-- Specifies the location of Java class files are under
             ./src -->
        <java-resource>./src</java-resource>
    </stateless-java-service>

    <stateful-java-service>
        <interface-name>oracle.j2ee.ws_example.StatefulExample</interface-name>
        <class-name>oracle.j2ee.ws_example.StatefulExampleImpl</class-name>
        <!-- Specifies the web service will be accessed in the uri named
             "statefullTest" within the servlet context. -->
        <uri>/statefulTest</uri>
        <!-- Specifies the location of Java class files are under
             ./src -->
        <java-resource>./src</java-resource>
    </stateful-java-service>
</web-service>

3.3.1.4 Adding WSDL and Client-Side Proxy Generation Tags

The WebServicesAssembler supports the <wsdl-gen> and <proxy-gen> tags to allow a Web Service developer to generate WSDL files and client-side proxy files. You can use these tags to control whether the WSDL file and the client-side proxy are generated. Using these tags you can also specify that the generated WSDL file or a WSDL file that you supply is packaged with the Web Service J2EE .ear.

A client-side developer can use the WSDL file that is obtained from a deployed Web Service, or the client-side proxy that is generated from the WSDL to build an application that uses the Web Service.