001: package org.apache.turbine.services.xmlrpc;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import java.io.InputStream;
023:
024: import java.net.URL;
025:
026: import java.util.Vector;
027:
028: import org.apache.turbine.services.Service;
029: import org.apache.turbine.util.TurbineException;
030:
031: /**
032: * The interface an XmlRpcService implements.
033: *
034: * @author <a href="mailto:josh@stonecottage.com">Josh Lucas</a>
035: * @author <a href="mailto:magnus@handtolvur.is">Magnús Þór Torfason</a>
036: * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
037: * @author <a href="jvanzyl@periapt.com">Jason van Zyl</a>
038: * @version $Id: XmlRpcService.java 534527 2007-05-02 16:10:59Z tv $
039: */
040: public interface XmlRpcService extends Service {
041: /** TurbineXmlRpcService. */
042: String SERVICE_NAME = "XmlRpcService";
043:
044: /**
045: * Execute a remote procedure call.
046: *
047: * @param url A URL.
048: * @param methodName A String with the method name.
049: * @param params A Vector with the parameters.
050: * @return An Object.
051: * @exception TurbineException
052: */
053: Object executeRpc(URL url, String methodName, Vector params)
054: throws TurbineException;
055:
056: /**
057: * Execute a remote procedure call taht requires
058: * authentication.
059: *
060: * @param url A URL.
061: * @param username The username to authenticate with
062: * @param password The password to authenticate with
063: * @param methodName A String with the method name.
064: * @param params A Vector with the parameters.
065: * @return An Object.
066: * @exception TurbineException
067: */
068: Object executeAuthenticatedRpc(URL url, String username,
069: String password, String methodName, Vector params)
070: throws TurbineException;
071:
072: /**
073: * Register an object as a handler for the XmlRpc Server part.
074: *
075: * @param handlerName The name under which we want
076: * to register the service
077: * @param handler The handler object
078: */
079: void registerHandler(String handlerName, Object handler);
080:
081: /**
082: * Register an object as a the default handler for
083: * the XmlRpc Server part.
084: *
085: * @param handler The handler object
086: */
087: void registerHandler(Object handler);
088:
089: /**
090: * Unregister a handler.
091: *
092: * @param handlerName The name of the handler to unregister.
093: */
094: void unregisterHandler(String handlerName);
095:
096: /**
097: * Handle an XML-RPC request using the encapsulated server.
098: *
099: * You can use this method to handle a request from within
100: * a Turbine screen.
101: *
102: * @param is the stream to read request data from.
103: * @return the response body that needs to be sent to the client.
104: */
105: byte[] handleRequest(InputStream is);
106:
107: /**
108: * Handle an XML-RPC request using the encapsulated server with user
109: * authentication.
110: *
111: * You can use this method to handle a request from within
112: * a Turbine screen.
113: *
114: * <p> Note that the handlers need to implement AuthenticatedXmlRpcHandler
115: * interface to access the authentication infomration.
116: *
117: * @param is the stream to read request data from.
118: * @param user the user that is making the request.
119: * @param password the password given by user.
120: * @return the response body that needs to be sent to the client.
121: */
122: byte[] handleRequest(InputStream is, String user, String password);
123:
124: /**
125: * Method to allow a client to send a file to a server.
126: *
127: * @param serverURL
128: * @param sourceLocationProperty
129: * @param sourceFileName
130: * @param destinationLocationProperty
131: * @param destinationFileName
132: * @throws TurbineException
133: * @deprecated This is not scope of the Service itself but of an
134: * application which uses the service.
135: */
136: void send(String serverURL, String sourceLocationProperty,
137: String sourceFileName, String destinationLocationProperty,
138: String destinationFileName) throws TurbineException;
139:
140: /**
141: * Method to allow a client to send a file to a server that
142: * requires authentication
143: *
144: * @param serverURL
145: * @param username
146: * @param password
147: * @param sourceLocationProperty
148: * @param sourceFileName
149: * @param destinationLocationProperty
150: * @param destinationFileName
151: * @throws TurbineException
152: * @deprecated This is not scope of the Service itself but of an
153: * application which uses the service.
154: */
155: void send(String serverURL, String username, String password,
156: String sourceLocationProperty, String sourceFileName,
157: String destinationLocationProperty,
158: String destinationFileName) throws TurbineException;
159:
160: /**
161: * Method to allow a client to send a file to a server.
162: *
163: * @param serverURL
164: * @param sourceLocationProperty
165: * @param sourceFileName
166: * @param destinationLocationProperty
167: * @param destinationFileName
168: * @throws TurbineException
169: * @deprecated This is not scope of the Service itself but of an
170: * application which uses the service.
171: */
172: void get(String serverURL, String sourceLocationProperty,
173: String sourceFileName, String destinationLocationProperty,
174: String destinationFileName) throws TurbineException;
175:
176: /**
177: * Method to allow a client to send a file to a server that
178: * requires authentication
179: *
180: * @param serverURL
181: * @param username
182: * @param password
183: * @param sourceLocationProperty
184: * @param sourceFileName
185: * @param destinationLocationProperty
186: * @param destinationFileName
187: * @throws TurbineException
188: * @deprecated This is not scope of the Service itself but of an
189: * application which uses the service.
190: */
191: void get(String serverURL, String username, String password,
192: String sourceLocationProperty, String sourceFileName,
193: String destinationLocationProperty,
194: String destinationFileName) throws TurbineException;
195:
196: /**
197: * Method to allow a client to remove a file from
198: * the server
199: *
200: * @param serverURL
201: * @param sourceLocationProperty
202: * @param sourceFileName
203: * @throws TurbineException
204: * @deprecated This is not scope of the Service itself but of an
205: * application which uses the service.
206: */
207: void remove(String serverURL, String sourceLocationProperty,
208: String sourceFileName) throws TurbineException;
209:
210: /**
211: * Method to allow a client to remove a file from
212: * a server that requires authentication
213: *
214: * @param serverURL
215: * @param username
216: * @param password
217: * @param sourceLocationProperty
218: * @param sourceFileName
219: * @throws TurbineException
220: * @deprecated This is not scope of the Service itself but of an
221: * application which uses the service.
222: */
223: void remove(String serverURL, String username, String password,
224: String sourceLocationProperty, String sourceFileName)
225: throws TurbineException;
226:
227: /**
228: * Switch client filtering on/off.
229: *
230: * @param state
231: * @see #acceptClient(java.lang.String)
232: * @see #denyClient(java.lang.String)
233: */
234: void setParanoid(boolean state);
235:
236: /**
237: * Add an IP address to the list of accepted clients. The parameter can
238: * contain '*' as wildcard character, e.g. "192.168.*.*". You must
239: * call setParanoid(true) in order for this to have
240: * any effect.
241: *
242: * @param address
243: * @see #denyClient(java.lang.String)
244: * @see #setParanoid(boolean)
245: */
246: void acceptClient(String address);
247:
248: /**
249: * Add an IP address to the list of denied clients. The parameter can
250: * contain '*' as wildcard character, e.g. "192.168.*.*". You must call
251: * setParanoid(true) in order for this to have any effect.
252: *
253: * @param address
254: * @see #acceptClient(java.lang.String)
255: * @see #setParanoid(boolean)
256: */
257: void denyClient(String address);
258:
259: }
|