001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License.
018 *
019 */
020package org.apache.mina.filter.codec.demux;
021
022import org.apache.mina.core.buffer.IoBuffer;
023import org.apache.mina.core.session.IoSession;
024import org.apache.mina.filter.codec.ProtocolDecoderOutput;
025
026/**
027 * Decodes a certain type of messages.
028 * <p>
029 * We didn't provide any <tt>dispose</tt> method for {@link MessageDecoder}
030 * because it can give you  performance penalty in case you have a lot of
031 * message types to handle.
032 *
033 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
034 *
035 * @see DemuxingProtocolDecoder
036 * @see MessageDecoderFactory
037 */
038public interface MessageDecoder {
039    /**
040     * Represents a result from {@link #decodable(IoSession, IoBuffer)} and
041     * {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}.  Please
042     * refer to each method's documentation for detailed explanation.
043     */
044    MessageDecoderResult OK = MessageDecoderResult.OK;
045
046    /**
047     * Represents a result from {@link #decodable(IoSession, IoBuffer)} and
048     * {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}.  Please
049     * refer to each method's documentation for detailed explanation.
050     */
051    MessageDecoderResult NEED_DATA = MessageDecoderResult.NEED_DATA;
052
053    /**
054     * Represents a result from {@link #decodable(IoSession, IoBuffer)} and
055     * {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}.  Please
056     * refer to each method's documentation for detailed explanation.
057     */
058    MessageDecoderResult NOT_OK = MessageDecoderResult.NOT_OK;
059
060    /**
061     * Checks the specified buffer is decodable by this decoder.
062     *
063     * @param session The current session
064     * @param in The buffer containing the data to decode
065     * @return {@link #OK} if this decoder can decode the specified buffer.
066     *         {@link #NOT_OK} if this decoder cannot decode the specified buffer.
067     *         {@link #NEED_DATA} if more data is required to determine if the
068     *         specified buffer is decodable ({@link #OK}) or not decodable
069     *         {@link #NOT_OK}.
070     */
071    MessageDecoderResult decodable(IoSession session, IoBuffer in);
072
073    /**
074     * Decodes binary or protocol-specific content into higher-level message objects.
075     * MINA invokes {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}
076     * method with read data, and then the decoder implementation puts decoded
077     * messages into {@link ProtocolDecoderOutput}.
078     *
079     * @param session The current session
080     * @param in The buffer containing the data to decode
081     * @param out The instance of {@link ProtocolDecoderOutput} that will receive the decoded messages
082     * @return {@link #OK} if you finished decoding messages successfully.
083     *         {@link #NEED_DATA} if you need more data to finish decoding current message.
084     *         {@link #NOT_OK} if you cannot decode current message due to protocol specification violation.
085     * @throws Exception if the read data violated protocol specification
086     */
087    MessageDecoderResult decode(IoSession session, IoBuffer in, ProtocolDecoderOutput out) throws Exception;
088
089    /**
090     * Invoked when the specified <tt>session</tt> is closed while this decoder was
091     * parsing the data.  This method is useful when you deal with the protocol which doesn't
092     * specify the length of a message such as HTTP response without <tt>content-length</tt>
093     * header. Implement this method to process the remaining data that
094     * {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)} method didn't process
095     * completely.
096     *
097     * @param session The current session
098     * @param out The instance of {@link ProtocolDecoderOutput} that contains the decoded messages
099     * @throws Exception if the read data violated protocol specification
100     */
101    void finishDecode(IoSession session, ProtocolDecoderOutput out) throws Exception;
102}