Author: juanpablo
Date: Wed Dec 26 22:14:50 2012
New Revision: 1426046
URL: http://svn.apache.org/viewvc?rev=1426046&view=rev
Log:
Initial Filters API (api.filters)
api.exceptions
-> org.apache.wiki.api.exceptions.WikiException, extends original
org.apache.wiki.WikiException
-> new api.exceptions.FilterException and api.exceptions.RedirectException
-> all api.exceptions.* extend from api.exceptions.WikiException
Added:
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/FilterException.java
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/RedirectException.java
incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/
incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/BasicPageFilter.java
incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/FilterManager.java
incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/PageFilter.java
Modified:
incubator/jspwiki/trunk/src/org/apache/wiki/WikiException.java
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/PluginException.java
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/WikiException.java
Modified: incubator/jspwiki/trunk/src/org/apache/wiki/WikiException.java
URL:
http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/wiki/WikiException.java?rev=1426046&r1=1426045&r2=1426046&view=diff
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/wiki/WikiException.java (original)
+++ incubator/jspwiki/trunk/src/org/apache/wiki/WikiException.java Wed Dec 26
22:14:50 2012
@@ -24,7 +24,7 @@ package org.apache.wiki;
* @since 2.0
*/
public class WikiException
- extends org.apache.wiki.api.exceptions.WikiException
+ extends Exception
{
private static final long serialVersionUID = 3257290231723210803L;
Added:
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/FilterException.java
URL:
http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/FilterException.java?rev=1426046&view=auto
==============================================================================
---
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/FilterException.java
(added)
+++
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/FilterException.java
Wed Dec 26 22:14:50 2012
@@ -0,0 +1,43 @@
+/*
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ */
+package org.apache.wiki.api.exceptions;
+
+import org.apache.wiki.WikiException;
+
+/**
+ * A generic PageFilter exception.
+ *
+ * @since 2.1.112
+ */
+public class FilterException
+ extends WikiException
+{
+
+ private static final long serialVersionUID = -490652869936406653L;
+
+ /**
+ * Constructs an exception.
+ *
+ * @param msg {@inheritDoc}
+ */
+ public FilterException( String msg )
+ {
+ super( msg );
+ }
+}
Modified:
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/PluginException.java
URL:
http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/PluginException.java?rev=1426046&r1=1426045&r2=1426046&view=diff
==============================================================================
---
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/PluginException.java
(original)
+++
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/PluginException.java
Wed Dec 26 22:14:50 2012
@@ -18,8 +18,6 @@
*/
package org.apache.wiki.api.exceptions;
-import org.apache.wiki.WikiException;
-
/**
* Provides a generic PluginException. This is the kind of
Added:
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/RedirectException.java
URL:
http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/RedirectException.java?rev=1426046&view=auto
==============================================================================
---
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/RedirectException.java
(added)
+++
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/RedirectException.java
Wed Dec 26 22:14:50 2012
@@ -0,0 +1,56 @@
+/*
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ */
+package org.apache.wiki.api.exceptions;
+
+/**
+ * This exception may be thrown if a filter wants to reject something and
+ * redirect the user elsewhere.
+ *
+ * @since 2.1.112
+ */
+public class RedirectException
+ extends FilterException
+{
+ private static final long serialVersionUID = 6626993875873941172L;
+
+ private final String m_where;
+
+ /**
+ * Constructs a new RedirectException.
+ *
+ * @param msg The message for the exception
+ * @param redirect The redirect URI.
+ */
+ public RedirectException( String msg, String redirect )
+ {
+ super( msg );
+
+ m_where = redirect;
+ }
+
+ /**
+ * Get the URI for redirection.
+ *
+ * @return The URI given in the constructor.
+ */
+ public String getRedirect()
+ {
+ return m_where;
+ }
+}
Modified:
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/WikiException.java
URL:
http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/WikiException.java?rev=1426046&r1=1426045&r2=1426046&view=diff
==============================================================================
---
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/WikiException.java
(original)
+++
incubator/jspwiki/trunk/src/org/apache/wiki/api/exceptions/WikiException.java
Wed Dec 26 22:14:50 2012
@@ -24,7 +24,7 @@ package org.apache.wiki.api.exceptions;
* @since 2.0
*/
public class WikiException
- extends Exception
+ extends org.apache.wiki.WikiException
{
private static final long serialVersionUID = 3257290231723210803L;
Added:
incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/BasicPageFilter.java
URL:
http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/BasicPageFilter.java?rev=1426046&view=auto
==============================================================================
---
incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/BasicPageFilter.java
(added)
+++
incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/BasicPageFilter.java
Wed Dec 26 22:14:50 2012
@@ -0,0 +1,90 @@
+/*
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ */
+package org.apache.wiki.api.filters;
+
+import java.util.Properties;
+
+import org.apache.wiki.WikiContext;
+import org.apache.wiki.WikiEngine;
+import org.apache.wiki.api.exceptions.FilterException;
+
+/**
+ * Provides a base implementation of a PageFilter. None of the callbacks
+ * do anything, so it is a good idea for you to extend from this class
+ * and implement only methods that you need.
+ *
+ */
+public class BasicPageFilter
+ implements PageFilter
+{
+ protected WikiEngine m_engine;
+
+ /**
+ * If you override this, you should call super.initialize() first.
+ *
+ * {@inheritDoc}
+ */
+ public void initialize( WikiEngine engine, Properties properties )
+ throws FilterException
+ {
+ m_engine = engine;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public String preTranslate( WikiContext wikiContext, String content )
+ throws FilterException
+ {
+ return content;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public String postTranslate( WikiContext wikiContext, String htmlContent )
+ throws FilterException
+ {
+ return htmlContent;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public String preSave( WikiContext wikiContext, String content )
+ throws FilterException
+ {
+ return content;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public void postSave( WikiContext wikiContext, String content )
+ throws FilterException
+ {
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public void destroy( WikiEngine engine )
+ {
+ }
+}
Added:
incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/FilterManager.java
URL:
http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/FilterManager.java?rev=1426046&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/FilterManager.java
(added)
+++ incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/FilterManager.java
Wed Dec 26 22:14:50 2012
@@ -0,0 +1,104 @@
+package org.apache.wiki.api.filters;
+
+import java.util.Collection;
+import java.util.List;
+
+import org.apache.wiki.WikiContext;
+import org.apache.wiki.api.exceptions.FilterException;
+
+public interface FilterManager
+{
+ /** Property name for setting the filter XML property file. Value is
<tt>{@value}</tt>. */
+ static final String PROP_FILTERXML = "jspwiki.filterConfig";
+
+ /** Default location for the filter XML property file. Value is
<tt>{@value}</tt>. */
+ static final String DEFAULT_XMLFILE = "/WEB-INF/filters.xml";
+
+ /** JSPWiki system filters are all below this value. */
+ static final int SYSTEM_FILTER_PRIORITY = -1000;
+
+ /** The standard user level filtering. */
+ static final int USER_FILTER_PRIORITY = 0;
+
+ /**
+ * Adds a page filter to the queue. The priority defines in which
+ * order the page filters are run, the highest priority filters go
+ * in the queue first.
+ * <p>
+ * In case two filters have the same priority, their execution order
+ * is the insertion order.
+ *
+ * @since 2.1.44.
+ * @param f PageFilter to add
+ * @param priority The priority in which position to add it in.
+ * @throws IllegalArgumentException If the PageFilter is null or invalid.
+ */
+ void addPageFilter( PageFilter f, int priority ) throws
IllegalArgumentException;
+
+ /**
+ * Does the filtering before a translation.
+ *
+ * @param context The WikiContext
+ * @param pageData WikiMarkup data to be passed through the preTranslate
chain.
+ * @throws FilterException If any of the filters throws a FilterException
+ * @return The modified WikiMarkup
+ *
+ * @see PageFilter#preTranslate(WikiContext, String)
+ */
+ String doPreTranslateFiltering( WikiContext context, String pageData )
throws FilterException;
+
+ /**
+ * Does the filtering after HTML translation.
+ *
+ * @param context The WikiContext
+ * @param htmlData HTML data to be passed through the postTranslate
+ * @throws FilterException If any of the filters throws a FilterException
+ * @return The modified HTML
+ * @see PageFilter#postTranslate(WikiContext, String)
+ */
+ String doPostTranslateFiltering( WikiContext context, String htmlData )
throws FilterException;
+
+ /**
+ * Does the filtering before a save to the page repository.
+ *
+ * @param context The WikiContext
+ * @param pageData WikiMarkup data to be passed through the preSave chain.
+ * @throws FilterException If any of the filters throws a FilterException
+ * @return The modified WikiMarkup
+ * @see PageFilter#preSave(WikiContext, String)
+ */
+ String doPreSaveFiltering( WikiContext context, String pageData ) throws
FilterException;
+
+ /**
+ * Does the page filtering after the page has been saved.
+ *
+ * @param context The WikiContext
+ * @param pageData WikiMarkup data to be passed through the postSave
chain.
+ * @throws FilterException If any of the filters throws a FilterException
+ *
+ * @see PageFilter#postSave(WikiContext, String)
+ */
+ void doPostSaveFiltering( WikiContext context, String pageData ) throws
FilterException;
+
+ /**
+ * Returns the list of filters currently installed. Note that this is not
+ * a copy, but the actual list. So be careful with it.
+ *
+ * @return A List of PageFilter objects
+ */
+ List< PageFilter > getFilterList();
+
+ /**
+ * Notifies PageFilters to clean up their ressources.
+ */
+ void destroy();
+
+ /**
+ * Returns a collection of modules currently managed by this
ModuleManager. Each
+ * entry is an instance of the WikiModuleInfo class. This method should
return something
+ * which is safe to iterate over, even if the underlying collection
changes.
+ *
+ * @return A Collection of WikiModuleInfo instances.
+ */
+ Collection modules();
+}
Added: incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/PageFilter.java
URL:
http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/PageFilter.java?rev=1426046&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/PageFilter.java
(added)
+++ incubator/jspwiki/trunk/src/org/apache/wiki/api/filters/PageFilter.java Wed
Dec 26 22:14:50 2012
@@ -0,0 +1,125 @@
+/*
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ */
+package org.apache.wiki.api.filters;
+
+import java.util.Properties;
+
+import org.apache.wiki.WikiContext;
+import org.apache.wiki.WikiEngine;
+import org.apache.wiki.api.exceptions.FilterException;
+
+/**
+ * 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
+ * being loaded at any given time.
+ * <p>
+ * Note that the WikiContext.getPage() method always returns the context
+ * in which text is rendered, i.e. the original request. Thus the content
+ * may actually be different content than what what the wikiContext.getPage()
+ * implies! This happens often if you are for example including multiple
+ * pages on the same page.
+ * <p>
+ * PageFilters must be thread-safe! There is only one instance of each
PageFilter
+ * per each WikiEngine invocation. If you need to store data persistently,
use
+ * VariableManager, or WikiContext.
+ * <p>
+ * As of 2.5.30, initialize() gains access to the WikiEngine.
+ *
+ */
+public interface PageFilter
+{
+ /**
+ * Is called whenever the a new PageFilter is instantiated and
+ * reset.
+ *
+ * @param engine The WikiEngine whic owns this PageFilter
+ * @param properties The properties ripped from filters.xml.
+ * @throws FilterException If the filter could not be initialized. If
this is thrown,
+ * the filter is not added to the internal queues.
+ */
+ public void initialize( WikiEngine engine, Properties properties )
+ throws FilterException;
+
+ /**
+ * This method is called whenever a page has been loaded from the
provider,
+ * but not yet been sent through the markup-translation process. Note
that you cannot
+ * do HTML translation here, because it will be escaped.
+ *
+ * @param wikiContext The current wikicontext.
+ * @param content WikiMarkup.
+ * @return The modified wikimarkup content.
+ * @throws FilterException If something goes wrong. Throwing this causes
the entire page
+ * processing to be abandoned.
+ */
+ public String preTranslate( WikiContext wikiContext, String content )
+ throws FilterException;
+
+ /**
+ * This method is called after a page has been fed through the
translation process,
+ * so anything you are seeing here is translated content. If you want to
+ * do any of your own WikiMarkup2HTML translation, do it here.
+ *
+ * @param wikiContext The WikiContext.
+ * @param htmlContent The translated HTML
+ * @return The modified HTML
+ *
+ * @throws FilterException If something goes wrong. Throwing this causes
the entire page
+ * processing to be abandoned.
+ */
+ public String postTranslate( WikiContext wikiContext, String htmlContent )
+ throws FilterException;
+
+ /**
+ * This method is called before the page has been saved to the
PageProvider.
+ *
+ * @param wikiContext The WikiContext
+ * @param content The wikimarkup that the user just wanted to save.
+ * @return The modified wikimarkup
+ * @throws FilterException If something goes wrong. Throwing this causes
the entire page
+ * processing to be abandoned.
+ */
+ public String preSave( WikiContext wikiContext, String content )
+ throws FilterException;
+
+ /**
+ * This method is called after the page has been successfully saved.
+ * If the saving fails for any reason, then this method will not
+ * be called.
+ * <p>
+ * Since the result is discarded from this method, this is only useful
+ * for things like counters, etc.
+ *
+ * @param wikiContext The WikiContext
+ * @param content The content which was just stored.
+ * @throws FilterException If something goes wrong. As the page is
already saved,
+ * This is just logged.
+ */
+ public void postSave( WikiContext wikiContext, String content )
+ throws FilterException;
+
+ /**
+ * Called for every filter, e.g. on wiki engine shutdown. Use this if you
have to
+ * clean up or close global resources you allocated in the initialize()
method.
+ *
+ * @param engine The WikiEngine which owns this filter.
+ * @since 2.5.36
+ */
+ public void destroy( WikiEngine engine );
+
+}
