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;
21:
22: import org.apache.mina.common.IoBuffer;
23: import org.apache.mina.common.IoSession;
24:
25: /**
26: * Decodes binary or protocol-specific data into higher-level message objects.
27: * MINA invokes {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}
28: * method with read data, and then the decoder implementation puts decoded
29: * messages into {@link ProtocolDecoderOutput} by calling
30: * {@link ProtocolDecoderOutput#write(Object)}.
31: * <p>
32: * Please refer to
33: * <a href="../../../../../xref-examples/org/apache/mina/examples/reverser/TextLineDecoder.html"><code>TextLineDecoder</code></a>
34: * example.
35: *
36: * @author The Apache MINA Project (dev@mina.apache.org)
37: * @version $Rev: 591178 $, $Date: 2007-11-01 18:48:24 -0600 (Thu, 01 Nov 2007) $
38: *
39: * @see ProtocolDecoderException
40: */
41: public interface ProtocolDecoder {
42: /**
43: * Decodes binary or protocol-specific content into higher-level message objects.
44: * MINA invokes {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}
45: * method with read data, and then the decoder implementation puts decoded
46: * messages into {@link ProtocolDecoderOutput}.
47: *
48: * @throws Exception if the read data violated protocol specification
49: */
50: void decode(IoSession session, IoBuffer in,
51: ProtocolDecoderOutput out) throws Exception;
52:
53: /**
54: * Invoked when the specified <tt>session</tt> is closed. This method is useful
55: * when you deal with the protocol which doesn't specify the length of a message
56: * such as HTTP response without <tt>content-length</tt> header. Implement this
57: * method to process the remaining data that {@link #decode(IoSession, IoBuffer, ProtocolDecoderOutput)}
58: * method didn't process completely.
59: *
60: * @throws Exception if the read data violated protocol specification
61: */
62: void finishDecode(IoSession session, ProtocolDecoderOutput out)
63: throws Exception;
64:
65: /**
66: * Releases all resources related with this decoder.
67: *
68: * @throws Exception if failed to dispose all resources
69: */
70: void dispose(IoSession session) throws Exception;
71: }
|