Interface PacketInterceptor

  • All Known Implementing Classes:
    PacketCopier

    public interface PacketInterceptor
    A packet interceptor encapsulates an action that is invoked on a packet immediately before or after it was received by a SocketReader and also when the packet is about to be sent in SocketConnection. These types of actions fall into two broad categories:
    • Interceptors that reject the packet by throwing an exception (only when the packet has not been processed yet).
    • Interceptors that dynamically transform the packet content.
    Any number of interceptors can be installed and removed at run-time. They can be installed globally or per-user. Global interceptors are run first, followed by any that are installed for the username.

    Author:
    Gaston Dombiak
    See Also:
    InterceptorManager
    • Method Detail

      • interceptPacket

        void interceptPacket​(org.xmpp.packet.Packet packet,
                             Session session,
                             boolean incoming,
                             boolean processed)
                      throws PacketRejectedException
        Invokes the interceptor on the specified packet. The interceptor can either modify the packet, or throw a PacketRejectedException to block it from being sent or processed (when read).

        An exception can only be thrown when processed is false which means that the read packet has not been processed yet or the packet was not sent yet. If the exception is thrown with a "read" packet then the sender of the packet will receive an answer with an error. But if the exception is thrown with a "sent" packet then nothing will happen.

        Note that for each packet, every interceptor will be called twice: once before processing is complete (processing==true) and once after processing is complete. Typically, an interceptor will want to ignore one or the other case.

        Parameters:
        packet - the packet to take action on.
        session - the session that received or is sending the packet.
        incoming - flag that indicates if the packet was read by the server or sent from the server.
        processed - flag that indicates if the action (read/send) was performed. (PRE vs. POST).
        Throws:
        PacketRejectedException - if the packet should be prevented from being processed.