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.api.engine;
020
021import java.util.Collection;
022import java.util.List;
023
024import org.apache.wiki.WikiContext;
025import org.apache.wiki.api.exceptions.FilterException;
026import org.apache.wiki.api.filters.PageFilter;
027import org.apache.wiki.modules.WikiModuleInfo;
028
029public interface FilterManager
030{
031    /** Property name for setting the filter XML property file.  Value is <tt>{@value}</tt>. */
032    String PROP_FILTERXML = "jspwiki.filterConfig";
033    
034    /** Default location for the filter XML property file.  Value is <tt>{@value}</tt>. */
035    String DEFAULT_XMLFILE = "/WEB-INF/filters.xml";
036
037    /** JSPWiki system filters are all below this value. */
038    int SYSTEM_FILTER_PRIORITY = -1000;
039    
040    /** The standard user level filtering. */
041    int USER_FILTER_PRIORITY   = 0;
042    
043    /**
044     *  Adds a page filter to the queue.  The priority defines in which
045     *  order the page filters are run, the highest priority filters go
046     *  in the queue first.
047     *  <p>
048     *  In case two filters have the same priority, their execution order
049     *  is the insertion order.
050     *
051     *  @since 2.1.44.
052     *  @param f PageFilter to add
053     *  @param priority The priority in which position to add it in.
054     *  @throws IllegalArgumentException If the PageFilter is null or invalid.
055     */
056    void addPageFilter( PageFilter f, int priority ) throws IllegalArgumentException;
057    
058    /**
059     *  Does the filtering before a translation.
060     *  
061     *  @param context The WikiContext
062     *  @param pageData WikiMarkup data to be passed through the preTranslate chain.
063     *  @throws FilterException If any of the filters throws a FilterException
064     *  @return The modified WikiMarkup
065     *  
066     *  @see PageFilter#preTranslate(WikiContext, String)
067     */
068    String doPreTranslateFiltering( WikiContext context, String pageData ) throws FilterException;
069    
070    /**
071     *  Does the filtering after HTML translation.
072     *  
073     *  @param context The WikiContext
074     *  @param htmlData HTML data to be passed through the postTranslate
075     *  @throws FilterException If any of the filters throws a FilterException
076     *  @return The modified HTML
077     *  @see PageFilter#postTranslate(WikiContext, String)
078     */
079    String doPostTranslateFiltering( WikiContext context, String htmlData ) throws FilterException;
080    
081    /**
082     *  Does the filtering before a save to the page repository.
083     *  
084     *  @param context The WikiContext
085     *  @param pageData WikiMarkup data to be passed through the preSave chain.
086     *  @throws FilterException If any of the filters throws a FilterException
087     *  @return The modified WikiMarkup
088     *  @see PageFilter#preSave(WikiContext, String)
089     */
090    String doPreSaveFiltering( WikiContext context, String pageData ) throws FilterException;
091    
092    /**
093     *  Does the page filtering after the page has been saved.
094     * 
095     *  @param context The WikiContext
096     *  @param pageData WikiMarkup data to be passed through the postSave chain.
097     *  @throws FilterException If any of the filters throws a FilterException
098     * 
099     *  @see PageFilter#postSave(WikiContext, String)
100     */
101    void doPostSaveFiltering( WikiContext context, String pageData ) throws FilterException;
102    
103    /**
104     *  Returns the list of filters currently installed.  Note that this is not
105     *  a copy, but the actual list.  So be careful with it.
106     *  
107     *  @return A List of PageFilter objects
108     */
109    List< PageFilter > getFilterList();
110    
111    /**
112     * Notifies PageFilters to clean up their ressources.
113     */
114    void destroy();
115    
116    /**
117     * Returns a collection of modules currently managed by this ModuleManager.  Each
118     * entry is an instance of the {@link WikiModuleInfo} class.  This method should return something
119     * which is safe to iterate over, even if the underlying collection changes.
120     * 
121     * @return A Collection of {@link WikiModuleInfo} instances.
122     */
123    Collection< WikiModuleInfo > modules();
124    
125    /**
126     * Returns the {@link WikiModuleInfo} information about the provided filterName.
127     * @param filterName
128     * @return The WikiModuleInfo
129     */
130    WikiModuleInfo getModuleInfo(String filterName);
131}