001    /**
002     * Jetrix TetriNET Server
003     * Copyright (C) 2001-2003  Emmanuel Bourg
004     *
005     * This program is free software; you can redistribute it and/or
006     * modify it under the terms of the GNU General Public License
007     * as published by the Free Software Foundation; either version 2
008     * of the License, or (at your option) any later version.
009     *
010     * This program is distributed in the hope that it will be useful,
011     * but WITHOUT ANY WARRANTY; without even the implied warranty of
012     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
013     * GNU General Public License for more details.
014     *
015     * You should have received a copy of the GNU General Public License
016     * along with this program; if not, write to the Free Software
017     * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
018     */
019    
020    package net.jetrix;
021    
022    import java.io.IOException;
023    import java.io.InputStream;
024    import java.util.Locale;
025    
026    /**
027     * A protocol to communicate with a client. A protocol is responsible for
028     * transforming the messages in string format comming for a client into the
029     * corresponding server {@link net.jetrix.Message}, as well as performing the
030     * reverse operation.
031     *
032     * @author Emmanuel Bourg
033     * @version $Revision: 848 $, $Date: 2010-05-03 22:51:32 +0200 (lun., 03 mai 2010) $
034     */
035    public interface Protocol
036    {
037        /**
038         * Return the name of this protocol.
039         *
040         * @return the name of this protocol
041         */
042        String getName();
043    
044        /**
045         * Parse the specified string and return the corresponding server
046         * message for this protocol.
047         *
048         * @param message the client message to parse
049         *
050         * @return the {@link net.jetrix.Message} equivalent of the specified
051         *     String or null if the protocol cannot understand the message.
052         */
053        Message getMessage(String message);
054    
055        /**
056         * Translate the specified message into a string that will be sent
057         * to a client using this protocol.
058         *
059         * @param m the message to translate
060         * @param locale the locale used for internationalized text messages
061         *
062         * @return the String equivalent in this protocol for the specified
063         *     {@link net.jetrix.Message} or null if it can't be translated.
064         */
065        String translate(Message m, Locale locale);
066    
067        /**
068         * Transform the style tags (<tt>&lt;blue&gt;</tt>, <tt>&lt;u&gt;</tt>,
069         * etc...) contained in the specified string into the style codes of this
070         * protocol.
071         *
072         * @param text the string to transform
073         *
074         * @return the stylized representation of the specified string for
075         *     this protocol.
076         */
077        String applyStyle(String text);
078    
079        /**
080         * Return the end of line character used by this protocol.
081         */
082        char getEOL();
083    
084        /**
085         * Read a line for this protocol. A line is ended by a \n or \r character,
086         * or by a protocol specific end of line as defined by the {@link #getEOL()}
087         * method.
088         *
089         * @since 0.3
090         *
091         * @param in       the stream to be read
092         * @param encoding the charset encoding used to read the message
093         * @throws IOException thrown if the stream is closed
094         */
095        String readLine(InputStream in, String encoding) throws IOException;
096    
097    }