View Javadoc

1   package org.apache.turbine.services.xmlrpc;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
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 }