View Javadoc
1   /*
2    * Copyright 2012 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License,
5    * version 2.0 (the "License"); you may not use this file except in compliance
6    * with the License. You may obtain a copy of the License at:
7    *
8    *   https://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations
14   * under the License.
15   */
16  package io.netty5.handler.codec;
17  
18  import io.netty5.channel.ChannelHandlerAdapter;
19  import io.netty5.channel.ChannelHandlerContext;
20  import io.netty5.util.ReferenceCounted;
21  import io.netty5.util.concurrent.Future;
22  import io.netty5.util.internal.TypeParameterMatcher;
23  
24  import java.util.List;
25  
26  import static io.netty5.util.internal.SilentDispose.autoClosing;
27  
28  /**
29   * A Codec for on-the-fly encoding/decoding of message.
30   *
31   * This can be thought of as a combination of {@link MessageToMessageDecoder} and {@link MessageToMessageEncoder}.
32   *
33   * Here is an example of a {@link MessageToMessageCodec} which just decode from {@link Integer} to {@link Long}
34   * and encode from {@link Long} to {@link Integer}.
35   *
36   * <pre>
37   *     public class NumberCodec extends
38   *             {@link MessageToMessageCodec}&lt;{@link Integer}, {@link Long}&gt; {
39   *         {@code @Override}
40   *         public {@link Long} decode({@link ChannelHandlerContext} ctx, {@link Integer} msg, List&lt;Object&gt; out)
41   *                 throws {@link Exception} {
42   *             out.add(msg.longValue());
43   *         }
44   *
45   *         {@code @Override}
46   *         public {@link Integer} encode({@link ChannelHandlerContext} ctx, {@link Long} msg, List&lt;Object&gt; out)
47   *                 throws {@link Exception} {
48   *             out.add(msg.intValue());
49   *         }
50   *     }
51   * </pre>
52   *
53   * Be aware that you need to call {@link ReferenceCounted#retain()} on messages that are just passed through if they
54   * are of type {@link ReferenceCounted}. This is needed as the {@link MessageToMessageCodec} will call
55   * {@link ReferenceCounted#release()} on encoded / decoded messages.
56   */
57  public abstract class MessageToMessageCodec<INBOUND_IN, OUTBOUND_IN> extends ChannelHandlerAdapter {
58  
59      private final MessageToMessageEncoder<Object> encoder = new MessageToMessageEncoder<>() {
60  
61          @Override
62          public boolean acceptOutboundMessage(Object msg) throws Exception {
63              return MessageToMessageCodec.this.acceptOutboundMessage(msg);
64          }
65  
66          @Override
67          @SuppressWarnings("unchecked")
68          protected void encodeAndClose(ChannelHandlerContext ctx, Object msg, List<Object> out) throws Exception {
69              MessageToMessageCodec.this.encodeAndClose(ctx, (OUTBOUND_IN) msg, out);
70          }
71      };
72  
73      private final MessageToMessageDecoder<Object> decoder = new MessageToMessageDecoder<>() {
74  
75          @Override
76          public boolean acceptInboundMessage(Object msg) throws Exception {
77              return MessageToMessageCodec.this.acceptInboundMessage(msg);
78          }
79  
80          @Override
81          @SuppressWarnings("unchecked")
82          protected void decodeAndClose(ChannelHandlerContext ctx, Object msg) throws Exception {
83              MessageToMessageCodec.this.decodeAndClose(ctx, (INBOUND_IN) msg);
84          }
85      };
86  
87      private final TypeParameterMatcher inboundMsgMatcher;
88      private final TypeParameterMatcher outboundMsgMatcher;
89  
90      /**
91       * Create a new instance which will try to detect the types to decode and encode out of the type parameter
92       * of the class.
93       */
94      protected MessageToMessageCodec() {
95          inboundMsgMatcher = TypeParameterMatcher.find(this, MessageToMessageCodec.class, "INBOUND_IN");
96          outboundMsgMatcher = TypeParameterMatcher.find(this, MessageToMessageCodec.class, "OUTBOUND_IN");
97      }
98  
99      /**
100      * Create a new instance.
101      *
102      * @param inboundMessageType    The type of messages to decode
103      * @param outboundMessageType   The type of messages to encode
104      */
105     protected MessageToMessageCodec(
106             Class<? extends INBOUND_IN> inboundMessageType, Class<? extends OUTBOUND_IN> outboundMessageType) {
107         inboundMsgMatcher = TypeParameterMatcher.get(inboundMessageType);
108         outboundMsgMatcher = TypeParameterMatcher.get(outboundMessageType);
109     }
110 
111     @Override
112     public void channelRead(ChannelHandlerContext ctx, Object msg) throws Exception {
113         decoder.channelRead(ctx, msg);
114     }
115 
116     @Override
117     public Future<Void> write(ChannelHandlerContext ctx, Object msg) {
118         return encoder.write(ctx, msg);
119     }
120 
121     /**
122      * Returns {@code true} if and only if the specified message can be decoded by this codec.
123      *
124      * @param msg the message
125      */
126     public boolean acceptInboundMessage(Object msg) throws Exception {
127         return inboundMsgMatcher.match(msg);
128     }
129 
130     /**
131      * Returns {@code true} if and only if the specified message can be encoded by this codec.
132      *
133      * @param msg the message
134      */
135     public boolean acceptOutboundMessage(Object msg) throws Exception {
136         return outboundMsgMatcher.match(msg);
137     }
138 
139     /**
140      * @see MessageToMessageEncoder#encode(ChannelHandlerContext, Object, List)
141      */
142     protected void encode(ChannelHandlerContext ctx, OUTBOUND_IN msg, List<Object> out)
143             throws Exception {
144         throw new CodecException(getClass().getName() + " must override either encode() or encodeAndClose().");
145     }
146 
147     /**
148      * @see MessageToMessageEncoder#encodeAndClose(ChannelHandlerContext, Object, List)
149      */
150     protected void encodeAndClose(ChannelHandlerContext ctx, OUTBOUND_IN msg, List<Object> out) throws Exception {
151         try (AutoCloseable ignore = autoClosing(msg)) {
152             encode(ctx, msg, out);
153         }
154     }
155 
156     /**
157      * @see MessageToMessageDecoder#decode(ChannelHandlerContext, Object)
158      */
159     protected void decode(ChannelHandlerContext ctx, INBOUND_IN msg) throws Exception {
160         throw new CodecException(getClass().getName() + " must override either decode() or decodeAndClose().");
161     }
162 
163     /**
164      * @see MessageToMessageDecoder#decodeAndClose(ChannelHandlerContext, Object)
165      */
166     protected void decodeAndClose(ChannelHandlerContext ctx, INBOUND_IN msg) throws Exception {
167         try (AutoCloseable ignore = autoClosing(msg)) {
168             decode(ctx, msg);
169         }
170     }
171 }