001/** 002 * 003 * Copyright 2003-2007 Jive Software. 004 * 005 * Licensed under the Apache License, Version 2.0 (the "License"); 006 * you may not use this file except in compliance with the License. 007 * You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018package org.jivesoftware.smack; 019 020import org.jivesoftware.smack.SmackException.NotConnectedException; 021import org.jivesoftware.smack.packet.Stanza; 022 023/** 024 * Provides a mechanism to listen for packets that pass a specified filter. 025 * This allows event-style programming -- every time a new stanza(/packet) is found, 026 * the {@link #processPacket(Stanza)} method will be called. This is the 027 * opposite approach to the functionality provided by a {@link PacketCollector} 028 * which lets you block while waiting for results. 029 * <p> 030 * Additionally you are able to intercept Packets that are going to be send and 031 * make modifications to them. You can register a PacketListener as interceptor 032 * by using {@link XMPPConnection#addPacketInterceptor(StanzaListener, 033 * org.jivesoftware.smack.filter.StanzaFilter)} 034 * </p> 035 * 036 * @see XMPPConnection#addAsyncStanzaListener(StanzaListener, org.jivesoftware.smack.filter.StanzaFilter) 037 * @author Matt Tucker 038 */ 039public interface StanzaListener { 040 041 /** 042 * Process the next stanza(/packet) sent to this stanza(/packet) listener. 043 * <p> 044 * A single thread is responsible for invoking all listeners, so 045 * it's very important that implementations of this method not block 046 * for any extended period of time. 047 * </p> 048 * 049 * @param packet the stanza(/packet) to process. 050 */ 051 public void processPacket(Stanza packet) throws NotConnectedException; 052 053}