1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 package org.apache.mina.protocol.codec;
20
21 import org.apache.mina.common.ByteBuffer;
22 import org.apache.mina.protocol.ProtocolDecoderOutput;
23 import org.apache.mina.protocol.ProtocolSession;
24 import org.apache.mina.protocol.ProtocolViolationException;
25
26 /***
27 * Decodes specific messages.
28 *
29 * @author The Apache Directory Project (dev@directory.apache.org)
30 * @version $Rev: 357871 $, $Date: 2005-12-20 10:56:40 +0900 (Tue, 20 Dec 2005) $
31 *
32 * @see DemuxingProtocolCodecFactory
33 * @see MessageDecoderFactory
34 */
35 public interface MessageDecoder {
36 /***
37 * Represents a result from {@link #decodable(ProtocolSession, ByteBuffer)} and
38 * {@link #decode(ProtocolSession, ByteBuffer, ProtocolDecoderOutput)}. Please
39 * refer to each method's documentation for detailed explanation.
40 */
41 static MessageDecoderResult OK = MessageDecoderResult.OK;
42
43 /***
44 * Represents a result from {@link #decodable(ProtocolSession, ByteBuffer)} and
45 * {@link #decode(ProtocolSession, ByteBuffer, ProtocolDecoderOutput)}. Please
46 * refer to each method's documentation for detailed explanation.
47 */
48 static MessageDecoderResult NEED_DATA = MessageDecoderResult.NEED_DATA;
49
50 /***
51 * Represents a result from {@link #decodable(ProtocolSession, ByteBuffer)} and
52 * {@link #decode(ProtocolSession, ByteBuffer, ProtocolDecoderOutput)}. Please
53 * refer to each method's documentation for detailed explanation.
54 */
55 static MessageDecoderResult NOT_OK = MessageDecoderResult.NOT_OK;
56
57 /***
58 * Checks the specified buffer is decodable by this decoder.
59 *
60 * @return {@link #OK} if this decoder can decode the specified buffer.
61 * {@link #NOT_OK} if this decoder cannot decode the specified buffer.
62 * {@link #NEED_DATA} if more data is required to determine if the
63 * specified buffer is decodable ({@link #OK}) or not decodable
64 * {@link #NOT_OK}.
65 */
66 MessageDecoderResult decodable( ProtocolSession session, ByteBuffer in );
67
68 /***
69 * Decodes binary or protocol-specific content into higher-level message objects.
70 * MINA invokes {@link #decode(ProtocolSession, ByteBuffer, ProtocolDecoderOutput)}
71 * method with read data, and then the decoder implementation puts decoded
72 * messages into {@link ProtocolDecoderOutput}.
73 *
74 * @return {@link #OK} if you finished decoding messages successfully.
75 * {@link #NEED_DATA} if you need more data to finish decoding current message.
76 * {@link #NOT_OK} if you cannot decode current message due to protocol specification violation.
77 *
78 * @throws ProtocolViolationException if the read data violated protocol
79 * specification
80 */
81 MessageDecoderResult decode( ProtocolSession session, ByteBuffer in,
82 ProtocolDecoderOutput out ) throws ProtocolViolationException;
83 }