01: /*
02: * Licensed to the Apache Software Foundation (ASF) under one
03: * or more contributor license agreements. See the NOTICE file
04: * distributed with this work for additional information
05: * regarding copyright ownership. The ASF licenses this file
06: * to you under the Apache License, Version 2.0 (the
07: * "License"); you may not use this file except in compliance
08: * with the License. You may obtain a copy of the License at
09: *
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.IoBuffer;
23: import org.apache.mina.common.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: 590006 $, $Date: 2007-10-30 03:44:02 -0600 (Tue, 30 Oct 2007) $
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: }
|