    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}