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