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.ProtocolDecoder;
    25  import org.apache.mina.codec.StatelessProtocolEncoder;
    26
    27  /**
    28   * Abstract class providing both encoding and decoding methods between a given
    29   * type and ByteBuffers.
    30   *
    31   * <p>
    32   * Transcoder is stateless class providing encoding and decoding facilities.
    33   * Additionally this abstract requires two methods which allows to determine the
    34   * size of a given message and to write it directly to a previously allocated
    35   * ByteBuffer.
    36   * </p>
    37   *
    38   * @param <INPUT>
    39   *            the type of the messages which will be encoded in ByteBuffers and
    40   *            decoded from ByteBuffers.
    41   *
    42   * @author <a href="http://mina.apache.org">Apache MINA Project</a>
    43   */
    44  public abstract class ByteBufferEncoder<INPUT> implements StatelessProtocolEncoder<INPUT, ByteBuffer> {
    45
    46      /**
    47       * Being stateless, this method is left empty
    48       *
    49       * @see ProtocolDecoder#createDecoderState()
    50       */
    51      @Override
    52      public final Void createEncoderState() {
    53          // stateless !
    54          return null;
    55      }
    56
    57      /**
    58       * Encodes a message to a {@link ByteBuffer}
    59       *
    60       * @param message
    61       *            a message to be encoded
    62       * @return the buffer containing {@link ByteBuffer} representation of the
    63       *         message
    64       */
    65      public ByteBuffer encode(INPUT message) {
    66          ByteBuffer buffer = ByteBuffer.allocate(getEncodedSize(message));
    67          int oldPos = buffer.position();
    68          writeTo(message, buffer);
    69          buffer.position(oldPos);
    70          return buffer;
    71      }
    72
    73      /**
    74       * Encodes a message to a {@link ByteBuffer}
    75       * <p>
    76       * The actual encoding needs to be implemented in the abstract method
    77       * {@link ByteBufferEncoder#encode(Object)}
    78       * </p>
    79       */
    80
    81      @Override
    82      public final ByteBuffer encode(INPUT message, Void context) {
    83          return encode(message);
    84      }
    85
    86      /**
    87       *
    88       * Computes the size of the serialized form of a message in bytes.
    89       *
    90       * @param message
    91       *            a message to be encoded
    92       * @return the size of the serialized form of the message
    93       */
    94      public abstract int getEncodedSize(INPUT message);
    95
    96      /**
    97       * Writes a message on a {@link ByteBuffer}.
    98       *
    99       * <p>
    100      * n.b. The buffer is expected to have at least a sufficient capacity to
    101      * handle the serialized form of the message.
    102      * </p>
    103      *
    104      * @param message
    105      *            a message to be encoded
    106      * @param buffer
    107      *            a target {@link ByteBuffer}
    108      */
    109     public abstract void writeTo(INPUT message, ByteBuffer buffer);
    110
    111 }