|
151
|
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
2
|
|
|
3
|
|
|
4
|
|
|
5
|
|
|
6
|
|
|
7
|
|
|
8
|
|
|
9
|
|
|
10
|
|
|
11
|
|
|
12
|
|
|
13 <html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
14 <head>
|
|
|
15 <title>ws-xmlrpc - Advanced Programming Topics</title>
|
|
|
16 <style type="text/css" media="all">
|
|
|
17 @import url("./css/maven-base.css");
|
|
|
18 @import url("./css/maven-theme.css");
|
|
|
19 @import url("./css/site.css");
|
|
|
20 </style>
|
|
|
21 <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
|
|
|
22 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
|
|
|
23 </head>
|
|
|
24 <body class="composite">
|
|
|
25 <div id="banner">
|
|
|
26 <a href="" id="bannerLeft">
|
|
|
27
|
|
|
28 <img src="images/xmlrpc-logo.gif" alt="" />
|
|
|
29
|
|
|
30 </a>
|
|
|
31 <div class="clear">
|
|
|
32 <hr/>
|
|
|
33 </div>
|
|
|
34 </div>
|
|
|
35 <div id="breadcrumbs">
|
|
|
36
|
|
|
37
|
|
|
38
|
|
|
39
|
|
|
40
|
|
|
41
|
|
|
42
|
|
|
43
|
|
|
44 <div class="xleft">
|
|
|
45 Last Published: 2010-02-06
|
|
|
46 </div>
|
|
|
47 <div class="xright"> <a href="http://www.apache.org/" class="externalLink">Apache</a>
|
|
|
48 |
|
|
|
49 <a href="../">Webservices</a>
|
|
|
50 |
|
|
|
51 <a href="">XML-RPC</a>
|
|
|
52
|
|
|
53
|
|
|
54
|
|
|
55
|
|
|
56
|
|
|
57
|
|
|
58
|
|
|
59
|
|
|
60 </div>
|
|
|
61 <div class="clear">
|
|
|
62 <hr/>
|
|
|
63 </div>
|
|
|
64 </div>
|
|
|
65 <div id="leftColumn">
|
|
|
66 <div id="navcolumn">
|
|
|
67
|
|
|
68
|
|
|
69
|
|
|
70
|
|
|
71
|
|
|
72
|
|
|
73
|
|
|
74
|
|
|
75 <h5>XML-RPC</h5>
|
|
|
76 <ul>
|
|
|
77
|
|
|
78 <li class="none">
|
|
|
79 <a href="index.html">Overview</a>
|
|
|
80 </li>
|
|
|
81
|
|
|
82 <li class="none">
|
|
|
83 <a href="download.html">Download</a>
|
|
|
84 </li>
|
|
|
85
|
|
|
86 <li class="none">
|
|
|
87 <a href="changes-report.html">Changes</a>
|
|
|
88 </li>
|
|
|
89
|
|
|
90 <li class="none">
|
|
|
91 <a href="mail-lists.html">Mailing Lists</a>
|
|
|
92 </li>
|
|
|
93
|
|
|
94 <li class="none">
|
|
|
95 <a href="contributing.html">Contributing</a>
|
|
|
96 </li>
|
|
|
97
|
|
|
98 <li class="none">
|
|
|
99 <a href="xmlrpc2">XML-RPC 2</a>
|
|
|
100 </li>
|
|
|
101
|
|
|
102 <li class="none">
|
|
|
103 <a href="links.html">Links</a>
|
|
|
104 </li>
|
|
|
105 </ul>
|
|
|
106 <h5>Documentation</h5>
|
|
|
107 <ul>
|
|
|
108
|
|
|
109 <li class="none">
|
|
|
110 <a href="client.html">Client Classes</a>
|
|
|
111 </li>
|
|
|
112
|
|
|
113 <li class="none">
|
|
|
114 <a href="server.html">Server Side XML-RPC</a>
|
|
|
115 </li>
|
|
|
116
|
|
|
117 <li class="none">
|
|
|
118 <a href="extensions.html">Vendor Extensions</a>
|
|
|
119 </li>
|
|
|
120
|
|
|
121 <li class="none">
|
|
|
122 <a href="ssl.html">SSL</a>
|
|
|
123 </li>
|
|
|
124
|
|
|
125 <li class="none">
|
|
|
126 <a href="introspection.html">Introspection</a>
|
|
|
127 </li>
|
|
|
128
|
|
|
129 <li class="none">
|
|
|
130 <strong>Advanced Techniques</strong>
|
|
|
131 </li>
|
|
|
132
|
|
|
133 <li class="none">
|
|
|
134 <a href="types.html">XML-RPC Types</a>
|
|
|
135 </li>
|
|
|
136
|
|
|
137 <li class="none">
|
|
|
138 <a href="faq.html">FAQ</a>
|
|
|
139 </li>
|
|
|
140
|
|
|
141 <li class="none">
|
|
|
142 <a href="apidocs/index.html">Javadocs</a>
|
|
|
143 </li>
|
|
|
144 </ul>
|
|
|
145 <h5>Project Documentation</h5>
|
|
|
146 <ul>
|
|
|
147
|
|
|
148
|
|
|
149
|
|
|
150
|
|
|
151
|
|
|
152
|
|
|
153
|
|
|
154
|
|
|
155
|
|
|
156
|
|
|
157
|
|
|
158
|
|
|
159
|
|
|
160
|
|
|
161
|
|
|
162
|
|
|
163
|
|
|
164
|
|
|
165
|
|
|
166
|
|
|
167
|
|
|
168
|
|
|
169
|
|
|
170
|
|
|
171
|
|
|
172
|
|
|
173
|
|
|
174 <li class="collapsed">
|
|
|
175 <a href="project-info.html">Project Information</a>
|
|
|
176 </li>
|
|
|
177
|
|
|
178
|
|
|
179
|
|
|
180
|
|
|
181
|
|
|
182
|
|
|
183
|
|
|
184
|
|
|
185
|
|
|
186 <li class="collapsed">
|
|
|
187 <a href="project-reports.html">Project Reports</a>
|
|
|
188 </li>
|
|
|
189 </ul>
|
|
|
190 <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
|
|
|
191 <img alt="Built by Maven" src="./images/logos/maven-feather.png"></img>
|
|
|
192 </a>
|
|
|
193
|
|
|
194
|
|
|
195
|
|
|
196
|
|
|
197
|
|
|
198
|
|
|
199
|
|
|
200
|
|
|
201 </div>
|
|
|
202 </div>
|
|
|
203 <div id="bodyColumn">
|
|
|
204 <div id="contentBox">
|
|
|
205 <p>This page describes some advanced topics.</p>
|
|
|
206 <div class="section"><h2>Dynamic proxies</h2>
|
|
|
207 <p>Dynamic proxies are an extremely comfortable way of Client programming. Basically, the idea is as follows: All request processors on the server side are splitted into interface and implementation. The interfaces are shared between client and server, typically within some common jar file. Now, rather than using the <a href="apidocs/org/apache/xmlrpc/client/XmlRpcClient.html">XmlRpcClient</a> directly, the programmer creates an instance of <a href="apidocs/org/apache/xmlrpc/client/util/ClientFactory.html">ClientFactory</a>, which is configured with an <a href="apidocs/org/apache/xmlrpc/client/XmlRpcClient.html">XmlRpcClient</a>.</p>
|
|
|
208 <p>The <a href="apidocs/org/apache/xmlrpc/client/util/ClientFactory.html">factory</a> can take an interface as input and returns an implementation, which internally calls the server by using the <a href="apidocs/org/apache/xmlrpc/client/XmlRpcClient.html">XmlRpcClient</a>.</p>
|
|
|
209 <p>Perhaps some code shows more than words. First of all, let's create a request processor interface.</p>
|
|
|
210 <div class="source"><pre> package com.foo;
|
|
|
211
|
|
|
212 public interface Adder {
|
|
|
213 public int add(int pNum1, int pNum2);
|
|
|
214 }
</pre>
|
|
|
215 </div>
|
|
|
216 <p>The server contains the request processors implementation:</p>
|
|
|
217 <div class="source"><pre> package com.foo;
|
|
|
218
|
|
|
219 public class AdderImpl implements Adder {
|
|
|
220 public int add(int pNum1, int pNum2) {
|
|
|
221 return pNum1 + pNum2;
|
|
|
222 }
|
|
|
223 }
</pre>
|
|
|
224 </div>
|
|
|
225 <p>And here is how the client would use this:</p>
|
|
|
226 <div class="source"><pre> import com.foo.Adder;
|
|
|
227 import java.net.URL;
|
|
|
228 import org.apache.xmlrpc.client.XmlRpcClient;
|
|
|
229 import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;
|
|
|
230 import org.apache.xmlrpc.client.util.ClientFactory;
|
|
|
231
|
|
|
232 XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
|
|
|
233 config.setServerURL(new URL("http://127.0.0.1:8080/xmlrpc"));
|
|
|
234 XmlRpcClient client = new XmlRpcClient();
|
|
|
235 client.setConfig(config);
|
|
|
236 ClientFactory factory = new ClientFactory(client);
|
|
|
237 Adder adder = (Adder) factory.newInstance(Adder.class);
|
|
|
238 int sum = adder.add(2, 4);
</pre>
|
|
|
239 </div>
|
|
|
240 <div class="section"><h3>Exception handling</h3>
|
|
|
241 <p>Currently, exceptions are a problem: If the server throws an exception (for example an IOException), then the client receives an XmlRpcException. Consequently, the generated implementation will attempt to throw the XmlRpcException.</p>
|
|
|
242 <p>Unfortunately, the method signature will of course contain an IOException, but rarely an XmlRpcException. As the XmlRpcException cannot be thrown, it is converted into an UndeclaredThrowableException.</p>
|
|
|
243 <p>This is no problem, if you are prepared for runtime exceptions by enclosing your code with proper exception handlers. (Of course, the exception handlers may be in a calling method.) Only if you want to catch the exception (for example, because you expect an error at a certain point), then you need to consider, which exception is being trapped: If the method exposes XmlRpcException, then you'll need to catch the XmlRpcException. Otherwise, it's UndeclaredThrowableException.</p>
|
|
|
244 <p>It is recommended to use the property enabledForExceptions. If this property is set, then the server will attempt to convert the exception into a byte array, which is transmitted to the client. The client will be able to convert the byte array back into an exception and throw that, as if it came right out of the client. Note, that this approach may cause security and privacy issues, because the serialized exception may, in theory, contain arbitrary objects.</p>
|
|
|
245 </div>
|
|
|
246 <div class="section"><h3>Cookie handling</h3>
|
|
|
247 <p>Cookie has not yet been generalized. In other words, it depends on the transport.</p>
|
|
|
248 <ul><li>The XmlRpcLiteHttpTransport doesn't have support for cookies. * The XmlRpcSunHttpTransport requires hand written code for setting and getting the cookies or using a cookie library. (The latter is recommended, of course.) In either way, you've got to use a custom transport and overwrite the methods newURLConnection(URL), initHttpHeaders(XmlRpcRequest), and close():<div class="source"><pre> import java.net.URLConnection;
|
|
|
249 import org.apache.xmlrpc.client.XmlRpcClient;
|
|
|
250 import org.apache.xmlrpc.client.XmlRpcSunHttpTransport;
|
|
|
251 import org.apache.xmlrpc.client.XmlRpcTransport;
|
|
|
252 import org.apache.xmlrpc.client.XmlRpcTransportFactory;
|
|
|
253
|
|
|
254 final XmlRpcClient client = new XmlRpcClient();
|
|
|
255 XmlRpcTransportFactory factory = new XmlRpcTransportFactory(){
|
|
|
256 public XmlRpcTransport getTransport(){
|
|
|
257 private URLConnection conn;
|
|
|
258 protected URLConnection newURLConnection(URL pURL) throws IOException {
|
|
|
259 conn = super.newURLConnection(pURL);
|
|
|
260 return conn;
|
|
|
261 }
|
|
|
262 protected void initHttpHeaders(XmlRpcRequest pRequest) {
|
|
|
263 super.initHttpHeaders(pRequest);
|
|
|
264 setCookies(conn);
|
|
|
265 }
|
|
|
266 protected void close() throws XmlRpcClientException {
|
|
|
267 getCookies(conn);
|
|
|
268 }
|
|
|
269 private void setCookies(URLConnection pConn) {
|
|
|
270 // Implement me ...
|
|
|
271 }
|
|
|
272 private void getCookies(URLConnection pConn) {
|
|
|
273 // Implement me ...
|
|
|
274 }
|
|
|
275 }
|
|
|
276 };
|
|
|
277 client.setTransportFactory(factory);
</pre>
|
|
|
278 </div>
|
|
|
279 </li>
|
|
|
280 <li>The XmlRpcCommonsHttpTransport requires that the HttpClient is being reused. (By default, a new HttpClient is created for any connection.) To reuse the HttpClient, set it on the transport factory:<div class="source"><pre> import org.apache.commons.httpclient.HttpClient;
|
|
|
281 import org.apache.commons.httpclient.HttpState;
|
|
|
282 import org.apache.xmlrpc.client.XmlRpcClient;
|
|
|
283 import org.apache.xmlrpc.client.XmlRpcCommonsTransport;
|
|
|
284 import org.apache.xmlrpc.client.XmlRpcCommonsTransportFactory;
|
|
|
285
|
|
|
286 final XmlRpcClient client = new XmlRpcClient();
|
|
|
287 final HttpClient httpClient = new HttpClient();
|
|
|
288 final XmlRpcCommonsTransportFactory factory = new XmlRpcCommonsTransportFactory(client);
|
|
|
289 factory.setHttpClient(httpClient);
|
|
|
290 client.setTransportFactory(factory);
|
|
|
291 final HttpState httpState = client.getState();
</pre>
|
|
|
292 </div>
|
|
|
293 <p>Cookies may now be read or set on the httpState object.</p>
|
|
|
294 <p>Note, that this means losing the XmlRpcClients multithreading abilities! The factory above is obviously bound to the HttpClient, which must be bound to a thread. If you need to set cookies initially, overwrite the transport method initHttpHeaders(XmlRpcRequest) as well.</p>
|
|
|
295 </li>
|
|
|
296 </ul>
|
|
|
297 </div>
|
|
|
298 <div class="section"><h3>Custom data types</h3>
|
|
|
299 <p>Apache XML-RPC was built with extensibility in mind. In particular, it was written to support custom data types.</p>
|
|
|
300 <p>The data type handling is completely left to the <a href="apidocs/org/apache/xmlrpc/common/TypeFactory.html">TypeFactory</a>. In other words, adding support for custom data types is as simple as providing your own type factory. This is typically done by subclassing <a href="apidocs/org/apache/xmlrpc/common/TypeFactoryImpl.html">TypeFactoryImpl</a>.</p>
|
|
|
301 <p>We'll illustrate the concept by creating a type factory, which uses a non-standard date format for transmitting date values. First of all, we've got to implement the subclass:</p>
|
|
|
302 <div class="source"><pre> import java.text.DateFormat;
|
|
|
303 import java.text.SimpleDateFormat;
|
|
|
304 import org.apache.xmlrpc.common.TypeFactoryImpl;
|
|
|
305 import org.apache.xmlrpc.common.XmlRpcController;
|
|
|
306 import org.apache.xmlrpc.parser.DateParser;
|
|
|
307 import org.apache.xmlrpc.parser.TypeParser;
|
|
|
308 import org.apache.xmlrpc.serializer.DateSerializer;
|
|
|
309 import org.apache.xmlrpc.serializer.TypeSerializer;
|
|
|
310 import org.apache.ws.commons.util.NamespaceContextImpl;
|
|
|
311
|
|
|
312 public class MyTypeFactory extends TypeFactoryImpl {
|
|
|
313 public MyTypeFactory(XmlRpcController pController) {
|
|
|
314 super(pController);
|
|
|
315 }
|
|
|
316
|
|
|
317 private DateFormat newFormat() {
|
|
|
318 return new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
|
|
|
319 }
|
|
|
320
|
|
|
321 public TypeParser getParser(XmlRpcStreamConfig pConfig, NamespaceContextImpl pContext, String pURI, String pLocalName) {
|
|
|
322 if (DateSerializer.DATE_TAG.equals(pLocalName)) {
|
|
|
323 return new DateParser(pFormat);
|
|
|
324 } else {
|
|
|
325 return super.getParser(pConfig, pContext, pURI, pLocalName);
|
|
|
326 }
|
|
|
327 }
|
|
|
328
|
|
|
329 public TypeSerializer getSerializer(XmlRpcStreamConfig pConfig, Object pObject) throws SAXException {
|
|
|
330 if (pObject instanceof Date) {
|
|
|
331 return new DateSerializer(newFormat());
|
|
|
332 } else {
|
|
|
333 return super.getSerializer(pConfig, pObject);
|
|
|
334 }
|
|
|
335 }
|
|
|
336 }
</pre>
|
|
|
337 </div>
|
|
|
338 <p>On the client side, we've got to tell the <a href="apidocs/org/apache/xmlrpc/client/XmlRpcClient.html">XmlRpcClient</a> to use the new factory. That's as simple as typing</p>
|
|
|
339 <div class="source"><pre> XmlRpcClient client = new XmlRpcClient();
|
|
|
340 client.setTypeFactory(new MyTypeFactory());
</pre>
|
|
|
341 </div>
|
|
|
342 <p>Things are a little bit more difficult on the server side. Basically all we need to do is setting the type factory on the <a href="apidocs/org/apache/xmlrpc/server/XmlRpcServer.html">XmlRpcServer</a>. The question is, how to obtain the server object. That depends on the environment. If you are using the XmlRpcServlet, then you've got to derive a subclass:</p>
|
|
|
343 <div class="source"><pre> import org.apache.xmlrpc.webserver.XmlRpcServletServer;
|
|
|
344 import org.apache.xmlrpc.webserver.XmlRpcServlet;
|
|
|
345
|
|
|
346 public class MyXmlRpcServlet extends XmlRpcServlet {
|
|
|
347 protected XmlRpcServletServer newXmlRpcServer(ServletConfig pConfig) {
|
|
|
348 XmlRpcServletServer server = super.newXmlRpcServer(pConfig);
|
|
|
349 server.setTypeFactory(new MyTypeFactory(server));
|
|
|
350 return server;
|
|
|
351 }
|
|
|
352 }
</pre>
|
|
|
353 </div>
|
|
|
354 <p>And, if you are using the <a href="apidocs/org/apache/xmlrpc/webserver/WebServer.html">WebServer</a>, you've got to override a similar method:</p>
|
|
|
355 <div class="source"><pre> import java.net.InetAddress;
|
|
|
356 import org.apache.xmlrpc.server.XmlRpcStreamServer;
|
|
|
357 import org.apache.xmlrpc.webserver.WebServer;
|
|
|
358
|
|
|
359 public class MyWebServer extends WebServer {
|
|
|
360 public MyWebServer(int pPort) {
|
|
|
361 super(pPort);
|
|
|
362 }
|
|
|
363
|
|
|
364 public MyWebServer(int pPort, InetAddress pAddr) {
|
|
|
365 super(pPort, pAddr);
|
|
|
366 }
|
|
|
367
|
|
|
368 protected XmlRpcStreamServer newXmlRpcStreamServer() {
|
|
|
369 XmlRpcStreamServer server = new ConnectionServer();
|
|
|
370 server.setTypeFactory(new MyTypeFactory());
|
|
|
371 return server;
|
|
|
372 }
|
|
|
373 }
</pre>
|
|
|
374 </div>
|
|
|
375 </div>
|
|
|
376 </div>
|
|
|
377
|
|
|
378 </div>
|
|
|
379 </div>
|
|
|
380 <div class="clear">
|
|
|
381 <hr/>
|
|
|
382 </div>
|
|
|
383 <div id="footer">
|
|
|
384 <div class="xright">©
|
|
|
385 2001-2010
|
|
|
386
|
|
|
387 The Apache Software Foundation
|
|
|
388
|
|
|
389
|
|
|
390
|
|
|
391
|
|
|
392
|
|
|
393
|
|
|
394
|
|
|
395
|
|
|
396 </div>
|
|
|
397 <div class="clear">
|
|
|
398 <hr/>
|
|
|
399 </div>
|
|
|
400 </div>
|
|
|
401 </body>
|
|
|
402 </html>
|
