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.SmackException.NotLoggedInException; 022import org.jivesoftware.smack.packet.Stanza; 023 024/** 025 * Provides a mechanism to listen for packets that pass a specified filter. 026 * This allows event-style programming -- every time a new stanza is found, 027 * the {@link #processStanza(Stanza)} method will be called. This is the 028 * opposite approach to the functionality provided by a {@link StanzaCollector} 029 * which lets you block while waiting for results. 030 * <p> 031 * Additionally you are able to intercept Packets that are going to be send and 032 * make modifications to them. You can register a PacketListener as interceptor 033 * by using {@link XMPPConnection#addStanzaInterceptor(StanzaListener, 034 * org.jivesoftware.smack.filter.StanzaFilter)} 035 * </p> 036 * 037 * @see XMPPConnection#addAsyncStanzaListener(StanzaListener, org.jivesoftware.smack.filter.StanzaFilter) 038 * @author Matt Tucker 039 */ 040public interface StanzaListener { 041 042 /** 043 * Process the next stanza sent to this stanza listener. 044 * <p> 045 * If this listener is synchronous, then a single thread is responsible for invoking all listeners, so 046 * it's very important that implementations of this method not block 047 * for any extended period of time. 048 * </p> 049 * 050 * @param packet the stanza to process. 051 * @throws NotConnectedException if the XMPP connection is not connected. 052 * @throws InterruptedException if the calling thread was interrupted. 053 * @throws NotLoggedInException if the XMPP connection is not authenticated. 054 */ 055 void processStanza(Stanza packet) throws NotConnectedException, InterruptedException, NotLoggedInException; 056 057}