View Javadoc

1   /*
2    *  Licensed to the Apache Software Foundation (ASF) under one
3    *  or more contributor license agreements.  See the NOTICE file
4    *  distributed with this work for additional information
5    *  regarding copyright ownership.  The ASF licenses this file
6    *  to you under the Apache License, Version 2.0 (the
7    *  "License"); you may not use this file except in compliance
8    *  with the License.  You may obtain a copy of the License at
9    *
10   *    http://www.apache.org/licenses/LICENSE-2.0
11   *
12   *  Unless required by applicable law or agreed to in writing,
13   *  software distributed under the License is distributed on an
14   *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   *  KIND, either express or implied.  See the License for the
16   *  specific language governing permissions and limitations
17   *  under the License.
18   *
19   */
20  package org.apache.mina.filter.codec.demux;
21  
22  import org.apache.mina.core.buffer.IoBuffer;
23  import org.apache.mina.core.session.IoSession;
24  import org.apache.mina.filter.codec.ProtocolDecoderOutput;
25  
26  /**
27   * Decodes a certain type of messages.
28   * <p>
29   * We didn't provide any <tt>dispose</tt> method for {@link MessageDecoder}
30   * because it can give you  performance penalty in case you have a lot of
31   * message types to handle.
32   *
33   * @author The Apache MINA Project (dev@mina.apache.org)
34   * @version $Rev: 671827 $, $Date: 2008-06-26 10:49:48 +0200 (jeu, 26 jun 2008) $
35   *
36   * @see DemuxingProtocolDecoder
37   * @see MessageDecoderFactory
38   */
39  public interface MessageDecoder {
40      /**
41       * Represents a result from {@link #decodable(IoSession, IoBuffer)} and
42       * {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}.  Please
43       * refer to each method's documentation for detailed explanation.
44       */
45      static MessageDecoderResult OK = MessageDecoderResult.OK;
46  
47      /**
48       * Represents a result from {@link #decodable(IoSession, IoBuffer)} and
49       * {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}.  Please
50       * refer to each method's documentation for detailed explanation.
51       */
52      static MessageDecoderResult NEED_DATA = MessageDecoderResult.NEED_DATA;
53  
54      /**
55       * Represents a result from {@link #decodable(IoSession, IoBuffer)} and
56       * {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}.  Please
57       * refer to each method's documentation for detailed explanation.
58       */
59      static MessageDecoderResult NOT_OK = MessageDecoderResult.NOT_OK;
60  
61      /**
62       * Checks the specified buffer is decodable by this decoder.
63       *
64       * @return {@link #OK} if this decoder can decode the specified buffer.
65       *         {@link #NOT_OK} if this decoder cannot decode the specified buffer.
66       *         {@link #NEED_DATA} if more data is required to determine if the
67       *         specified buffer is decodable ({@link #OK}) or not decodable
68       *         {@link #NOT_OK}.
69       */
70      MessageDecoderResult decodable(IoSession session, IoBuffer in);
71  
72      /**
73       * Decodes binary or protocol-specific content into higher-level message objects.
74       * MINA invokes {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}
75       * method with read data, and then the decoder implementation puts decoded
76       * messages into {@link ProtocolDecoderOutput}.
77       *
78       * @return {@link #OK} if you finished decoding messages successfully.
79       *         {@link #NEED_DATA} if you need more data to finish decoding current message.
80       *         {@link #NOT_OK} if you cannot decode current message due to protocol specification violation.
81       *
82       * @throws Exception if the read data violated protocol specification
83       */
84      MessageDecoderResult decode(IoSession session, IoBuffer in,
85              ProtocolDecoderOutput out) throws Exception;
86  
87      /**
88       * Invoked when the specified <tt>session</tt> is closed while this decoder was
89       * parsing the data.  This method is useful when you deal with the protocol which doesn't
90       * specify the length of a message such as HTTP response without <tt>content-length</tt>
91       * header. Implement this method to process the remaining data that
92       * {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)} method didn't process
93       * completely.
94       *
95       * @throws Exception if the read data violated protocol specification
96       */
97      void finishDecode(IoSession session, ProtocolDecoderOutput out)
98              throws Exception;
99  }