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 }