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.common.ByteBuffer;
23 import org.apache.mina.common.IoSession;
24 import org.apache.mina.filter.codec.ProtocolDecoderOutput;
25
26 /**
27 * Decodes specific messages.
28 *
29 * @author The Apache Directory Project (mina-dev@directory.apache.org)
30 * @version $Rev: 555855 $, $Date: 2007-07-13 12:19:00 +0900 (Fri, 13 Jul 2007) $
31 *
32 * @see DemuxingProtocolCodecFactory
33 * @see MessageDecoderFactory
34 */
35 public interface MessageDecoder {
36 /**
37 * Represents a result from {@link #decodable(IoSession, ByteBuffer)} and
38 * {@link #decode(IoSession, 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(IoSession, ByteBuffer)} and
45 * {@link #decode(IoSession, 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(IoSession, ByteBuffer)} and
52 * {@link #decode(IoSession, 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(IoSession session, ByteBuffer in);
67
68 /**
69 * Decodes binary or protocol-specific content into higher-level message objects.
70 * MINA invokes {@link #decode(IoSession, 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 Exception if the read data violated protocol specification
79 */
80 MessageDecoderResult decode(IoSession session, ByteBuffer in,
81 ProtocolDecoderOutput out) throws Exception;
82
83 /**
84 * Invoked when the specified <tt>session</tt> is closed while this decoder was
85 * parsing the data. This method is useful when you deal with the protocol which doesn't
86 * specify the length of a message such as HTTP response without <tt>content-length</tt>
87 * header. Implement this method to process the remaining data that
88 * {@link #decode(IoSession, ByteBuffer, ProtocolDecoderOutput)} method didn't process
89 * completely.
90 *
91 * @throws Exception if the read data violated protocol specification
92 */
93 void finishDecode(IoSession session, ProtocolDecoderOutput out)
94 throws Exception;
95 }