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 <a href="http://mina.apache.org">Apache MINA Project</a>
34   *
35   * @see DemuxingProtocolDecoder
36   * @see MessageDecoderFactory
37   */
38  public interface MessageDecoder {
39      /**
40       * Represents a result from {@link #decodable(IoSession, IoBuffer)} and
41       * {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}.  Please
42       * refer to each method's documentation for detailed explanation.
43       */
44      static MessageDecoderResult OK = MessageDecoderResult.OK;
45  
46      /**
47       * Represents a result from {@link #decodable(IoSession, IoBuffer)} and
48       * {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}.  Please
49       * refer to each method's documentation for detailed explanation.
50       */
51      static MessageDecoderResult NEED_DATA = MessageDecoderResult.NEED_DATA;
52  
53      /**
54       * Represents a result from {@link #decodable(IoSession, IoBuffer)} and
55       * {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}.  Please
56       * refer to each method's documentation for detailed explanation.
57       */
58      static MessageDecoderResult NOT_OK = MessageDecoderResult.NOT_OK;
59  
60      /**
61       * Checks the specified buffer is decodable by this decoder.
62       *
63       * @return {@link #OK} if this decoder can decode the specified buffer.
64       *         {@link #NOT_OK} if this decoder cannot decode the specified buffer.
65       *         {@link #NEED_DATA} if more data is required to determine if the
66       *         specified buffer is decodable ({@link #OK}) or not decodable
67       *         {@link #NOT_OK}.
68       */
69      MessageDecoderResult decodable(IoSession session, IoBuffer in);
70  
71      /**
72       * Decodes binary or protocol-specific content into higher-level message objects.
73       * MINA invokes {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}
74       * method with read data, and then the decoder implementation puts decoded
75       * messages into {@link ProtocolDecoderOutput}.
76       *
77       * @return {@link #OK} if you finished decoding messages successfully.
78       *         {@link #NEED_DATA} if you need more data to finish decoding current message.
79       *         {@link #NOT_OK} if you cannot decode current message due to protocol specification violation.
80       *
81       * @throws Exception if the read data violated protocol specification
82       */
83      MessageDecoderResult decode(IoSession session, IoBuffer in, ProtocolDecoderOutput out) throws Exception;
84  
85      /**
86       * Invoked when the specified <tt>session</tt> is closed while this decoder was
87       * parsing the data.  This method is useful when you deal with the protocol which doesn't
88       * specify the length of a message such as HTTP response without <tt>content-length</tt>
89       * header. Implement this method to process the remaining data that
90       * {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)} method didn't process
91       * completely.
92       *
93       * @throws Exception if the read data violated protocol specification
94       */
95      void finishDecode(IoSession session, ProtocolDecoderOutput out) throws Exception;
96  }