📄 index.xtp
字号:
<document> <header> <product>resin</product> <title>A JAX-WS Service for the Resin SOA</title> <description> <p>Resin simplifies deployment of JAX-WS applications by avoiding the need for complicated WSDLs and schema. </p> </description> <type>tutorial</type> <tutorial-startpage>demo.jsp</tutorial-startpage> </header> <body> <summary/> <s1><p>JAX-WS (Java API for XML Web Services) offers a powerful new approach towriting SOAP-based services. However because its design is so tightly coupledto WSDL (Web Service Definition Language), getting started writing a simpleservice has up until now been difficult and confusing. This tutorial showshow to write a simple, straightforward SOAP service starting with Java. Wewill also see how easy it is to deploy web services using Resin's easy tounderstand XML configuration.</p></s1><s1 title="Files in this tutorial"><deftable><tr><td><viewfile-link file="WEB-INF/classes/example/UserService.java"/> </td><td>The main service implementation.</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/User.java"/> </td><td>User class</td></tr><tr><td><viewfile-link file="WEB-INF/resin-web.xml"/> </td><td>Configures the environment</td></tr><tr><td><viewfile-link file="demo.jsp"/> </td><td>Client JSP</td></tr></deftable></s1><s1 title="What are JAX-WS, SOAP, and WSDL?"><p>SOAP is essentially an XML-based protocol for invoking remote methods. Forexample, if we have a method <code>int add(int a, int b)</code>, the SOAP request and response for this method might look like the following:</p><example title="SOAP request"><?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <m:add xmlns:m="http://example/"> <a>1</a> <b>2</b> </m:add> </soapenv:Body></soapenv:Envelope></example><example title="SOAP response"><?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <m:addResponse xmlns:m="http://example/"> <result>3</result> </m:addResponse> </soapenv:Body></soapenv:Envelope></example><p>WSDL is an XML-based language that describes the interface to SOAP serviceslike the one above. It is very flexible and allows for numerous styles ofSOAP invocations. Unfortunately, it can be very difficult to read. Forexample, the above exchange might have the following WSDL:</p><example title="Add service WSDL"><?xml version="1.0" standalone="yes"?><definitions targetNamespace="http://example/" name="AddService" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:m="http://example/"> <types> <xsd:schema version="1.0" targetNamespace="http://example/"> <xsd:element name="add" type="m:add"/> <xsd:complexType name="add"> <xsd:sequence> <xsd:element name="a" type="xsd:int"/> <xsd:element name="b" type="xsd:int"/> </xsd:sequence> </xsd:complexType> <xsd:element name="addResponse" type="m:addResponse"/> <xsd:complexType name="addResponse"/> <xsd:sequence> <xsd:element name="result" type="xsd:int"/> </xsd:sequence> </xsd:complexType> </xsd:schema> </types> <message name="add"> <part name="parameters" element="m:add"/> </message> <message name="addResponse"> <part name="parameters" element="m:addResponse"/> </message> <portType name="Add"> <operation name="add"> <input message="m:add"/> <output message="m:addResponse"/> </operation> </portType> <binding name="AddPortBinding" type="m:Add"> <soap:binding transport="http://schemas.xmlsoap.org/wsdl/soap/" style="document"/> <operation name="add"> <soap:operation soapAction=""/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> </binding> <service name="AddService"> <port name="AddPort" binding="m:AddPortBinding"> <soap:address location="http://example/add-service/"/> </port> </service></definitions></example><p>After looking at this WSDL, which is one of the simpler examples, you mightbegin to understand why WSDL has become mostly interpreted by programs and not people. If you are a client of another organization and plan to use theirSOAP services, you may have to use their WSDL to generate Java code for yourclient. However if you are designing your own service, especially for intra-organizational use only, there may be no need to use WSDL at all!</p><p>JAX-WS is a Java API and architecture for writing SOAP services and clients.Because WSDLs are necessary in some cases, JAX-WS has a lot of functionalitythat deals with reading and generating them. Unfortunately, if you're simplytrying to write your own simple service, dealing with WSDL can be veryconfusing and complicated. In the example below, we will show how to writea simple, but useful service that uses JAX-WS without ever touching a WSDL!</p></s1><s1 title="User Service Client"><p>Our service consists of one method, <code>getUsers()</code> that takes agroup id and returns all the users in that group. If the group doesn't exist,the service throws an exception.</p><p>First we will need an interface for our service. The interface isan actual Java interface. The service implementation will implement this interface and the client will obtain a proxy that exposes it.</p><example title="UserService.java">package example;import java.util.List;import javax.jws.WebMethod;import javax.jws.WebService;@WebServicepublic interface UserService { @WebMethod public List<User> getUsers(int groupId) throws InvalidGroupIdException;}</example><p>Notice the annotations @WebService and @WebMethod. These are not strictlynecessary, but help to show that this interface is for a SOAP web service. Other than those annotations, the interface is like any other Java interfacewith a method that takes arguments, returns a value, and even throws anexception. Within JAX-WS it will perform almost exactly like a local methodeven if it is really being invoked on a remote machine.</p><p>Next we'll look at the User class:</p><example title="User.java">package example;public class User { private String _name; private int _id; private int _groupId; // // JAXB requires a zero-argument constructor // public User() {} public User(int id, int groupId, String name) { _id = id; _groupId = groupId; _name = name; } public String getName() { return _name; } public void setName(String name) { _name = name; } public int getId() { return _id; } public void setId(int id) { _id = id; } public int getGroupId() { return _groupId; } public void setGroupId(int groupId) { _groupId = groupId; } public String toString() { return "User[id=" + _id + ", groupId=" + _groupId + ", name=" + _name + "]"; }}</example><p>This is a very simple class with three properties: a user id, a group id, anda user name. Because our service will return a list of these User objectsand we're actually using SOAP under the covers, JAX-WS will use another newJava technology: JAXB. JAXB is essentially a way to serialize and deserializeJava to and from XML. So this class needs to be JAXB compatible. In thiscase, fortunately all that means is that we need a zero-argument constructor.</p><p>The InvalidGroupIdException class is just a basic exception:</p><example title="InvalidGroupIdException.java">package example;public class InvalidGroupIdException extends Exception{ public InvalidGroupIdException() { super(); } public InvalidGroupIdException(String message) { super(message); }}</example><p>These three classes are all that the client needs to use the service. JAX-WShas a way to obtain a client programmatically. However, since we know that this client will be used frequently, we can create a client instance and register it in JNDI using Resin's <web-service-client> configuration tag:</p><example title="Client configuration"> <web-service-client jndi-name="soap/UserService"> <url>soap:${webApp.url}/user/</url> <interface>example.UserService</interface> </web-service-client></example></s1><s1 title="Service Implementation"><p>The implementation of this service is as simple as writing a class whichimplements UserService. In our simple example, we store user groups ina HashMap, but in a more complicated service, we might retrieve the usersfrom a database. The only unusual thing about the implementation is the@WebService annotation which indicates that the UserService interface isthe <em>endpointInterface</em> for this service. This simply means thatthe service will expose that interface as a SOAP service.</p><example title="UserServiceImpl.java">package example;import java.util.ArrayList;import java.util.HashMap;import java.util.List;import javax.jws.WebService;@WebService(endpointInterface="example.UserService")public class UserServiceImpl implements UserService { private final HashMap<Integer,List<User>> _userGroupMap = new HashMap<Integer,List<User>>(); public UserServiceImpl() { List<User> group1 = new ArrayList<User>(); group1.add(new User(1, 1, "Bruce")); group1.add(new User(2, 1, "Harvey")); List<User> group2 = new ArrayList<User>(); group2.add(new User(1, 2, "Lois")); group2.add(new User(2, 2, "Lex")); _userGroupMap.put(1, group1); _userGroupMap.put(2, group2); } public List<User> getUsers(int groupId) throws InvalidGroupIdException { List<User> users = _userGroupMap.get(groupId); if (users == null) throw new InvalidGroupIdException("Invalid group id"); return users; }}</example><p>Now for the deployment of this service. No WAR file is necessary, just asimple <servlet-mapping> tag in the resin-web.xml file:</p><example title="Service Configuration"> <servlet-mapping url-pattern="/user/*" jndi-name="service/UserService" servlet-class="example.UserServiceImpl"> <protocol type="soap"/> </servlet-mapping></example></s1><s1 title="JSP Client Script"><p>The client can now connect to the UserService by doing a lookup in JNDI.This allows simple access even using JSP:</p><example title="demo.jsp"><%@ page import="java.util.List" %><%@ page import="javax.naming.*" %><%@ page import="javax.xml.ws.Holder" %><%@ page import="example.UserService" %><%@ page import="example.User" %><%Context context = (Context) new InitialContext().lookup("java:comp/env");UserService service = (UserService) context.lookup("soap/UserService");List<User> users = service.getUsers(2);Exception invalid = null;try { service.getUsers(0);}catch (Exception e) { invalid = e;}%><pre>UserService.getUsers(1): <%= holder.value %>UserService.getUsers(0): <%= invalid %></pre></example><results>UserService.getUsers(1): [User[id=1, groupId=2, name=Lois], User[id=2, groupId=2, name=Lex]]UserService.getUsers(0): example.InvalidGroupIdException</results></s1> </body></document>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -