计算机科学论坛--用JAX-RPC开发Web Services

姓名：(无权查看)
城市：(无权查看)
院校：(无权查看)

A Simple Example: HelloWorld
This example shows you how to use JAX-RPC to create a Web service named HelloWorld. A remote client of the HelloWorld service can invoke the sayHello method, which accepts a string parameter and then returns a string.
HelloWorld at Runtime
Figure 10-1 shows a simplified view of the HelloWorld service after it's been deployed. Here's a more detailed description of what happens at runtime:
To call a remote procedure, the HelloClient program invokes a method on a stub, a local object that represents the remote service.
The stub invokes routines in the JAX-RPC runtime system.
The runtime system converts the remote method call into a SOAP message and then transmits the message as an HTTP request.
When the server receives the HTTP request, the JAX-RPC runtime system extracts the SOAP message from the request and translates it into a method call.
The JAX-RPC runtime system invokes the method on the tie object.
The tie object invokes the method on the implementation of the HelloWorld service.
The runtime system on the server converts the method's response into a SOAP message and then transmits the message back to the client as an HTTP response.
On the client, the JAX-RPC runtime system extracts the SOAP message from the HTTP response and then translates it into a method response for the HelloClient program.

Figure 10-1 The HelloWorld Example at Runtime
The application developer only provides the top layers in the stacks depicted by Figure 10-1. Table 10-1 shows where the layers originate.
Table 10-1 Who (or What) Provides the Layers
Layer Source
HelloClient Program
HelloWorld Service (definition interface and implementation class) Provided by the application developer
Stubs
Ties Generated by the xrpcc tool, which is run by the application developer
JAX-RPC Runtime
System Included with the Java WSDP
HelloWorld Files
To create a service with JAX-RPC, an application developer needs to provide just a few files. For the HelloWorld example, these files are in the <JWSDP_HOME>/docs/tutorial/examples/jaxrpc/hello directory:
HelloIF.java - the service definition interface
HelloImpl.java - the service definition implementation class, it implements the HelloIF interface
config.xml - a configuration file read by the xrpcc tool, which creates the stub and tie classes
web.xml - a deployment descriptor for the Web component (a servlet) that dispatches to the service
HelloClient.java - the remote client that contacts the service and then invokes the sayHello method
Setting Up
If you haven't already done so, follow these instructions in the chapter Getting Started With Tomcat:
Setting the PATH Variable
Creating the Build Properties File
Starting Tomcat
Building and Installing the Service
The basic steps for developing a JAX-RPC Web service are as follows.
Code the service definition interface and implementation class.
Compile the service definition code of step 1.
Create the configuration file.
Generate the ties.
Create the deployment descriptor.
Install the service on Tomcat.
The sections that follow describe each of these steps in more detail.

姓名：(无权查看)
城市：(无权查看)
院校：(无权查看)

Coding the Service Definition Interface and Implementation Class
编写服务定义接口和执行类
A service definition interface declares the methods that a remote client may invoke on the service. The interface must conform to a few rules:
一个服务定义接口，接口里的方法远程客户可以从服务器调用。接口必须符合以下规定。
It extends the java.rmi.Remote interface.
继承java.rmi.Remote接口。
It must not have constant declarations, such as public final static.
不包含任何静态常量声明，如public final static。
The methods must throw the java.rmi.RemoteException or one of its subclasses. (The methods may also throw service-specific exceptions.)
方法必须抛出java.rmi.RemoteException或它的一个子类。（方法也可以抛出指定的服务异常。）
Method parameters and return types must be supported JAX-RPC types.
方法的参数和返回值必须支持JAX-RPC类型。
In this example, the service definition interface is HelloIF.java:
在这个例子，服务定义接口是HelloIF.java。
package hello;

import java.rmi.Remote;
import java.rmi.RemoteException;

public interface HelloIF extends Remote {
public String sayHello(String s) throws RemoteException;
}

In addition to the interface, you'll need to code the class that implements the interface. In this example, the implementation class is called HelloImpl:
除了接口，你要编写接口的执行类。这个例子执行类叫HelloImpl。
package hello;

public class HelloImpl implements HelloIF {

public String message ="Hello";

    public String sayHello(String s) {
        return message + s;
    }
}

Compiling the Service Definition Code
编写服务定义程序。
To compile HelloIF.java and HelloImpl.java, go to the <JWSDP_HOME>/docs
/tutorial/examples/jaxrpc/hello directory and type the following:
打入：
ant compile-server

This command places the resulting class files in the build/shared subdirectory.
这个命令将结果类文件放到build/shared子目录。
Creating the Configuration File
创建配置文件
The config.xml file contains information needed by the xrpcc tool, which you'll run in the next section.
Config.xml文件包括的信息需要xrpcc工具，你可在下一章运行。
In the file listing that follows, note the values defined in the <service> element.
文件如下：值被定义在<service>元素。
The name of the service is HelloWorld. The packageName attribute, hello, is the name of the package of the classes generated by xrpcc.
服务名叫HelloWorld.包名hello。Xrpcc产生类的包名。
In the <interface> subelement, the name attribute corresponds to the fully qualified name of the service definition interface, hello.HelloIF.
子元素<interface>的name属性为服务定义接口的全名：hello.HelloIF。
The servantName attribute is the name of the interface's implementation class, hello.HelloImpl.
服务名属性是接口执行类：hello.HelloImpl。
Here is the config.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<configuration xmlns="http://java.sun.com/xml/ns/jax-
rpc/ri/config">
    <service name="HelloWorld"
        targetNamespace="http://hello.org/wsdl"
        typeNamespace="http://hello.org/types"
        packageName="hello">                             包名
        <interface name="hello.HelloIF"                接口名
            servantName="hello.HelloImpl"/>             服务名
     </service>
</configuration>

________________________________________
Note: Although required for the implementation of JAX-RPC in the Java WSDP, the configuration file and xrpcc tool are not defined in the specifications. Their syntax and usage may change in future releases.
虽然JWSDP执行需要JAX-RPC，但配置文件和xrpcc工具并没有被特别指定。它们的语法和使用方法会在将来的版本有所改变。
________________________________________
Generating the Ties
Ties are lower-level classes on the server that enable it to communicate with the client. (On the client, the corresponding classes are called stubs.)
Ties是服务器的低级类可以和客户通信。（在客户端，通讯类叫stubs。）
To generate the ties, you run the xrpcc tool. The tool also creates a properties file and a WSDL file.
要运行xrpcc工具产生ties。Xrpcc也可以创建一个属性设置文件和一个WSDL文件。
Used internally by JAX-RPC in this release, the properties file is not defined in the specifications.
用这个版本的JAX-RPC，文件属性没有被特别规定。
For information about the relationship between JAX-RPC technology and WSDL files, please refer to the JAX-RPC Specification.
要获得JAX-RPC和WSDL关系的信息，请参考JAX-RPC规格。
In this example, the xrpcc tool reads the service definition interface and the configuration file. (Alternatively, the tool may read a WSDL file instead of the interface.
这个例子，xrpcc工具读服务接口定义和配置文件。（xrpcc可能会读WSDL文件，而不是接口。）
The xrpcc tool is a script: xrpcc.sh for UNIX or xprcc.bat for Windows. To create the ties, go to the <JWSDP_HOME>/docs/tutorial/examples/jaxrpc/hello directory and run the tool as follows. (Type the command on a single line.)
Xrpcc是一个脚本：UNIX用xprcc.sh,WINDOWS用xprcc.bat。要创建ties到hello目录，运行下面工具。（每行打印命令。）
UNIX:
xrpcc.sh -classpath build/shared -server -d build/server
config.xml

Windows:
xrpcc.bat -classpath build\shared -server -d build\server
config.xml

The -classpath option refers to the directory into which the server files were compiled.
¬-classpath选项将目录放入被编辑的服务文件。
The -d option denotes the destination directory for the generated files.
-d选项指出被生成文件的目的目录。
As a shortcut, instead of running the xrpcc command as shown previously, you can simply type the following:
如果不运行上面xrpcc命令，你可以打下面：
ant xrpcc-server

姓名：(无权查看)
城市：(无权查看)
院校：(无权查看)

Creating the Deployment Descriptor
创建动态描述符
A deployment descriptor is an XML file that provides configuration information for the Web server about the Web components (JSP pages or servlets) that are in a Web application.
部署描述符是一个XML文件，为Web服务提供配置信息，如Web应用程序里Web组成是JSP还是servlets.
Because the HelloWorld service is deployed as a servlet, the deployment descriptor has some elements that are related to the service.
因为HelloWorld服务被部署为servlet,部署描述符有一些元素和服务有关。
This section describes only those elements; for more information about deployment descriptors, see the Java Servlet Specification.
这章只说元素，关于部署描述符信息看Java Servlet 规定。
Let's take a quick look at a couple of the elements in the deployment descriptor (web.xml).
让我们快速看一下部署描述符（web.xml）的成队元素。
First, note the HelloWorld_Config.properties value of the <init-param> element. 属性设置的名字是服务名。
首先，说HelloWorld_Config.properties的<init-param>元素的值。
This properties file was generated by the xrpcc tool. The name of the file is the HelloWorld service name (which was defined in the configuration file) appended by the _Config.properties string.
这个属性设置文章由xrpcc工具产生。这个文件的名字是HelloWorld服务的名字（已定义在配置文件）后面家_Config.properties字符串。
The value of the <url-pattern> element, /jaxrpc/*, is part of the URL that designates the service's endpoint.
<url-pattern>元素的值指定服务终端URL的一部分。
This URL is passed to the HelloClient program as a command-line parameter.
URL作为命令行参数被传到HelloClient程序。
The web.xml deployment descriptor follows:
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE web-app PUBLIC
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">

<web-app>
   <display-name>HelloWorldApplication</display-name>
   <description>Hello World Application</description>
   <servlet>
      <servlet-name>JAXRPCEndpoint</servlet-name>
      <display-name>JAXRPCEndpoint</display-name>
      <description>
         Endpoint for Hello World Application
      </description>
      <servlet-class>
        com.sun.xml.rpc.server.http.JAXRPCServlet
      </servlet-class>
      <init-param>
         <param-name>configuration.file</param-name>
         <param-value>
          /WEB-INF/HelloWorld_Config.properties
        </param-value>
      </init-param>
      <load-on-startup>0</load-on-startup>
   </servlet>
   <servlet-mapping>
      <servlet-name>JAXRPCEndpoint</servlet-name>
      <url-pattern>/jaxrpc/*</url-pattern>
   </servlet-mapping>
   <session-config>
      <session-timeout>60</session-timeout>
   </session-config>
</web-app>

Installing the Service
安装服务
The HelloWorld service is implemented as a Web application that runs on Tomcat. To install the Web application, go to the <JWSDP_HOME>/docs/tutorial/examples
/jaxrpc/hello directory and type the following commands:
ant setup-web-inf
ant install
HelloWorld 服务作为Web应用程序被执行，运行在Tomcat上。安装Web应用程序去hello目录，打入下面命令：
The setup-web-inf target copies the class files and the deployment descriptor (web.xml) to the build/WEB-INF subdirectory.
setup-web-inf目的是复制类文件，部署描述符（web.xml）去构建/WEB-INF子目录。
The contents of the build/WEB-INF subdirectory match the contents of the WAR file. /WEB-INF子目录的内容和WEB 文件的内容相对应。
To list all installed Web applications, type the following:
列出所有已安装的Web 应用程序，打入：
ant list

Verifying the Installation
检查安装
To verify that the HelloWorld service has been installed, open a browser window and specify this URL:
检查HelloWorld服务是否已被安装，打开浏览器，URL为：
http://localhost:8080/jaxrpc-hello/jaxrpc

The browser should display these lines:
浏览器显示：
A Web Service is installed at this URL.
Web服务已被安装在该URL。

It supports the following ports: "HelloIF"
(http://localhost:8080/jaxrpc-hello/jaxrpc/HelloIF)
Web服务支持下面的端口：
You can use this approach to verify the deployment of any service that is created with the JAX-RPC implementation of the Java WSDP. You would specify the following URL:
http://localhost:8080/jaxrpc-dynamic/jaxrpc
你可以使用这个方法检查任何服务的部署，这些服务有JAX-RPC执行JWSDP创建。
Removing the Service
删除服务
At this point in the tutorial, do not remove the service. When you are finished with this example, you can remove the HelloWorld service by typing this command:
打入下面命令删除服务：
ant remove

Building and Running the Client
构建和运行客户端
To develop a JAX-RPC client, you follow these steps:
Generate the stubs.
Code the client.
Compile the client code.
Package the client classes into a JAR file.
Run the client.
开发JAX-RPC要遵循下列步骤：
产生stubs
编写client
编辑client程序
Client类打包成JAR文件。
运行client。
The following sections describe each of these steps.
Generating the Stubs
产生stubs
In addition to generating the ties for the server, the xrpcc tool also generates the stubs for the client. To create the stubs, go to the <JWSDP_HOME>/docs/tutorial/examples
/jaxrpc/hello directory and run the tool as follows. (Type the command on a single line.)
Xrpcc工具除了为服务器产生ties还为客户端产生stubs。创建stubs，到hello目录，运行下面工具：
UNIX:
xrpcc.sh -classpath build/shared -client -d build/client
config.xml
Windows:
xrpcc.bat -classpath build\shared -client -d build\client
config.xml

The -classpath option refers to the directory containing the class files that you created in Compiling the Service Definition Code. The -d option denotes the destination directory for the generated files. See the section Syntax for the full syntax of the xrpcc tool.
As a shortcut, instead of running the xrpcc command as shown previously, you can simply type the following:
如果不用xrpcc命令，你可以打入：
ant xrpcc-client

Coding the Client
编写客户端程序：
HelloClient is a stand-alone program that calls the sayHello method of the HelloWorld service. It makes this call through a stub, a local object which acts as a proxy for the remote service.
HelloClient 是一个独立的程序，调用HelloWorld服务的sayHello方法。HelloClient通过stub调用HelloWorld服务的sayHello方法，一个当地对象作为远程服务器的代理。
At runtime, HelloClient accepts as input a single command-line parameter, a URI that denotes the address of the target service port. This URI is often called the endpoint of the service.
在运行时，HelloClient接收输入的命令行参数，URL指定目标服务端地址。这个URL常调用服务端。
To direct the stub to the correct endpoint, the program invokes the _setProperty method. Next, it casts the stub to the type HelloIF, the service definition interface. Finally, the program invokes the sayHello method on the stub.
为了将stub指向正确的终端，程序调用_setProperty方法。接着，让stub调用HelloIF，HelloIF定义了接口。最后程序stub调用sayHello方法。
To create the stub, HelloClient invokes a private method named createProxy. Note that the code in this method is implementation-specific and might not be portable because of the HelloWorld_Impl object.
创建stub，HelloClient调用名为creatProxy（创建代理主机）的私有方法。creatProxy方法程序是具体执行，可能不适合HelloWorld_Impl对象。
The source code for HelloClient follows:
package hello;

import javax.xml.rpc.Stub;

public class HelloClient {
    public static void main(String[] args) {
        try {
            Stub stub = createProxy();
            stub._setProperty(
                javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY,
                args[0]);
            HelloIF hello = (HelloIF)stub;
            System.out.println(hello.sayHello("Duke!"));
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }

    private static Stub createProxy() {
        // Note: HelloWorld_Impl is implementation-specific.
        return (Stub)(new HelloWorld_Impl().getHelloIFPort());
    }
}

姓名：(无权查看)
城市：(无权查看)
院校：(无权查看)

Compiling the Client Code
编辑Client程序
Because the client code refers to classes generated by the xrpcc tool, be sure to run the tool before compiling the client. To compile the client, go to the <JWSDP_HOME>
/docs/tutorial/examples/jaxrpc/hello directory and type the following:
由于client程序涉及的类有xrpcc工具产生，请确定编辑client前运行xrpcc工具。打入：
ant compile-client

Packaging the Client
将Client打包
To package the client into a JAR file, go to the<JWSDP_HOME>/docs/tutorial
/examples/jaxrpc/hello directory and type the following command:
将client打包为JAR文件，打：
ant jar-client

This command creates the dist/hello-client.jar file.
这个命令创建hello-client.jar文件。
Running the Client
运行Client
To run the HelloClient program, go to the <JWSDP_HOME>/docs/tutorial/examples
/jaxrpc/hello directory and type the following:
运行HelloClient程序，打：
ant run

The program should display this line:
程序显示：
Hello Duke!

The ant run target executes this command:
Ant运行执行下面命令：
java -classpath <cpath> hello.HelloClient <endpoint>

The classpath includes the hello-client.jar file that you created in the preceding section, as well as several JAR files that belong to the Java WSDP. In order to run the client remotely, all of these JAR files must reside on the remote client's computer.
路径包括你在前面创建的hello-client.jar文件，和一些属于JWSDP的JAR文件。
The command-line parameter for the HelloClient program is the service endpoint:
http://localhost:8080/jaxrpc-hello/jaxrpc/HelloIF
HelloClient程序命令行参数是服务终端。
The jaxrpc-hello portion of the URL is the context of the servlet that implements the HelloWorld service. This portion corresponds to the prefix of the jaxrpc-hello.war file. The jaxrpc string matches the value of the <url-pattern> element of the web.xml deployment descriptor. And finally, HelloIF is the name of the interface that defines the service.
URL的jaxrpc-hello部分是servlet的上下文执行HelloWorld服务。这个部分和jaxrpc-hello.war文件前缀一致。Jaxrpc字符串和web.xml部署描述文件的<url-pattern>元素值一致。最后HelloIF是定义服务的接口的名子。
Iterative Development
迭代开发
In order to show you each step of development, the previous sections instructed you to type several Ant commands. However, it would be inconvenient to type all of those commands during iterative development.
为了显示开发的没一步，前面章节介绍你打入一些ant命令。然而，在迭代开发里打如这些命令可能不方便。
To save time, after you've installed the application (with ant install), you can iterate through these steps:
为了节省时间，你用ant安装应用程序，你可迭代下面的步骤：
Test the application.   测试应用程序。
Edit the source files.     编辑源程序。
Execute ant build.           执行ant build。
Execute ant reload.    执行ant reload。
Execute ant run.       执行ant run。
The build target compiles the code, runs the xrpcc tool, and packages the client JAR file. The reload target updates the Web application on Tomcat with your latest changes.
Build目的是编辑程序，运行xrpcc工具，打包client JAR文件。Reload目的是在Tomcat上更新刚改变的Web应用程序。


	W 3 C h i n a ( since 2003 ) 旗下站点苏ICP备05006046号《全国人大常委会关于维护互联网安全的决定》《计算机信息网络国际联网安全保护管理办法》	109.375ms