View Javadoc

1   /*
2    *   @(#) $Id: MessageDecoder.java 357871 2005-12-20 01:56:40Z trustin $
3    *
4    *   Copyright 2004 The Apache Software Foundation
5    *
6    *   Licensed under the Apache License, Version 2.0 (the "License");
7    *   you may not use this file except in compliance with the License.
8    *   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, software
13   *   distributed under the License is distributed on an "AS IS" BASIS,
14   *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   *   See the License for the specific language governing permissions and
16   *   limitations under the License.
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  }