jspwiki-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From juanpa...@apache.org
Subject svn commit: r1426046 - in /incubator/jspwiki/trunk/src/org/apache/wiki: ./ api/exceptions/ api/filters/
Date Wed, 26 Dec 2012 22:14:50 GMT
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 );
+
+}



Mime
View raw message