001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  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 */
017package org.apache.wicket.markup.parser;
018
019import java.text.ParseException;
020
021import org.apache.wicket.markup.Markup;
022import org.apache.wicket.markup.MarkupElement;
023
024
025/**
026 * Wicket uses a streaming XML parser to read the markup. A chain of IMarkupFilters is used e.g. to
027 * remove comments, allow for html typical markup (some tags don't need to be closed explicitly),
028 * etc.
029 * 
030 * @see org.apache.wicket.markup.MarkupParser
031 * @see org.apache.wicket.markup.MarkupFactory
032 * 
033 * @author Juergen Donnerstag
034 */
035public interface IMarkupFilter
036{
037        /**
038         * IMarkupFilters are usually chained with the last filter retrieving the elements from the XML
039         * parser.
040         * 
041         * @return The next filter in the chain, or null if the last one.
042         */
043        IMarkupFilter getNextFilter();
044
045        /**
046         * Set parent filter.
047         * 
048         * @param parent
049         *            The next element in the chain
050         */
051        void setNextFilter(final IMarkupFilter parent);
052
053        /**
054         * Get the next MarkupElement from the parent MarkupFilter and handle it if the specific filter
055         * criteria are met. Depending on the filter, it may return the MarkupElement unchanged,
056         * modified or remove it by asking the parent handler for the next tag.
057         * 
058         * @return Return the next eligible MarkupElement. Null, if no more found.
059         * @throws ParseException
060         */
061        MarkupElement nextElement() throws ParseException;
062
063        /**
064         * Called after all filters have been processed.
065         * 
066         * @param markup
067         */
068        void postProcess(final Markup markup);
069}