001/*
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  You may obtain a copy of the License at
009
010       http://www.apache.org/licenses/LICENSE-2.0
011
012    Unless required by applicable law or agreed to in writing,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.    
018 */
019package org.apache.wiki.filters;
020
021import org.apache.wiki.api.core.Context;
022import org.apache.wiki.api.exceptions.FilterException;
023import org.apache.wiki.api.filters.PageFilter;
024import org.apache.wiki.modules.ModuleManager;
025
026import java.util.List;
027
028public interface FilterManager extends ModuleManager {
029
030    /** Property name for setting the filter XML property file.  Value is <tt>{@value}</tt>. */
031    String PROP_FILTERXML = "jspwiki.filterConfig";
032    
033    /** Default location for the filter XML property file.  Value is <tt>{@value}</tt>. */
034    String DEFAULT_XMLFILE = "/WEB-INF/filters.xml";
035
036    /** JSPWiki system filters are all below this value. */
037    int SYSTEM_FILTER_PRIORITY = -1000;
038    
039    /** The standard user level filtering. */
040    int USER_FILTER_PRIORITY   = 0;
041    
042    /**
043     *  Adds a page filter to the queue.  The priority defines in which
044     *  order the page filters are run, the highest priority filters go
045     *  in the queue first.
046     *  <p>
047     *  In case two filters have the same priority, their execution order
048     *  is the insertion order.
049     *
050     *  @since 2.1.44.
051     *  @param f PageFilter to add
052     *  @param priority The priority in which position to add it in.
053     *  @throws IllegalArgumentException If the PageFilter is null or invalid.
054     */
055    void addPageFilter( PageFilter f, int priority ) throws IllegalArgumentException;
056    
057    /**
058     *  Does the filtering before a translation.
059     *  
060     *  @param context The WikiContext
061     *  @param pageData WikiMarkup data to be passed through the preTranslate chain.
062     *  @throws FilterException If any of the filters throws a FilterException
063     *  @return The modified WikiMarkup
064     *  
065     *  @see PageFilter#preTranslate(Context, String)
066     */
067    String doPreTranslateFiltering( Context context, String pageData ) throws FilterException;
068    
069    /**
070     *  Does the filtering after HTML translation.
071     *  
072     *  @param context The WikiContext
073     *  @param htmlData HTML data to be passed through the postTranslate
074     *  @throws FilterException If any of the filters throws a FilterException
075     *  @return The modified HTML
076     *  @see PageFilter#postTranslate(Context, String)
077     */
078    String doPostTranslateFiltering( Context context, String htmlData ) throws FilterException;
079    
080    /**
081     *  Does the filtering before a save to the page repository.
082     *  
083     *  @param context The WikiContext
084     *  @param pageData WikiMarkup data to be passed through the preSave chain.
085     *  @throws FilterException If any of the filters throws a FilterException
086     *  @return The modified WikiMarkup
087     *  @see PageFilter#preSave(Context, String)
088     */
089    String doPreSaveFiltering( Context context, String pageData ) throws FilterException;
090    
091    /**
092     *  Does the page filtering after the page has been saved.
093     * 
094     *  @param context The WikiContext
095     *  @param pageData WikiMarkup data to be passed through the postSave chain.
096     *  @throws FilterException If any of the filters throws a FilterException
097     * 
098     *  @see PageFilter#postSave(Context, String)
099     */
100    void doPostSaveFiltering( Context context, String pageData ) throws FilterException;
101    
102    /**
103     *  Returns the list of filters currently installed.  Note that this is not
104     *  a copy, but the actual list.  So be careful with it.
105     *  
106     *  @return A List of PageFilter objects
107     */
108    List< PageFilter > getFilterList();
109    
110    /**
111     * Notifies PageFilters to clean up their resources.
112     */
113    void destroy();
114
115}