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