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 */
019 package org.apache.wiki.api.engine;
020
021 import java.util.Collection;
022 import java.util.List;
023
024 import org.apache.wiki.WikiContext;
025 import org.apache.wiki.api.exceptions.FilterException;
026 import org.apache.wiki.api.filters.PageFilter;
027
028 public interface FilterManager
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(WikiContext, String)
066 */
067 String doPreTranslateFiltering( WikiContext 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(WikiContext, String)
077 */
078 String doPostTranslateFiltering( WikiContext 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(WikiContext, String)
088 */
089 String doPreSaveFiltering( WikiContext 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(WikiContext, String)
099 */
100 void doPostSaveFiltering( WikiContext 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 ressources.
112 */
113 void destroy();
114
115 /**
116 * Returns a collection of modules currently managed by this ModuleManager. Each
117 * entry is an instance of the WikiModuleInfo class. This method should return something
118 * which is safe to iterate over, even if the underlying collection changes.
119 *
120 * @return A Collection of WikiModuleInfo instances.
121 */
122 Collection modules();
123 }