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 }