View Javadoc

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.codec.delimited;
21  
22  import java.nio.ByteBuffer;
23  
24  import org.apache.mina.codec.IoBuffer;
25  import org.apache.mina.codec.ProtocolDecoder;
26  import org.apache.mina.codec.ProtocolDecoderException;
27  import org.apache.mina.codec.StatelessProtocolDecoder;
28  import org.apache.mina.codec.delimited.ints.RawInt32;
29  import org.apache.mina.codec.delimited.ints.VarInt;
30  
31  /**
32   * Abstract class providing both encoding and decoding methods between a given
33   * type and ByteBuffers.
34   * 
35   * <p>
36   * Transcoder is stateless class providing encoding and decoding facilities.
37   * Additionally this abstract requires two methods which allows to determine the
38   * size of a given message and to write it directly to a previously allocated
39   * ByteBuffer.
40   * </p>
41   * 
42   * @param <INPUT>
43   *            the type of the messages which will be encoded in ByteBuffers and
44   *            decoded from ByteBuffers.
45   * 
46   * @author <a href="http://mina.apache.org">Apache MINA Project</a>
47   */
48  public abstract class IoBufferDecoder<INPUT> implements StatelessProtocolDecoder<IoBuffer, INPUT> {
49      /**
50       * Being stateless, this method is left empty
51       * 
52       * @see ProtocolDecoder#createDecoderState()
53       */
54      @Override
55      public final Void createDecoderState() {
56          // stateless !
57          return null;
58      }
59  
60      /**
61       * Decodes a message from a {@link IoBuffer}
62       * 
63       * <p>
64       * When a truncated input is given to this method it <b>may</b> return null.
65       * Not all decoder will be able to detect this issue and report it that way.
66       * Thanks to prefixing of messages, decoder will only receive appropriately
67       * sized ByteBuffers.
68       * </p>
69       * 
70       * <p>
71       * n.b. The decoders used for the prefixing (i.e. {@link RawInt32} and
72       * {@link VarInt}) <b>have</b> to detect truncated ByteBuffers.
73       * </p>
74       * 
75       * @param input
76       *            data to be decoded as a TYPE message
77       * @return the decoded message on success, null otherwise
78       * 
79       * @throws ProtocolDecoderException
80       */
81      public abstract INPUT decode(IoBuffer input);
82  
83      /**
84       * Decodes a message from a {@link ByteBuffer}
85       * <p>
86       * The actual decoding needs to be implemented in the abstract method
87       * {@link IoBufferDecoder#decode(ByteBuffer)}
88       * </p>
89       */
90      @Override
91      public final INPUT decode(IoBuffer input, Void context) {
92          return decode(input);
93      }
94  
95      /**
96       * Being stateless, this method is left empty
97       * 
98       * @see ProtocolDecoder#finishDecode(Object)
99       */
100     @Override
101     public final void finishDecode(Void context) {
102         // stateless !
103     }
104 
105 }