1 package org.apache.turbine.services.xmlrpc;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 import java.io.InputStream;
23
24 import java.net.URL;
25
26 import java.util.Vector;
27
28 import org.apache.turbine.services.Service;
29 import org.apache.turbine.util.TurbineException;
30
31 /***
32 * The interface an XmlRpcService implements.
33 *
34 * @author <a href="mailto:josh@stonecottage.com">Josh Lucas</a>
35 * @author <a href="mailto:magnus@handtolvur.is">Magnús Þór Torfason</a>
36 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
37 * @author <a href="jvanzyl@periapt.com">Jason van Zyl</a>
38 * @version $Id: XmlRpcService.java 534527 2007-05-02 16:10:59Z tv $
39 */
40 public interface XmlRpcService
41 extends Service
42 {
43 /*** TurbineXmlRpcService. */
44 String SERVICE_NAME = "XmlRpcService";
45
46 /***
47 * Execute a remote procedure call.
48 *
49 * @param url A URL.
50 * @param methodName A String with the method name.
51 * @param params A Vector with the parameters.
52 * @return An Object.
53 * @exception TurbineException
54 */
55 Object executeRpc(URL url,
56 String methodName,
57 Vector params)
58 throws TurbineException;
59
60 /***
61 * Execute a remote procedure call taht requires
62 * authentication.
63 *
64 * @param url A URL.
65 * @param username The username to authenticate with
66 * @param password The password to authenticate with
67 * @param methodName A String with the method name.
68 * @param params A Vector with the parameters.
69 * @return An Object.
70 * @exception TurbineException
71 */
72 Object executeAuthenticatedRpc(URL url,
73 String username,
74 String password,
75 String methodName,
76 Vector params)
77 throws TurbineException;
78
79 /***
80 * Register an object as a handler for the XmlRpc Server part.
81 *
82 * @param handlerName The name under which we want
83 * to register the service
84 * @param handler The handler object
85 */
86 void registerHandler(String handlerName, Object handler);
87
88 /***
89 * Register an object as a the default handler for
90 * the XmlRpc Server part.
91 *
92 * @param handler The handler object
93 */
94 void registerHandler(Object handler);
95
96 /***
97 * Unregister a handler.
98 *
99 * @param handlerName The name of the handler to unregister.
100 */
101 void unregisterHandler(String handlerName);
102
103 /***
104 * Handle an XML-RPC request using the encapsulated server.
105 *
106 * You can use this method to handle a request from within
107 * a Turbine screen.
108 *
109 * @param is the stream to read request data from.
110 * @return the response body that needs to be sent to the client.
111 */
112 byte[] handleRequest(InputStream is);
113
114 /***
115 * Handle an XML-RPC request using the encapsulated server with user
116 * authentication.
117 *
118 * You can use this method to handle a request from within
119 * a Turbine screen.
120 *
121 * <p> Note that the handlers need to implement AuthenticatedXmlRpcHandler
122 * interface to access the authentication infomration.
123 *
124 * @param is the stream to read request data from.
125 * @param user the user that is making the request.
126 * @param password the password given by user.
127 * @return the response body that needs to be sent to the client.
128 */
129 byte[] handleRequest(InputStream is, String user, String password);
130
131 /***
132 * Method to allow a client to send a file to a server.
133 *
134 * @param serverURL
135 * @param sourceLocationProperty
136 * @param sourceFileName
137 * @param destinationLocationProperty
138 * @param destinationFileName
139 * @throws TurbineException
140 * @deprecated This is not scope of the Service itself but of an
141 * application which uses the service.
142 */
143 void send(String serverURL,
144 String sourceLocationProperty,
145 String sourceFileName,
146 String destinationLocationProperty,
147 String destinationFileName)
148 throws TurbineException;
149
150 /***
151 * Method to allow a client to send a file to a server that
152 * requires authentication
153 *
154 * @param serverURL
155 * @param username
156 * @param password
157 * @param sourceLocationProperty
158 * @param sourceFileName
159 * @param destinationLocationProperty
160 * @param destinationFileName
161 * @throws TurbineException
162 * @deprecated This is not scope of the Service itself but of an
163 * application which uses the service.
164 */
165 void send(String serverURL,
166 String username,
167 String password,
168 String sourceLocationProperty,
169 String sourceFileName,
170 String destinationLocationProperty,
171 String destinationFileName)
172 throws TurbineException;
173
174 /***
175 * Method to allow a client to send a file to a server.
176 *
177 * @param serverURL
178 * @param sourceLocationProperty
179 * @param sourceFileName
180 * @param destinationLocationProperty
181 * @param destinationFileName
182 * @throws TurbineException
183 * @deprecated This is not scope of the Service itself but of an
184 * application which uses the service.
185 */
186 void get(String serverURL,
187 String sourceLocationProperty,
188 String sourceFileName,
189 String destinationLocationProperty,
190 String destinationFileName)
191 throws TurbineException;
192
193 /***
194 * Method to allow a client to send a file to a server that
195 * requires authentication
196 *
197 * @param serverURL
198 * @param username
199 * @param password
200 * @param sourceLocationProperty
201 * @param sourceFileName
202 * @param destinationLocationProperty
203 * @param destinationFileName
204 * @throws TurbineException
205 * @deprecated This is not scope of the Service itself but of an
206 * application which uses the service.
207 */
208 void get(String serverURL,
209 String username,
210 String password,
211 String sourceLocationProperty,
212 String sourceFileName,
213 String destinationLocationProperty,
214 String destinationFileName)
215 throws TurbineException;
216
217 /***
218 * Method to allow a client to remove a file from
219 * the server
220 *
221 * @param serverURL
222 * @param sourceLocationProperty
223 * @param sourceFileName
224 * @throws TurbineException
225 * @deprecated This is not scope of the Service itself but of an
226 * application which uses the service.
227 */
228 void remove(String serverURL,
229 String sourceLocationProperty,
230 String sourceFileName)
231 throws TurbineException;
232
233 /***
234 * Method to allow a client to remove a file from
235 * a server that requires authentication
236 *
237 * @param serverURL
238 * @param username
239 * @param password
240 * @param sourceLocationProperty
241 * @param sourceFileName
242 * @throws TurbineException
243 * @deprecated This is not scope of the Service itself but of an
244 * application which uses the service.
245 */
246 void remove(String serverURL,
247 String username,
248 String password,
249 String sourceLocationProperty,
250 String sourceFileName)
251 throws TurbineException;
252
253 /***
254 * Switch client filtering on/off.
255 *
256 * @param state
257 * @see #acceptClient(java.lang.String)
258 * @see #denyClient(java.lang.String)
259 */
260 void setParanoid(boolean state);
261
262 /***
263 * Add an IP address to the list of accepted clients. The parameter can
264 * contain '*' as wildcard character, e.g. "192.168.*.*". You must
265 * call setParanoid(true) in order for this to have
266 * any effect.
267 *
268 * @param address
269 * @see #denyClient(java.lang.String)
270 * @see #setParanoid(boolean)
271 */
272 void acceptClient(String address);
273
274 /***
275 * Add an IP address to the list of denied clients. The parameter can
276 * contain '*' as wildcard character, e.g. "192.168.*.*". You must call
277 * setParanoid(true) in order for this to have any effect.
278 *
279 * @param address
280 * @see #acceptClient(java.lang.String)
281 * @see #setParanoid(boolean)
282 */
283 void denyClient(String address);
284
285 }