View Javadoc

1   /*
2    *   @(#) $Id: MessageDecoder.java 210062 2005-07-11 03:52:38Z 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   * @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  }