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.filters;
020
021import java.util.Properties;
022
023import org.apache.wiki.WikiContext;
024import org.apache.wiki.WikiEngine;
025import org.apache.wiki.api.exceptions.FilterException;
026
027/**
028 *  Provides a definition for a page filter.  A page filter is a class
029 *  that can be used to transform the WikiPage content being saved or
030 *  being loaded at any given time.
031 *  <p>
032 *  Note that the WikiContext.getPage() method always returns the context
033 *  in which text is rendered, i.e. the original request.  Thus the content
034 *  may actually be different content than what what the wikiContext.getPage()
035 *  implies!  This happens often if you are for example including multiple
036 *  pages on the same page.
037 *  <p>
038 *  PageFilters must be thread-safe!  There is only one instance of each PageFilter 
039 *  per each WikiEngine invocation.  If you need to store data persistently, use
040 *  VariableManager, or WikiContext.
041 *  <p>
042 *  As of 2.5.30, initialize() gains access to the WikiEngine.
043 *
044 */
045public interface PageFilter
046{
047    /**
048     *  Is called whenever the a new PageFilter is instantiated and
049     *  reset.
050     *  
051     *  @param engine The WikiEngine whic owns this PageFilter
052     *  @param properties The properties ripped from filters.xml.
053     *  @throws FilterException If the filter could not be initialized. If this is thrown,
054     *                          the filter is not added to the internal queues.
055     */
056    void initialize( WikiEngine engine, Properties properties )
057        throws FilterException;
058
059    /**
060     *  This method is called whenever a page has been loaded from the provider,
061     *  but not yet been sent through the markup-translation process.  Note that you cannot
062     *  do HTML translation here, because it will be escaped.
063     *
064     *  @param wikiContext The current wikicontext.
065     *  @param content     WikiMarkup.
066     *  @return The modified wikimarkup content.
067     *  @throws FilterException If something goes wrong.  Throwing this causes the entire page
068     *                          processing to be abandoned.
069     */
070    String preTranslate( WikiContext wikiContext, String content )
071        throws FilterException;
072
073    /**
074     *  This method is called after a page has been fed through the translation process,
075     *  so anything you are seeing here is translated content.  If you want to
076     *  do any of your own WikiMarkup2HTML translation, do it here.
077     *  
078     *  @param wikiContext The WikiContext.
079     *  @param htmlContent The translated HTML
080     *  @return The modified HTML
081     *  
082     *  @throws FilterException If something goes wrong.  Throwing this causes the entire page
083     *                          processing to be abandoned.
084     */
085    String postTranslate( WikiContext wikiContext, String htmlContent )
086        throws FilterException;
087
088    /**
089     *  This method is called before the page has been saved to the PageProvider.
090     *  
091     *  @param wikiContext The WikiContext
092     *  @param content The wikimarkup that the user just wanted to save.
093     *  @return The modified wikimarkup
094     *  @throws FilterException If something goes wrong.  Throwing this causes the entire page
095     *                          processing to be abandoned.
096     */
097    String preSave( WikiContext wikiContext, String content )
098        throws FilterException;
099
100    /**
101     *  This method is called after the page has been successfully saved.
102     *  If the saving fails for any reason, then this method will not
103     *  be called.
104     *  <p>
105     *  Since the result is discarded from this method, this is only useful
106     *  for things like counters, etc.
107     *  
108     *  @param wikiContext The WikiContext
109     *  @param content The content which was just stored.
110     *  @throws FilterException If something goes wrong.  As the page is already saved,
111     *                          This is just logged.
112     */
113    void postSave( WikiContext wikiContext, String content )
114        throws FilterException;
115
116    /**
117     *  Called for every filter, e.g. on wiki engine shutdown. Use this if you have to 
118     *  clean up or close global resources you allocated in the initialize() method.
119     * 
120     *  @param engine The WikiEngine which owns this filter.
121     *  @since 2.5.36
122     */
123    void destroy( WikiEngine engine );
124
125}