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.filter; 019 020import org.jivesoftware.smack.packet.Stanza; 021 022/** 023 * Defines a way to filter stanzas for particular attributes. Stanza filters are used when 024 * constructing stanza listeners or collectors -- the filter defines what stanzas match the criteria 025 * of the collector or listener for further stanza processing. 026 * <p> 027 * Several simple filters are pre-defined. These filters can be logically combined for more complex 028 * stanza filtering by using the {@link org.jivesoftware.smack.filter.AndFilter AndFilter} and 029 * {@link org.jivesoftware.smack.filter.OrFilter OrFilter} filters. It's also possible to define 030 * your own filters by implementing this interface. The code example below creates a trivial filter 031 * for stanzas with a specific ID (real code should use {@link StanzaIdFilter} instead). 032 * 033 * <pre> 034 * // Use an anonymous inner class to define a stanza filter that returns 035 * // all stanzas that have a stanza ID of "RS145". 036 * StanzaFilter myFilter = new StanzaFilter() { 037 * public boolean accept(Stanza stanza) { 038 * return "RS145".equals(stanza.getStanzaId()); 039 * } 040 * }; 041 * // Create a new stanza collector using the filter we created. 042 * PacketCollector myCollector = connection.createPacketCollector(myFilter); 043 * </pre> 044 * 045 * @see org.jivesoftware.smack.PacketCollector 046 * @see org.jivesoftware.smack.StanzaListener 047 * @author Matt Tucker 048 */ 049public interface StanzaFilter { 050 051 /** 052 * Tests whether or not the specified stanza should pass the filter. 053 * 054 * @param stanza the stanza(/packet) to test. 055 * @return true if and only if <tt>stanza</tt> passes the filter. 056 */ 057 public boolean accept(Stanza stanza); 058}