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.handler.demux;
21  
22  import java.util.Collections;
23  import java.util.Map;
24  import java.util.Set;
25  import java.util.concurrent.ConcurrentHashMap;
26  
27  import org.apache.mina.core.service.IoHandler;
28  import org.apache.mina.core.service.IoHandlerAdapter;
29  import org.apache.mina.core.session.IoSession;
30  import org.apache.mina.core.session.UnknownMessageTypeException;
31  import org.apache.mina.util.IdentityHashSet;
32  
33  /**
34   * A {@link IoHandler} that demuxes <code>messageReceived</code> events
35   * to the appropriate {@link MessageHandler}.
36   * <p>
37   * You can freely register and deregister {@link MessageHandler}s using
38   * {@link #addReceivedMessageHandler(Class, MessageHandler)} and
39   * {@link #removeReceivedMessageHandler(Class)}.
40   * <p>
41   * When <code>message</code> is received through a call to
42   * {@link #messageReceived(IoSession, Object)} the class of the
43   * <code>message</code> object will be used to find a {@link MessageHandler} for
44   * that particular message type. If no {@link MessageHandler} instance can be
45   * found for the immediate class (i.e. <code>message.getClass()</code>) the
46   * interfaces implemented by the immediate class will be searched in depth-first
47   * order. If no match can be found for any of the interfaces the search will be
48   * repeated recursively for the superclass of the immediate class
49   * (i.e. <code>message.getClass().getSuperclass()</code>).
50   * <p>
51   * Consider the following type hierarchy (<code>Cx</code> are classes while
52   * <code>Ix</code> are interfaces):
53   * <pre>
54   *     C3 - I7 - I9
55   *      |    |   /\
56   *      |   I8  I3 I4
57   *      |
58   *     C2 - I5 - I6
59   *      |
60   *     C1 - I1 - I2 - I4
61   *      |         |
62   *      |        I3
63   *    Object
64   * </pre>
65   * When <code>message</code> is of type <code>C3</code> this hierarchy will be
66   * searched in the following order:
67   * <code>C3, I7, I8, I9, I3, I4, C2, I5, I6, C1, I1, I2, I3, I4, Object</code>.
68   * <p>
69   * For efficiency searches will be cached. Calls to
70   * {@link #addReceivedMessageHandler(Class, MessageHandler)} and
71   * {@link #removeReceivedMessageHandler(Class)} clear this cache.
72   *
73   * @author <a href="http://mina.apache.org">Apache MINA Project</a>
74   */
75  public class DemuxingIoHandler extends IoHandlerAdapter {
76  
77      private final Map<Class<?>, MessageHandler<?>> receivedMessageHandlerCache = new ConcurrentHashMap<Class<?>, MessageHandler<?>>();
78  
79      private final Map<Class<?>, MessageHandler<?>> receivedMessageHandlers = new ConcurrentHashMap<Class<?>, MessageHandler<?>>();
80  
81      private final Map<Class<?>, MessageHandler<?>> sentMessageHandlerCache = new ConcurrentHashMap<Class<?>, MessageHandler<?>>();
82  
83      private final Map<Class<?>, MessageHandler<?>> sentMessageHandlers = new ConcurrentHashMap<Class<?>, MessageHandler<?>>();
84  
85      private final Map<Class<?>, ExceptionHandler<?>> exceptionHandlerCache = new ConcurrentHashMap<Class<?>, ExceptionHandler<?>>();
86  
87      private final Map<Class<?>, ExceptionHandler<?>> exceptionHandlers = new ConcurrentHashMap<Class<?>, ExceptionHandler<?>>();
88  
89      /**
90       * Creates a new instance with no registered {@link MessageHandler}s.
91       */
92      public DemuxingIoHandler() {
93          // Do nothing
94      }
95  
96      /**
97       * Registers a {@link MessageHandler} that handles the received messages of
98       * the specified <code>type</code>.
99       * 
100      * @param <E> The message handler's type
101      * @param type The message's type
102      * @param handler The message handler
103      * @return the old handler if there is already a registered handler for
104      *         the specified <tt>type</tt>.  <tt>null</tt> otherwise.
105      */
106     @SuppressWarnings("unchecked")
107     public <E> MessageHandler<? super E> addReceivedMessageHandler(Class<E> type, MessageHandler<? super E> handler) {
108         receivedMessageHandlerCache.clear();
109         
110         return (MessageHandler<? super E>) receivedMessageHandlers.put(type, handler);
111     }
112 
113     /**
114      * Deregisters a {@link MessageHandler} that handles the received messages
115      * of the specified <code>type</code>.
116      *
117      * @param <E> The message handler's type
118      * @param type The message's type
119      * @return the removed handler if successfully removed.  <tt>null</tt> otherwise.
120      */
121     @SuppressWarnings("unchecked")
122     public <E> MessageHandler<? super E> removeReceivedMessageHandler(Class<E> type) {
123         receivedMessageHandlerCache.clear();
124         
125         return (MessageHandler<? super E>) receivedMessageHandlers.remove(type);
126     }
127 
128     /**
129      * Registers a {@link MessageHandler} that handles the sent messages of the
130      * specified <code>type</code>.
131      *
132      * @param <E> The message handler's type
133      * @param type The message's type
134      * @param handler The message handler
135      * @return the old handler if there is already a registered handler for
136      *         the specified <tt>type</tt>.  <tt>null</tt> otherwise.
137      */
138     @SuppressWarnings("unchecked")
139     public <E> MessageHandler<? super E> addSentMessageHandler(Class<E> type, MessageHandler<? super E> handler) {
140         sentMessageHandlerCache.clear();
141         
142         return (MessageHandler<? super E>) sentMessageHandlers.put(type, handler);
143     }
144 
145     /**
146      * Deregisters a {@link MessageHandler} that handles the sent messages of
147      * the specified <code>type</code>.
148      *
149      * @param <E> The message handler's type
150      * @param type The message's type
151      * @return the removed handler if successfully removed.  <tt>null</tt> otherwise.
152      */
153     @SuppressWarnings("unchecked")
154     public <E> MessageHandler<? super E> removeSentMessageHandler(Class<E> type) {
155         sentMessageHandlerCache.clear();
156         
157         return (MessageHandler<? super E>) sentMessageHandlers.remove(type);
158     }
159 
160     /**
161      * Registers a {@link MessageHandler} that receives the messages of
162      * the specified <code>type</code>.
163      *
164      * @param <E> The message handler's type
165      * @param type The message's type
166      * @param handler The Exception handler
167      * @return the old handler if there is already a registered handler for
168      *         the specified <tt>type</tt>.  <tt>null</tt> otherwise.
169      */
170     @SuppressWarnings("unchecked")
171     public <E extends Throwable> ExceptionHandler<? super E> addExceptionHandler(Class<E> type,
172             ExceptionHandler<? super E> handler) {
173         exceptionHandlerCache.clear();
174         
175         return (ExceptionHandler<? super E>) exceptionHandlers.put(type, handler);
176     }
177 
178     /**
179      * Deregisters a {@link MessageHandler} that receives the messages of
180      * the specified <code>type</code>.
181      *
182      * @param <E> The Exception Handler's type
183      * @param type The message's type
184      * @return the removed handler if successfully removed.  <tt>null</tt> otherwise.
185      */
186     @SuppressWarnings("unchecked")
187     public <E extends Throwable> ExceptionHandler<? super E> removeExceptionHandler(Class<E> type) {
188         exceptionHandlerCache.clear();
189         
190         return (ExceptionHandler<? super E>) exceptionHandlers.remove(type);
191     }
192 
193     /**
194      * @return the {@link MessageHandler} which is registered to process
195      * the specified <code>type</code>.
196      * @param <E> The message handler's type
197      * @param type The message's type
198      */
199     @SuppressWarnings("unchecked")
200     public <E> MessageHandler<? super E> getMessageHandler(Class<E> type) {
201         return (MessageHandler<? super E>) receivedMessageHandlers.get(type);
202     }
203 
204     /**
205      * @return the {@link Map} which contains all messageType-{@link MessageHandler}
206      * pairs registered to this handler for received messages.
207      */
208     public Map<Class<?>, MessageHandler<?>> getReceivedMessageHandlerMap() {
209         return Collections.unmodifiableMap(receivedMessageHandlers);
210     }
211 
212     /**
213      * @return the {@link Map} which contains all messageType-{@link MessageHandler}
214      * pairs registered to this handler for sent messages.
215      */
216     public Map<Class<?>, MessageHandler<?>> getSentMessageHandlerMap() {
217         return Collections.unmodifiableMap(sentMessageHandlers);
218     }
219 
220     /**
221      * @return the {@link Map} which contains all messageType-{@link MessageHandler}
222      * pairs registered to this handler.
223      */
224     public Map<Class<?>, ExceptionHandler<?>> getExceptionHandlerMap() {
225         return Collections.unmodifiableMap(exceptionHandlers);
226     }
227 
228     /**
229      * Forwards the received events into the appropriate {@link MessageHandler}
230      * which is registered by {@link #addReceivedMessageHandler(Class, MessageHandler)}.
231      * 
232      * <b>Warning !</b> If you are to overload this method, be aware that you 
233      * _must_ call the messageHandler in your own method, otherwise it won't 
234      * be called.
235      * 
236      * {@inheritDoc}
237      */
238     @Override
239     public void messageReceived(IoSession session, Object message) throws Exception {
240         MessageHandler<Object> handler = findReceivedMessageHandler(message.getClass());
241         
242         if (handler != null) {
243             handler.handleMessage(session, message);
244         } else {
245             throw new UnknownMessageTypeException("No message handler found for message type: "
246                     + message.getClass().getSimpleName());
247         }
248     }
249 
250     /**
251      * Invoked when a message written by IoSession.write(Object) is sent out.
252      * 
253      * <b>Warning !</b> If you are to overload this method, be aware that you 
254      * _must_ call the messageHandler in your own method, otherwise it won't 
255      * be called.
256      * 
257      * {@inheritDoc}
258      */
259     @Override
260     public void messageSent(IoSession session, Object message) throws Exception {
261         MessageHandler<Object> handler = findSentMessageHandler(message.getClass());
262         
263         if (handler != null) {
264             handler.handleMessage(session, message);
265         } else {
266             throw new UnknownMessageTypeException("No handler found for message type: "
267                     + message.getClass().getSimpleName());
268         }
269     }
270 
271     /**
272      * Invoked when any exception is thrown by user IoHandler implementation 
273      * or by MINA. If cause is an instance of IOException, MINA will close the 
274      * connection automatically.
275      *
276      * <b>Warning !</b> If you are to overload this method, be aware that you 
277      * _must_ call the messageHandler in your own method, otherwise it won't 
278      * be called.
279      * 
280      * {@inheritDoc}
281      */
282     @Override
283     public void exceptionCaught(IoSession session, Throwable cause) throws Exception {
284         ExceptionHandler<Throwable> handler = findExceptionHandler(cause.getClass());
285         
286         if (handler != null) {
287             handler.exceptionCaught(session, cause);
288         } else {
289             throw new UnknownMessageTypeException("No handler found for exception type: "
290                     + cause.getClass().getSimpleName());
291         }
292     }
293 
294     protected MessageHandler<Object> findReceivedMessageHandler(Class<?> type) {
295         return findReceivedMessageHandler(type, null);
296     }
297 
298     protected MessageHandler<Object> findSentMessageHandler(Class<?> type) {
299         return findSentMessageHandler(type, null);
300     }
301 
302     protected ExceptionHandler<Throwable> findExceptionHandler(Class<? extends Throwable> type) {
303         return findExceptionHandler(type, null);
304     }
305 
306     @SuppressWarnings("unchecked")
307     private MessageHandler<Object> findReceivedMessageHandler(Class<?> type, Set<Class<?>> triedClasses) {
308         return (MessageHandler<Object>) findHandler(receivedMessageHandlers, receivedMessageHandlerCache, type,
309                 triedClasses);
310     }
311 
312     @SuppressWarnings("unchecked")
313     private MessageHandler<Object> findSentMessageHandler(Class<?> type, Set<Class<?>> triedClasses) {
314         return (MessageHandler<Object>) findHandler(sentMessageHandlers, sentMessageHandlerCache, type, triedClasses);
315     }
316 
317     @SuppressWarnings("unchecked")
318     private ExceptionHandler<Throwable> findExceptionHandler(Class<?> type, Set<Class<?>> triedClasses) {
319         return (ExceptionHandler<Throwable>) findHandler(exceptionHandlers, exceptionHandlerCache, type, triedClasses);
320     }
321 
322     @SuppressWarnings("unchecked")
323     private Object findHandler(Map<Class<?>,?> handlers, Map handlerCache, Class<?> type, Set<Class<?>> triedClasses) {
324         if ((triedClasses != null) && (triedClasses.contains(type))) {
325             return null;
326         }
327 
328         /*
329          * Try the cache first.
330          */
331         Object handler = handlerCache.get(type);
332         
333         if (handler != null) {
334             return handler;
335         }
336 
337         /*
338          * Try the registered handlers for an immediate match.
339          */
340         handler = handlers.get(type);
341 
342         if (handler == null) {
343             /*
344              * No immediate match could be found. Search the type's interfaces.
345              */
346 
347             if (triedClasses == null) {
348                 triedClasses = new IdentityHashSet<Class<?>>();
349             }
350             
351             triedClasses.add(type);
352 
353             Class<?>[] interfaces = type.getInterfaces();
354             
355             for (Class<?> element : interfaces) {
356                 handler = findHandler(handlers, handlerCache, element, triedClasses);
357                 
358                 if (handler != null) {
359                     break;
360                 }
361             }
362         }
363 
364         if (handler == null) {
365             /*
366              * No match in type's interfaces could be found. Search the
367              * superclass.
368              */
369             Class<?> superclass = type.getSuperclass();
370             
371             if (superclass != null) {
372                 handler = findHandler(handlers, handlerCache, superclass, null);
373             }
374         }
375 
376         /*
377          * Make sure the handler is added to the cache. By updating the cache
378          * here all the types (superclasses and interfaces) in the path which
379          * led to a match will be cached along with the immediate message type.
380          */
381         if (handler != null) {
382             handlerCache.put(type, handler);
383         }
384 
385         return handler;
386     }
387 }