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 * @author Trustin Lee (trustin@apache.org)
31 * @version $Rev: 210062 $, $Date: 2005-07-11 12:52:38 +0900 $
32 *
33 * @see DemuxingProtocolCodecFactory
34 * @see MessageDecoderFactory
35 */
36 public interface MessageDecoder {
37 /***
38 * Represents a result from {@link #decodable(ProtocolSession, ByteBuffer)} and
39 * {@link #decode(ProtocolSession, ByteBuffer, ProtocolDecoderOutput)}. Please
40 * refer to each method's documentation for detailed explanation.
41 */
42 static MessageDecoderResult OK = MessageDecoderResult.OK;
43
44 /***
45 * Represents a result from {@link #decodable(ProtocolSession, ByteBuffer)} and
46 * {@link #decode(ProtocolSession, ByteBuffer, ProtocolDecoderOutput)}. Please
47 * refer to each method's documentation for detailed explanation.
48 */
49 static MessageDecoderResult NEED_DATA = MessageDecoderResult.NEED_DATA;
50
51 /***
52 * Represents a result from {@link #decodable(ProtocolSession, ByteBuffer)} and
53 * {@link #decode(ProtocolSession, ByteBuffer, ProtocolDecoderOutput)}. Please
54 * refer to each method's documentation for detailed explanation.
55 */
56 static MessageDecoderResult NOT_OK = MessageDecoderResult.NOT_OK;
57
58 /***
59 * Checks the specified buffer is decodable by this decoder.
60 *
61 * @return {@link #OK} if this decoder can decode the specified buffer.
62 * {@link #NOT_OK} if this decoder cannot decode the specified buffer.
63 * {@link #NEED_DATA} if more data is required to determine if the
64 * specified buffer is decodable ({@link #OK}) or not decodable
65 * {@link #NOT_OK}.
66 */
67 MessageDecoderResult decodable( ProtocolSession session, ByteBuffer in );
68
69 /***
70 * Decodes binary or protocol-specific content into higher-level message objects.
71 * MINA invokes {@link #decode(ProtocolSession, ByteBuffer, ProtocolDecoderOutput)}
72 * method with read data, and then the decoder implementation puts decoded
73 * messages into {@link ProtocolDecoderOutput}.
74 *
75 * @return {@link #OK} if you finished decoding messages successfully.
76 * {@link #NEED_DATA} if you need more data to finish decoding current message.
77 * {@link #NOT_OK} if you cannot decode current message due to protocol specification violation.
78 *
79 * @throws ProtocolViolationException if the read data violated protocol
80 * specification
81 */
82 MessageDecoderResult decode( ProtocolSession session, ByteBuffer in,
83 ProtocolDecoderOutput out ) throws ProtocolViolationException;
84 }