Source code: com/synaptics/elvis/ElvisHandler.java
1 /*
2 * The contents of this file are subject to the Mozilla Public License Version
3 * 1.1 (the "License"); you may not use this file except in compliance with the
4 * License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
5 *
6 * Software distributed under the License is distributed on an "AS IS" basis,
7 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
8 * the specific language governing rights and limitations under the License.
9 *
10 * The Original Code is com.synaptics.elvis code.
11 *
12 * The Initial Developers of the Original Code are Synaptics, Inc. and Christopher Heiny.
13 * Portions created by Synaptics, Inc. and Christopher Heiny are
14 * Copyright (C) 2002 Synaptics, Inc. and Christopher Heiny. All Rights Reserved.
15 *
16 * Contributor(s):
17 * Christopher Heiny <cheiny@synaptics.com>
18 */
19
20 package com.synaptics.elvis;
21
22 /** <CODE>ElvisHandler</code> is the primitive interface for the handlers passed
23 * to {@link com.synaptics.elvis.ElvisHandler#get(String,int,ElvisHandler) ElvisHandler.get() }.
24 * <CODE>perform()</code> will be called whenever the ElvisWatcher thread receives
25 * a request from an Elvis client.
26 * <P>Implementors of <CODE>ElvisHandler</code> must be aware that they are <B>not</b>
27 * being called from the Swing notification thread, and handle their UI interactions
28 * accordingly.
29 * <P><CODE>perform</code> is not called in a thread-safe manner. If we are the One
30 * True Elvis, then it is quite possible for
31 * the local Elvis client to call <CODE>perform</code> from one of its threads at the
32 * same time as another Elvis client transmits a request to us. In this case, it we
33 * will wind up with two different threads in the <CODE>perform</code> method. Although
34 * Elvis is thread-safe up until the point of collision, it is up to the client application
35 * (that is, <I>your</i> code) to take over thread-safety, starting with the <CODE>perform</code>
36 * method.
37 * <P>Also, to avoid potentially blocking Elvis clients while the handler does work,
38 * implementors will probably want to have a separate thread for actually doing
39 * the work of the ElvisHandler. In this case, <CODE>perform</code> should simply
40 * queue the request and then return.
41 *
42 *
43 * @author cheiny
44 * @version $Id: ElvisHandler.java,v 1.1 2002/05/09 07:17:17 clheiny Exp $
45 */
46 public interface ElvisHandler {
47
48 /** The <CODE>perform()</code> method is what actually performs the work associated with
49 * this incarnation of Elvis.
50 * @param data A Strings as received from an Elvis client.
51 * @returns An ElvisResult indicating the success or failure of the action, along with relevant data.
52 * @throws Nothing, unless the implementation is broken. If an exception is thrown, it will be logged
53 * and a failure result will be returned to the client.
54 */
55 ElvisResult perform(String data);
56
57 }
58