Endpoint.publish("http://127.0.0.1:9876/ts", new TimeServerImpl());
Endpoint endpoint = Endpoint.create(new TimeServerImpl());
endpoint.publish(url);
2 ways to create a client:
QName qname = new QName("http://ts.ch01/", "TimeServerImplService");
Service service = Service.create(url, qname);
TimeServer eif = service.getPort(TimeServer.class);
or if you have already generated the artifacts with wsimport
TeamsService service = new TeamsService();
Teams port = service.getTeamsPort();
Document VS RPC
Under the rpc style, the messages are named but not explicitly typed; under the
document style, the messages are explicitly typed in an XSD document.
WRAPPED vs UNWRAPPED
The body of the unwrapped SOAP request envelope has two elements, named num1 and num2. These are numbers to be added. The SOAP body does not contain the name of the service operation that is to perform the addition and send the sum as a response. By contrast, the body of a wrapped SOAP request envelope has a single element named addNums, the name of the requested service operation, and two subelements, each holding a number to be added. The wrapped version makes the service operation explicit. The arguments for the operation are nested in an intuitive manner; that is, as subelements within the operation element addNums.
Guidelines for the wrapped document convention are straightforward. Here is a summary of the guidelines:
The SOAP envelope's body should have only one part, that is, it should contain a single XML element with however many XML subelements are required. For example, even if a service operation expects arguments and returns a value, the parameters and return value do not occur as standalone XML elements in the SOAP body but, rather, as XML subelements within the main element. Example 2-9 illustrates with the addNums element as the single XML element in the SOAP body and the pair num1 and num2 as XML subelements.
The relationship between the WSDL's XSD and the single XML element in the SOAP body is well defined. The document-style version of the TimeServer can be used to illustrate. In the XSD, there are four XSD complexType elements, each of which defines a data type. For example, there is a complexType with the name getTimeAsString and another with the name getTimeAsStringResponse. These definitions occur in roughly the bottom half of the XSD. In the top half are XML element definitions, each of which has a name and a type attribute. The complexTypes also have names, which are coordinated with the element names. For example, the complexType named getTimeAsString is matched with an element of the same name. Here is a segment of the XSD that shows the name coordination:
<xs:element name="getTimeAsString"
type="tns:getTimeAsString">
</xs:element>
<xs:element name="getTimeAsStringResponse"
type="tns:getTimeAsStringResponse">
</xs:element>
...
<xs:complexType name="getTimeAsString"></xs:complexType>
<xs:complexType name="getTimeAsStringResponse">
<xs:sequence>
<xs:element name="return"
type="xs:string" minOccurs="0">
</xs:element>
</xs:sequence>
</xs:complexType>
Further, each complexType is either empty (for instance, getTimeAsString) or contains an xs:sequence (for instance, getTimeAsStringResponse, which has an xs:sequence of one XML element). The xs:sequence contains typed arguments and typed returned values. The TimeServer example is quite simple in that the requests contain no arguments and the responses contain just one return value. Nonetheless, this segment of XSD shows the structure for the general case. For instance, if the getTimeAsStringResponse had several return values, then each would occur as an XML subelement within the xs:sequence. Finally, note that every XML element in this XSD segment (and, indeed, in the full XSD) is named and typed.
The XML elements in the XSD serve as the wrappers for the SOAP message body. For the ch01.ts.TimeServer, a sample wrapped document is:
<?xml version="1.0" ?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.or g/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soapenv:Body>
<ans:getTimeAsElapsedResponse xmlns:ans="http://ts.ch01/">
<return>1205030105192</return>
</ans:getTimeAsElapsedResponse>
</soapenv:Body>
</soapenv:Envelope>
This is the same kind of SOAP body generated for an rpc-style service, which is precisely the point. The difference, again, is that the wrapped document-style service, unlike its rpc-style counterpart, includes explicit type and format information in an XSD from the WSDL's types section.
The request wrapper has the same name as the service operation (for instance, addNums in Example 2-9), and the response wrapper should be the request wrapper's name with Response appended (for instance, addNumsResponse).
The WSDL portType section now has named operations (e.g., getTimeAsString) whose messages are typed. For instance, the input (request) message getTimeAsString has the type tns:getTimeAsString, which is defined as one of the four complexTypes in the WSDL's XSD. For the document-style version of the service, here is the portType segment:
<portType name="TimeServer">
<operation name="getTimeAsString">
<input message="tns:getTimeAsString"></input>
<output message="tns:getTimeAsStringResponse"></output>
</operation>
<operation name="getTimeAsElapsed">
<input message="tns:getTimeAsElapsed"></input>
<output message="tns:getTimeAsElapsedResponse"></output>
</operation>
</portType>
The wrapped document convention, despite its unofficial status, has become prevalent. JWS supports the convention. By default, a Java SOAP-based web service is wrapped doc/lit, that is, wrapped document style with literal encoding.
JAXB
JAX-B supports conversions between Java and XML types.
The @XmlType and @XmlRootElement annotations direct the marshaling of Skier objects, where marshaling is the process of encoding an in-memory object (for example, a Skier) as an XML document so that, for instance, the encoding can be sent across a network to be unmarshaled or decoded at the other end. In common usage, the distinction between marshal and unmarshal is very close and perhaps identical to the serialize/deserialize distinction. I use the distinctions interchangeably. JAX-B supports the marshaling of in-memory Java objects to XML documents and the unmarshaling of XML documents to in-memory Java objects.
The annotation @XmlType, applied in this example to the Person class, indicates that JAX-B should generate an XML Schema type from the Java type. The annotation @XmlRootElement, applied in this example to the Skier class, indicates that JAX-B should generate an XML document (outermost or root) element from the Java class. Accordingly, the resulting XML in this example is a document whose outermost element represents a skier; and the document has a nested element that represents a person.
Marshaling
JAXBContext ctx = JAXBContext.newInstance(Skier.class);
Marshaller m = ctx.createMarshaller();
m.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
// Marshal a Skier object: 1st to stdout, 2nd to file
Skier skier = createSkier();
m.marshal(skier, System.out);
Unmarshaling
Unmarshaller u = ctx.createUnmarshaller();
Skier bd_clone = (Skier) u.unmarshal(new File(file_name));
@XmlRootElement(name = "getTimeAsElapsedResponse", namespace = "http://ts.ch02/")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "getTimeAsElapsedResponse", namespace = "http://ts.ch02/")
public class GetTimeAsElapsedResponse {
@XmlElement(name = "return", namespace = "")
private long _return;
public long get_return() { return this._return; }
public void set_return(long _return) { this._return = _return; }
}
The annotation in bold indicates that the field named _return will be marshaled and unmarshaled rather than a property defined with a get/set method pair that follows the usual JavaBean naming conventions.
Other annotation attributes can be set to override the default naming conventions. For example, if the annotation in the Skier class declaration is changed to:
@XmlRootElement(name = "NordicSkier")
then the resulting XML document begins:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<NordicSkier>
No comments:
Post a Comment