Working with JAX-RPC, Page 2
The xrpcc Tool
The xrpcc tool creates the following for you:
The stubs and ties.
A server configuration file. This file is not part of the JAX-RPC specification as such, but it is used by the Tomcat Web server.
If the Web service is a JAX-RPC implementation, the xrpcc tool generates the WSDL document describing the Web service from the RMI interface.
If the Web service is not a JAX-RPC implementation, you can use the xrpcc tool to generate the RMI interfaces that your JAX-RPC client can use to connect to the Web service. The xrpcc tool will use the WSDL file to generate the RMI interfaces.
To generate these files, the xrpcc tool reads a configuration XML file called config.xml. Depending on whether you start with the RMI interface or the WSDL document, the config.xml file will differ. Let's look at both of the syntaxes. Later on in the chapter, you will see an actual implementation of the config.xml file for the sample CarPartRequest Web service that you will create.
The config.xml File Syntax When Starting with RMI Interfaces
When starting with RMI interfaces, the config.xml file should have the following syntax:
<?xml version="1.0" encoding="UTF-8"?> <configuration xmlns="http://java.sun.com/jax-rpc-ri/xrpcc-config"> <service name="Name of the service" packageName="Package name that stores the web service classes" targetNamespace="Target namespace of the generated WSDL document" typeNameSpace="Target namespace for the schema portion of the generated WSDL document" <interface name="name of the service endpoint interface" servantName="Implementation class for the endpoint interface" soapAction="(Optional)String to be used as the SOAP action for all operations in the corresponding port" soapActionBase="(Optional) Prefix for SOAPAction string"> <handlerChains> </handlerChains> </interface> <typeMappingRegistry> User defined type mapping of Java to WSDL </typeMappingRegistry> <handlerChains> </handlerChains> <namespaceMappingRegistry> </namespaceMappingRegistry> </service> </configuration>
After the mandatory XML declaration and namespace definition line, the configuration file begins with the service element. This element defines the name of the Web service and the package name. The name parameter takes the service name. This information is used when generating the WSDL document for the Web service. The value of the name parameter is used as the name of the WSDL document. It is also used as the value of the name parameter of the definitions element of the WSDL document. The targetNamespace and typeNamespace parameters define where the generated WSDL file and its schema definition will be hosted. The interface element describes the interfaces exposed by the Web service and the implementation class of the interface.
The config.xml file can have only one service element. However, depending on the number of Web services and the interfaces exposed by each of the Web services, there can be multiple interface elements.
The typeMappingRegistry element provides the mechanism to define your own type mappings between XML schema types and Java types. This is an optional entry.
The config.xml File Syntax When Starting with a WSDL Document
When starting with a WSDL document, the config.xml file should have the following syntax:
<?xml version="1.0" encoding="UTF-8"?> <configuration xmlns="http://java.sun.com/jax-rpc-ri/xrpcc-config"> <wsdl location="URL to the WSDL document" packageName="Name of the package for the generated interfaces and implementation classes"> <typeMappingRegistry> WSDL to Java type mapping information </typeMappingRegistry> <handlerChains> </handlerChains> <namespaceMappingRegistry> </namespaceMappingRegistry> </wsdl> </configuration>
The wsdl element defines the URL address to the WSDL document, and the package name in which the generated stubs, ties, and RMI interfaces will be created when the xrpcc tool is run.
The optional element typeMappingRegistry enables you to define your own type mappings between XML schema data types and Java types.
The Types Supported by JAX-RPC
As you learned previously, the xrpcc tool automatically creates the mapping between the Java types and the XML data types used in the WSDL document. However, not all Java types are directly supported by the JAX-RPC mechanism. Therefore, you need to know the Java types that are supported by the JAX-RPC.
The JAX-RPC specification ensures support for a number of J2SE classes and primitive data types, user-defined classes, and Java beans. The specification also provides a mechanism to support the classes that are not directly supported by JAX-RPC. We'll examine each of them now in greater detail.
Java Types Support
The Java types supported by JAX-RPC are a combination of J2SE classes and primitive data types:
Arrays of these classes and primitive types
In addition to these J2SE classes and primitive data types, JAX-RPC also provides support for the application classes of your application. For example, you might have a Java application dealing with car parts inventory. In the application, you might have classes such as EngineSpecs, EngineOrder, and so on. You can use such classes while developing Web services; they're called value types in the JAX-RPC specification. However, for a Java class to be supported by the JAX-RPC specification, it must follow the following rules:
It must have a public default constructor.
It must not implement (directly or indirectly) the java.rmi.Remote interface. However, other than the java.rmi.Remote interface, it can implement any other interface or extend other Java classes.
It can contain public, private, protected, and package-level fields. However, for the value of a public field to be passed, it must be a supported JAX-RPC type as specified earlier, and should not be final or transient.
It may contain any type of methods.
It may contain static or transient fields.
If the Java class is a JavaBean component, it must have the getter and setter methods defined for each of the bean properties. Additionally, the bean properties must consist of the data types supported by JAX-RPC.