01: /**
02: * $RCSfile: PacketInterceptor.java,v $
03: * $Revision: 3010 $
04: * $Date: 2005-10-31 20:28:11 -0300 (Mon, 31 Oct 2005) $
05: *
06: * Copyright (C) 2007 Jive Software. All rights reserved.
07: *
08: * This software is published under the terms of the GNU Public License (GPL),
09: * a copy of which is included in this distribution.
10: */package org.jivesoftware.openfire.interceptor;
11:
12: import org.jivesoftware.openfire.session.Session;
13: import org.xmpp.packet.Packet;
14:
15: /**
16: * A packet interceptor encapsulates an action that is invoked on a packet immediately
17: * before or after it was received by a SocketReader and also when the packet is about to
18: * be sent in SocketConnection. These types of actions fall into two broad categories:<ul>
19: * <li> Interceptors that reject the packet by throwing an exception (only when the packet
20: * has not been processed yet).
21: * <li> Interceptors that dynamically transform the packet content.
22: * </ul>
23: *
24: * Any number of interceptors can be installed and removed at run-time. They can be installed
25: * globally or per-user. Global interceptors are run first, followed by any that are installed
26: * for the username.<p>
27: *
28: * @see InterceptorManager
29: * @author Gaston Dombiak
30: */
31: public interface PacketInterceptor {
32:
33: /**
34: * Invokes the interceptor on the specified packet. The interceptor can either modify
35: * the packet, or throw a PacketRejectedException to block it from being sent or processed
36: * (when read).<p>
37: *
38: * An exception can only be thrown when <tt>processed</tt> is false which means that the read
39: * packet has not been processed yet or the packet was not sent yet. If the exception is thrown
40: * with a "read" packet then the sender of the packet will receive an answer with an error. But
41: * if the exception is thrown with a "sent" packet then nothing will happen.<p>
42: *
43: * Note that for each packet, every interceptor will be called twice: once before processing
44: * is complete (<tt>processing==true</tt>) and once after processing is complete. Typically,
45: * an interceptor will want to ignore one or the other case.
46: *
47: * @param packet the packet to take action on.
48: * @param session the session that received or is sending the packet.
49: * @param incoming flag that indicates if the packet was read by the server or sent from
50: * the server.
51: * @param processed flag that indicates if the action (read/send) was performed. (PRE vs. POST).
52: * @throws PacketRejectedException if the packet should be prevented from being processed.
53: */
54: void interceptPacket(Packet packet, Session session,
55: boolean incoming, boolean processed)
56: throws PacketRejectedException;
57: }
|