001: // serverHandler.java
002: // -------------------------------------------
003: // (C) by Michael Peter Christen; mc@anomic.de
004: // first published on http://www.anomic.de
005: // Frankfurt, Germany, 2004
006: // last major change: 05.04.2004
007: //
008: // This program is free software; you can redistribute it and/or modify
009: // it under the terms of the GNU General Public License as published by
010: // the Free Software Foundation; either version 2 of the License, or
011: // (at your option) any later version.
012: //
013: // This program is distributed in the hope that it will be useful,
014: // but WITHOUT ANY WARRANTY; without even the implied warranty of
015: // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
016: // GNU General Public License for more details.
017: //
018: // You should have received a copy of the GNU General Public License
019: // along with this program; if not, write to the Free Software
020: // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
021: //
022: // Using this software in any meaning (reading, learning, copying, compiling,
023: // running) means that you agree that the Author(s) is (are) not responsible
024: // for cost, loss of data or any harm that may be caused directly or indirectly
025: // by usage of this softare or this documentation. The usage of this software
026: // is on your own risk. The installation and usage (starting/running) of this
027: // software may allow other people or application to access your computer and
028: // any attached devices and is highly dependent on the configuration of the
029: // software which must be done by the user of the software; the author(s) is
030: // (are) also not responsible for proper configuration and usage of the
031: // software, even if provoked by documentation provided together with
032: // the software.
033: //
034: // Any changes to this file according to the GPL as documented in the file
035: // gpl.txt aside this file in the shipment you received can be done to the
036: // lines that follows this copyright notice here, but changes must not be
037: // done inside the copyright notive above. A re-distribution must contain
038: // the intact and unchanged copyright notice.
039: // Contributions and changes to the program code must be marked as such.
040:
041: /*
042: serverHandler:
043:
044: A Generic Server becomes a server for s specific protocol by impementation of
045: a corresponding handler class. The handler class provides methods for each
046: command of the protocol that is implemented.
047: The Handler class is assigned to the serverCore by passing the handlers
048: name to the serverCore upon initialization.
049: Example:
050: serverCore server = new serverCore(port, 1000, 0, false, "ftpdProtocol", null, 0);
051: In this example the protocol handler "ftpdProtocol" is assigned. There a class
052: named ftpdProtocol.java must be implemented, that implements this interface,
053: a serverHandler.
054: Any protocol command can be implemented in either way:
055:
056: public String COMMAND(String arg) throws IOException;
057: public InputStream COMMAND(String arg) throws IOException;
058: public void COMMAND(String arg) throws IOException;
059:
060: ..where COMMAND is the command that had been passed to the server
061: on the terminal connection. The 'arg' argument is the remaining part of
062: the command on the terminal connection.
063: If the handler method returns a NULL value, which is especially
064: the case if the method implements a 'void' return-value method,
065: then the server disconnects the connection.
066: Any other return value (String or an InputStream) is returned to
067: the client on it's own line through the terminal connection.
068: If it is wanted that the server terminates right after submitting
069: a last line, then this can be indicated by prefixing the return
070: value by a '!'-character.
071:
072: If one of the command methods throws a IOException, then the
073: server asks the error - method for a return value on the terminal
074: connection.
075:
076: The greeting-method is used to request a string that is transmitted
077: to the client as terminal output at the beginning of a connection
078: session.
079: */
080:
081: package de.anomic.server;
082:
083: import java.io.IOException;
084:
085: public interface serverHandler {
086:
087: // init method for static variables of the handler
088: // this method shall be called only once
089: // information that is passed here is cloned for every new instance
090: //public void initHandler(serverSwitch switchboard) throws java.io.IOException;
091:
092: // an init method that the server calls to provide hooks and
093: // information to the session's sockets and information
094: // the Switchboard allowes to trigger events through all sessions
095: // and an supervision process.
096: // this method shall be called only once
097: public void initSession(serverCore.Session session)
098: throws java.io.IOException;
099:
100: // a response line upon connection is send to client
101: // if no response line is wanted, return "" or null
102: public String greeting();
103:
104: // return string in case of any error that occurs during communication
105: // is always (but not only) called if an IO-dependent exception occurs.
106: public String error(Throwable e);
107:
108: // clone method for the handler prototype
109: // each time a server makes a new connection it clones the hanlder prototype
110: // the clone method does not need to clone every detail of a handler connection,
111: // but only the necessary one for a newly initialized instance
112: public Object clone();
113:
114: /**
115: * Instead of using clone this function can be used to reset an existing
116: * handler prototype so that it can e reused
117: */
118: public void reset();
119:
120: /**
121: * Tthis function will be called by the {@link serverCore}.listen() function
122: * if the whole request line is empty and therefore no function of this
123: * serverHandlerClass can be called because of the missing command name
124: */
125: public Boolean EMPTY(String arg) throws IOException;
126:
127: /**
128: * This function will be called by the {@link serverCore}.listen() function
129: * if no corresponding funktion of the serverHandler class can be
130: * found for the received command.
131: */
132: public Boolean UNKNOWN(String requestLine) throws IOException;
133: }
|