jspwiki-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jalka...@apache.org
Subject svn commit: r708011 - in /incubator/jspwiki/trunk: ./ src/org/apache/jspwiki/ src/org/apache/jspwiki/api/
Date Sun, 26 Oct 2008 16:32:06 GMT
Author: jalkanen
Date: Sun Oct 26 09:32:05 2008
New Revision: 708011

URL: http://svn.apache.org/viewvc?rev=708011&view=rev
Log:
Added the api definitions from the separate SVN branch.

Added:
    incubator/jspwiki/trunk/src/org/apache/jspwiki/
    incubator/jspwiki/trunk/src/org/apache/jspwiki/api/
    incubator/jspwiki/trunk/src/org/apache/jspwiki/api/AbstractContext.java
    incubator/jspwiki/trunk/src/org/apache/jspwiki/api/FilterException.java
    incubator/jspwiki/trunk/src/org/apache/jspwiki/api/ModuleData.java
    incubator/jspwiki/trunk/src/org/apache/jspwiki/api/PageFilter.java
    incubator/jspwiki/trunk/src/org/apache/jspwiki/api/PluginException.java
    incubator/jspwiki/trunk/src/org/apache/jspwiki/api/Release.java
    incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiContext.java
    incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiEngine.java
    incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiException.java
    incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiPage.java
    incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiPlugin.java
    incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiRenderer.java
    incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiSession.java
Modified:
    incubator/jspwiki/trunk/ChangeLog

Modified: incubator/jspwiki/trunk/ChangeLog
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/ChangeLog?rev=708011&r1=708010&r2=708011&view=diff
==============================================================================
--- incubator/jspwiki/trunk/ChangeLog (original)
+++ incubator/jspwiki/trunk/ChangeLog Sun Oct 26 09:32:05 2008
@@ -1,3 +1,7 @@
+2008-10-26  Janne Jalkanen <jalkanen@apache.org>
+
+        * Added the 3.0 API definition interfaces from the SVN.
+
 2008-10-17  Janne Jalkanen <jalkanen@apache.org>
 
         * Merged fixes from 2.8.0 branch

Added: incubator/jspwiki/trunk/src/org/apache/jspwiki/api/AbstractContext.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/jspwiki/api/AbstractContext.java?rev=708011&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/jspwiki/api/AbstractContext.java (added)
+++ incubator/jspwiki/trunk/src/org/apache/jspwiki/api/AbstractContext.java Sun Oct 26 09:32:05 2008
@@ -0,0 +1,275 @@
+/* 
+    JSPWiki - a JSP-based WikiWiki clone.
+
+    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.jspwiki.api;
+
+import java.io.IOException;
+import java.security.Permission;
+import java.security.Principal;
+import java.util.Locale;
+import java.util.MissingResourceException;
+import java.util.ResourceBundle;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+/**
+ *  The AbstractContext represents a request lifecycle.  It is valid throughout
+ *  the request, and gives access to innards of JSPWiki.
+ *  <p>
+ *  This mostly replaces the old WikiContext class.  The reason is that WikiContext
+ *  always needs a WikiPage, but since 2.4 we've had quite a few non-page contexts
+ *  like group editing and so on.  For these pages, it is unnecessary to carry
+ *  the WikiPage all around.
+ *  <p>
+ *  WikiContext still stays the main interface for third party developers (e.g. plugins
+ *  or filters).
+ */
+// FIXME: This might be the wrong name.
+public interface AbstractContext
+{
+    
+    /**
+     *  Returns the name of the current template which is in use.
+     *  
+     *  @return The template name
+     */
+    // FIXME: Would it be better to return an object (e.g. WikiTemplate?)
+    public String getContentTemplate();
+    
+    /**
+     *  Returns the name of the top-level JSP file that this one refers to
+     *  @return The JSP file name
+     */
+    // FIXME: Shouldn't this be really just a pointer to the bean?
+    public String getJSP();
+    
+    /**
+     *  Returns the handling engine.
+     *
+     *  @return The wikiengine owning this context.
+     */
+    public WikiEngine getEngine();
+    /**
+     *  Returns the request context.
+     *  @return The name of the request context (e.g. VIEW).
+     */
+    public String getRequestContext();
+
+    /**
+     *  Gets a previously set variable.
+     *
+     *  @param key The variable name.
+     *  @return The variable contents.
+     */
+    public Object getVariable( String key );
+
+    /**
+     *  Sets a variable.  The variable is valid while the WikiContext is valid,
+     *  i.e. while page processing continues.  The variable data is discarded
+     *  once the page processing is finished.
+     *
+     *  @param key The variable name.
+     *  @param data The variable value.
+     */
+    public void setVariable( String key, Object data );
+
+    /**
+     *  This method will safely return any HTTP parameters that
+     *  might have been defined.  You should use this method instead
+     *  of peeking directly into the result of getHttpRequest(), since
+     *  this method is smart enough to do all of the right things,
+     *  figure out UTF-8 encoded parameters, etc.
+     *
+     *  @since 2.0.13.
+     *  @param paramName Parameter name to look for.
+     *  @return HTTP parameter, or null, if no such parameter existed.
+     */
+    public String getHttpParameter( String paramName );
+
+    /**
+     *  If the request did originate from a HTTP request,
+     *  then the HTTP request can be fetched here.  However, it the request
+     *  did NOT originate from a HTTP request, then this method will
+     *  return null, and YOU SHOULD CHECK FOR IT!
+     *
+     *  @return Null, if no HTTP request was done.
+     *  @since 2.0.13.
+     */
+    public HttpServletRequest getHttpRequest();
+
+
+    /**
+     * Returns the target of this wiki context: a page, group name or JSP. If
+     * the associated Command is a PageCommand, this method returns the page's
+     * name. Otherwise, this method delegates to the associated Command's
+     * {@link com.ecyrd.jspwiki.ui.Command#getName()} method. Calling classes
+     * can rely on the results of this method for looking up canonically-correct
+     * page or group names. Because it does not automatically assume that the
+     * wiki context is a PageCommand, calling this method is inherently safer
+     * than calling <code>getPage().getName()</code>.
+     * @return the name of the target of this wiki context
+     * @see com.ecyrd.jspwiki.ui.PageCommand#getName()
+     * @see com.ecyrd.jspwiki.ui.GroupCommand#getName()
+     */
+    public String getName();
+
+    /**
+     *  Gets the template that is to be used throughout this request.
+     *  @since 2.1.15.
+     *  @return template name
+     */
+    public String getTemplate();
+
+    /**
+     *  Convenience method that gets the current user. Delegates the
+     *  lookup to the WikiSession associated with this WikiContect.
+     *  May return null, in case the current
+     *  user has not yet been determined; or this is an internal system.
+     *  If the WikiSession has not been set, <em>always</em> returns null.
+     *
+     *  @return The current user; or maybe null in case of internal calls.
+     */
+    public Principal getCurrentUser();
+
+    /**
+     *  A shortcut to generate a VIEW url.
+     *
+     *  @param page The page to which to link.
+     *  @return An URL to the page.  This honours the current absolute/relative setting.
+     */
+    // FIXME: Better to create a new URL creation class, which is WikiContext-specific?
+    public String getViewURL( String page );
+
+    /**
+     *  Creates an URL for the given request context.
+     *
+     *  @param context e.g. WikiContext.EDIT
+     *  @param page The page to which to link
+     *  @return An URL to the page, honours the absolute/relative setting in jspwiki.properties
+     */
+    public String getURL( String context,
+                          String page );
+
+    /**
+     *  Returns an URL from a page. It this WikiContext instance was constructed
+     *  with an actual HttpServletRequest, we will attempt to construct the
+     *  URL using HttpUtil, which preserves the HTTPS portion if it was used.
+     *
+     *  @param context The request context (e.g. WikiContext.UPLOAD)
+     *  @param page    The page to which to link
+     *  @param params  A list of parameters, separated with "&amp;"
+     *
+     *  @return An URL to the given context and page.
+     */
+    public String getURL( String context,
+                          String page,
+                          String params );
+
+
+    /**
+     *  Returns a shallow clone of the WikiContext.
+     *
+     *  @since 2.1.37.
+     *  @return A shallow clone of the WikiContext
+     */
+    public Object clone();
+
+    /**
+     *  Returns the WikiSession associated with the context.
+     *  This method is guaranteed to always return a valid WikiSession.
+     *  If this context was constructed without an associated
+     *  HttpServletRequest, it will return {@link WikiSession#guestSession(WikiEngine)}.
+     *
+     *  @return The WikiSession associate with this context.
+     */
+    public WikiSession getWikiSession();
+
+    /**
+     * Returns the permission required to successfully execute this context.
+     * For example, the a wiki context of VIEW for a certain page means that
+     * the PagePermission "view" is required for the page. In some cases, no
+     * particular permission is required, in which case a dummy permission will
+     * be returned ({@link java.util.PropertyPermission}<code> "os.name",
+     * "read"</code>). This method is guaranteed to always return a valid,
+     * non-null permission.
+     * @return the permission
+     * @since 2.4
+     */
+    public Permission requiredPermission();
+
+
+    /**
+     * Checks whether the current user has access to this wiki context,
+     * by obtaining the required Permission ({@link #requiredPermission()})
+     * and delegating the access check to
+     * {@link com.ecyrd.jspwiki.auth.AuthorizationManager#checkPermission(WikiSession, Permission)}.
+     * If the user is allowed, this method returns <code>true</code>;
+     * <code>false</code> otherwise. If access is allowed,
+     * the wiki context will be added to the request as an attribute
+     * with the key name {@link com.ecyrd.jspwiki.tags.WikiTagBase#ATTR_CONTEXT}.
+     * Note that this method will automatically redirect the user to
+     * a login or error page, as appropriate, if access fails. This is
+     * NOT guaranteed to be default behavior in the future.
+     * @param response the http response
+     * @return the result of the access check
+     * @throws IOException In case something goes wrong
+     */
+    // FIXME: Is this the correct place really for this?
+    public boolean hasAccess( HttpServletResponse response ) throws IOException;
+
+    /**
+     * Checks whether the current user has access to this wiki context (and
+     * optionally redirects if not), by obtaining the required Permission ({@link #requiredPermission()})
+     * and delegating the access check to
+     * {@link com.ecyrd.jspwiki.auth.AuthorizationManager#checkPermission(WikiSession, Permission)}.
+     * If the user is allowed, this method returns <code>true</code>;
+     * <code>false</code> otherwise. If access is allowed,
+     * the wiki context will be added to the request as attribute
+     * with the key name {@link com.ecyrd.jspwiki.tags.WikiTagBase#ATTR_CONTEXT}.
+     * @return the result of the access check
+     * @param response The servlet response object
+     * @param redirect If true, makes an automatic redirect to the response
+     * @throws IOException If something goes wrong
+     */
+    // FIXME: Is this the correct place really for this?
+    public boolean hasAccess( HttpServletResponse response, boolean redirect ) throws IOException;
+
+    /**
+     *  Locates the i18n ResourceBundle given.  This method interprets
+     *  the request locale, and uses that to figure out which language the
+     *  user wants.
+     *  @see com.ecyrd.jspwiki.i18n.InternationalizationManager
+     *  @param bundle The name of the bundle you are looking for.
+     *  @return A resource bundle object
+     *  @throws MissingResourceException If the bundle cannot be found
+     */
+    public ResourceBundle getBundle( String bundle ) throws MissingResourceException;
+
+    /**
+     *  Returns the locale of the HTTP request if available,
+     *  otherwise returns the default Locale of the server.
+     *
+     *  @return A valid locale object
+     *  @param context The WikiContext
+     */
+    public Locale getLocale();
+
+}

Added: incubator/jspwiki/trunk/src/org/apache/jspwiki/api/FilterException.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/jspwiki/api/FilterException.java?rev=708011&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/jspwiki/api/FilterException.java (added)
+++ incubator/jspwiki/trunk/src/org/apache/jspwiki/api/FilterException.java Sun Oct 26 09:32:05 2008
@@ -0,0 +1,42 @@
+/* 
+    JSPWiki - a JSP-based WikiWiki clone.
+
+    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.jspwiki.api;
+
+/**
+ *  A generic PageFilter exception.
+ *
+ *  @since 2.1.112
+ */
+public class FilterException 
+    extends WikiException
+{
+    private static final long serialVersionUID = 0L;
+    
+    /**
+     *  Constructs an exception.
+     *  
+     *  @param msg {@inheritDoc}
+     */
+    public FilterException( String msg )
+    {
+        super( msg );
+    }
+}

Added: incubator/jspwiki/trunk/src/org/apache/jspwiki/api/ModuleData.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/jspwiki/api/ModuleData.java?rev=708011&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/jspwiki/api/ModuleData.java (added)
+++ incubator/jspwiki/trunk/src/org/apache/jspwiki/api/ModuleData.java Sun Oct 26 09:32:05 2008
@@ -0,0 +1,88 @@
+/*
+    JSPWiki - a JSP-based WikiWiki clone.
+
+    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.jspwiki.api;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ *  This annotation allows you to annotate your plugin in such a way
+ *  that JSPWiki can locate some extra information about it.
+ *  <p>
+ *  This annotation replaces the old jspwiki_modules.xml file - it
+ *  is far better to be able to annotate the class file directly
+ *  than to put the stuff in a separate XML file.
+ *  <p>
+ *  JSPWiki will use Reflection to locate all WikiPlugin classes,
+ *  so the jspwiki_module.xml is not strictly speaking needed. 
+ *  
+ *  @since 3.0
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+public @interface ModuleData
+{
+    /** The author of this module. */
+    String author()         default "AnonymousCoward";
+    
+    /** The minimum version of JSPWiki that this module will work with.  This will be
+     *  checked when the module is loaded.
+     */
+    String minVersion()     default "0.0";
+    
+    /** The maximum version of JSPWiki that this module will work with. */
+    String maxVersion()     default "1000000.0";
+    
+    /** The minimum version of the JSPWiki API that this module will work with.
+     *  Note the difference - you can create a dependency between either a particular
+     *  JSPWiki version, or a particular JSPWiki API version.
+     *  <p>
+     *  Notice that there is no maxAPIVersion(), because JSPWiki API is supposed
+     *  to be completely backwards compatible all the time. (Yeah right.)
+     */
+    String minAPIVersion()  default "0.0";
+    
+    /**
+     *  Defines the style sheets which should be included whenever this module
+     *  is used.  For PageFilters this means almost every single request.
+     */
+    String[] stylesheets()  default {};
+    
+    /**  
+     *  Defines the Javascripts which should be included whenever this module
+     *  is used.
+     */
+    String[] scripts()      default {};
+    
+    /**
+     *  Returns the class name for the AdminBean which governs the use of this
+     *  class.
+     */
+    String adminBeanClass() default "";
+    
+    /**
+     *  Defines the different aliases which can also be used to access this
+     *  module.  This allows you to define a "shorter name" for the module
+     *  to be used in e.g. macros.
+     */
+    String[] aliases()      default "";
+}

Added: incubator/jspwiki/trunk/src/org/apache/jspwiki/api/PageFilter.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/jspwiki/api/PageFilter.java?rev=708011&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/jspwiki/api/PageFilter.java (added)
+++ incubator/jspwiki/trunk/src/org/apache/jspwiki/api/PageFilter.java Sun Oct 26 09:32:05 2008
@@ -0,0 +1,124 @@
+/*
+    JSPWiki - a JSP-based WikiWiki clone.
+
+    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.jspwiki.api;
+
+import java.util.Properties;
+
+
+/**
+ *  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 eingine 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 );
+
+}

Added: incubator/jspwiki/trunk/src/org/apache/jspwiki/api/PluginException.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/jspwiki/api/PluginException.java?rev=708011&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/jspwiki/api/PluginException.java (added)
+++ incubator/jspwiki/trunk/src/org/apache/jspwiki/api/PluginException.java Sun Oct 26 09:32:05 2008
@@ -0,0 +1,66 @@
+/*
+    JSPWiki - a JSP-based WikiWiki clone.
+
+    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.jspwiki.api;
+
+/**
+ *  Provides a generic PluginException.  This is the kind of
+ *  an exception that the plugins should throw.
+ */
+public class PluginException
+    extends WikiException
+{
+    private static final long serialVersionUID = 0L;
+
+    private final Throwable m_throwable;
+
+    /**
+     *  Create a PluginException.
+     *  
+     *  @param message {@inheritDoc}
+     */
+    public PluginException( String message )
+    {
+        super( message );
+        m_throwable = null;
+    }
+
+    /**
+     *  Create a PluginException with the given original exception wrapped.
+     *  
+     *  @param message {@inheritDoc}
+     *  @param original The original exception.
+     */
+    public PluginException( String message, Throwable original )
+    {
+        super( message );
+        m_throwable = original;
+    }
+
+    /**
+     *  Return the original exception.
+     *  
+     *  @return The original exception.
+     */
+    public Throwable getRootThrowable()
+    {
+        return m_throwable;
+    }
+}

Added: incubator/jspwiki/trunk/src/org/apache/jspwiki/api/Release.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/jspwiki/api/Release.java?rev=708011&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/jspwiki/api/Release.java (added)
+++ incubator/jspwiki/trunk/src/org/apache/jspwiki/api/Release.java Sun Oct 26 09:32:05 2008
@@ -0,0 +1,83 @@
+/*
+    JSPWiki - a JSP-based WikiWiki clone.
+
+    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.jspwiki.api;
+
+/**
+ *  Contains release and version information.  You may also invoke this
+ *  class directly, in which case it prints out the version string.  This
+ *  is a handy way of checking which JSPWiki version you have - just type
+ *  from a command line:
+ *  <pre>
+ *  % java -cp JSPWiki-api.jar org.apache.jspwiki.api.Release
+ *  1.0
+ *  </pre>
+ */
+public final class Release
+{
+    /** The JSPWiki API major version. */
+    public static final int        VERSION       = 0;
+
+    /** The JSPWiki API revision. */
+    public static final int        REVISION      = 1;
+    
+    /**
+     *  This is the generic version string you should use
+     *  when printing out the version.  It is of the form "VERSION.REVISION"
+     */
+    public static final String     VERSTR        = VERSION+"."+REVISION;
+
+    /**
+     *  Private constructor prevents instantiation.
+     */
+    private Release()
+    {}
+
+    /**
+     *  This method is useful for templates, because hopefully it will
+     *  not be inlined, and thus any change to version number does not
+     *  need recompiling the pages.
+     *
+     *  @since 2.1.26.
+     *  @return The version string (e.g. 2.5.23).
+     */
+    public static String getVersionString()
+    {
+        return VERSTR;
+    }
+
+    /**
+     *  Executing this class directly from command line prints out
+     *  the current version.  It is very useful for things like
+     *  different command line tools.
+     *  <P>Example:
+     *  <PRE>
+     *  % java org.apache.jspwiki.api.Release
+     *  1.0
+     *  </PRE>
+     *
+     *  @param argv The argument string.  This class takes in no arguments.
+     */
+    public static void main( String[] argv )
+    {
+        System.out.println(VERSTR);
+    }
+}

Added: incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiContext.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiContext.java?rev=708011&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiContext.java (added)
+++ incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiContext.java Sun Oct 26 09:32:05 2008
@@ -0,0 +1,96 @@
+/*
+    JSPWiki - a JSP-based WikiWiki clone.
+
+    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.jspwiki.api;
+
+
+/**
+ *  The WikiContext represents a request which targets a WikiPage
+ *  in some way or the other.
+ *  <p>
+ *  This class would be better named as "PageRequestContext" or something,
+ *  but we need to keep at least some similarity with the 2.x API...
+ */
+public interface WikiContext extends AbstractContext
+{
+
+
+    /**
+     *  Sets a reference to the real page whose content is currently being
+     *  rendered.
+     *  <p>
+     *  Sometimes you may want to render the page using some other page's context.
+     *  In those cases, it is highly recommended that you set the setRealPage()
+     *  to point at the real page you are rendering.  Please see InsertPageTag
+     *  for an example.
+     *  <p>
+     *  Also, if your plugin e.g. does some variable setting, be aware that if it
+     *  is embedded in the LeftMenu or some other page added with InsertPageTag,
+     *  you should consider what you want to do - do you wish to really reference
+     *  the "master" page or the included page.
+     *
+     *  @param page  The real page which is being rendered.
+     *  @return The previous real page
+     *  @since 2.3.14
+     *  @see com.ecyrd.jspwiki.tags.InsertPageTag
+     */
+    public WikiPage setRealPage( WikiPage page );
+
+    /**
+     *  Gets a reference to the real page whose content is currently being rendered.
+     *  If your plugin e.g. does some variable setting, be aware that if it
+     *  is embedded in the LeftMenu or some other page added with InsertPageTag,
+     *  you should consider what you want to do - do you wish to really reference
+     *  the "master" page or the included page.
+     *  <p>
+     *  For example, in the default template, there is a page called "LeftMenu".
+     *  Whenever you access a page, e.g. "Main", the master page will be Main, and
+     *  that's what the getPage() will return - regardless of whether your plugin
+     *  resides on the LeftMenu or on the Main page.  However, getRealPage()
+     *  will return "LeftMenu".
+     *
+     *  @return A reference to the real page.
+     *  @see com.ecyrd.jspwiki.tags.InsertPageTag
+     *  @see com.ecyrd.jspwiki.parser.JSPWikiMarkupParser
+     */
+    public WikiPage getRealPage();
+
+    /**
+     *  Figure out to which page we are really going to.  Considers
+     *  special page names from the jspwiki.properties, and possible aliases.
+     *  This method forwards requests to
+     *  {@link com.ecyrd.jspwiki.ui.CommandResolver#getSpecialPageReference(String)}.
+     *  @return A complete URL to the new page to redirect to
+     *  @since 2.2
+     */
+
+    // FIXME: Probably not needed for 3.0?
+    public String getRedirectURL();
+
+
+    /**
+     *  Returns the page that is being handled.
+     *
+     *  @return the page which was fetched.
+     */
+    public WikiPage getPage();
+
+
+}

Added: incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiEngine.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiEngine.java?rev=708011&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiEngine.java (added)
+++ incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiEngine.java Sun Oct 26 09:32:05 2008
@@ -0,0 +1,61 @@
+/*
+    JSPWiki - a JSP-based WikiWiki clone.
+
+    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.jspwiki.api;
+
+import java.util.Iterator;
+
+/**
+ *  Provides the master interface to the content repository and
+ *  main JSPWiki functionality.
+ */
+public interface WikiEngine
+{
+    /**
+     *  Locates a WikiPage object based on the given path.
+     *  
+     *  @param path The JCR path, relative to the WikiEngine.
+     *  @param version The version which to look for
+     *  @return A WikiPage object, or null, if it could not be located.
+     */
+    public WikiPage getPage( String path, int version );
+    
+    /**
+     *  Returns a Renderer object for a particular type.  Allowed types
+     *  are "xhtml" for XHTML renderer, or whatever might be available as plugins.
+     *  
+     *  @param type A string describing the destination format.
+     *  @return A Renderer object.
+     */
+    public WikiRenderer getRenderer( String type );
+    
+    /**
+     *  Get a configuration parameter.
+     */
+    
+    public String getConfigParameter( String key );
+    
+    /**
+     *  Returns an iterator for all of the parameters keys.
+     * 
+     *  @return An immutable iterator instance.
+     */
+    public Iterator getAllConfigParameters();
+}

Added: incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiException.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiException.java?rev=708011&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiException.java (added)
+++ incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiException.java Sun Oct 26 09:32:05 2008
@@ -0,0 +1,42 @@
+/*
+    JSPWiki - a JSP-based WikiWiki clone.
+
+    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.jspwiki.api;
+
+/**
+ *  A generic Wiki exception.
+ *
+ *  @since 2.0
+ */
+public class WikiException
+    extends Exception
+{
+    private static final long serialVersionUID = 3257290231723210803L;
+
+    /**
+     *  Constructs an exception.
+     *  
+     *  @param msg The message in the exception.
+     */
+    public WikiException( String msg )
+    {
+        super(msg);
+    }
+}

Added: incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiPage.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiPage.java?rev=708011&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiPage.java (added)
+++ incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiPage.java Sun Oct 26 09:32:05 2008
@@ -0,0 +1,216 @@
+/*
+    JSPWiki - a JSP-based WikiWiki clone.
+
+    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.jspwiki.api;
+
+import java.io.InputStream;
+import java.security.acl.Acl;
+import java.util.Date;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ *  A WikiPage represents a Node in the repository.  Unlike in
+ *  JSPWiki 2.x, a WikiPage also represents an attachment - in fact,
+ *  there is no difference between a WikiPage and an attachment, only
+ *  that they hold different ContentTypes.
+ */
+public interface WikiPage
+{    
+    /**
+     *  Returns the name of the page.
+     *  
+     *  @return The page name.
+     */
+    public String getName();
+
+    /**
+     *  Easy accessor to the wiki:contentType attribute.  For example, jspwiki code
+     *  shall return "text/x-jspwiki".
+     *  FIXME: The default MIME type is probably not correct. 
+     *  @return The Wiki Content type.
+     */
+    // NEW
+    public String getContentType();
+    
+    /**
+     *  Easy accessor to setting the wiki:contentType attribute.
+     */
+    // NEW
+    public void setContentType( String contentType );
+    
+    /**
+     *  Returns the content of the page as a stream.
+     */
+    // NEW
+    public InputStream getContentAsStream();
+    
+    /**
+     *  Returns the content as a string, if it can be construed as a string.
+     * 
+     *  @return A string.
+     */
+    //NEW
+    public String getContentAsString();
+    
+    /**
+     *  Set the page content.  This is a shortcut to setting a property "wiki:content".
+     *  
+     *  @param content The page content as a String.
+     */
+    // NEW
+    public void setContent( String content );
+    
+    /**
+     *  Set the page content from an input stream.
+     *  
+     *  @param in The inputstream to read from.
+     */
+    // NEW
+    public void setContent( InputStream in );
+    
+    /**
+     *  Returns the referrers (that is, those pages which reference this page in any form).
+     *  Each String is a path to the WikiPage.
+     */
+    // NEW
+    public Set<String> getReferrers();
+    
+    /**
+     *  A WikiPage may have a number of attributes, which might or might not be 
+     *  available.  Typically attributes are things that do not need to be stored
+     *  with the wiki page to the page repository, but are generated
+     *  on-the-fly.  A provider is not required to save them, but they
+     *  can do that if they really want.
+     *  
+     *  @param key The key using which the attribute is fetched
+     *  @return The attribute.  If the attribute has not been set, returns null.
+     */
+    // TODO: Should this also work with the old SET -attributes?
+    // FIXME: Need to define the relationship between JCR Properties and these.
+    public Object getAttribute( String key );
+
+    /**
+     *  Sets an metadata attribute.  When the page is stored, so are the attributes.
+     *  
+     *  @see #getAttribute(String)
+     *  @param key The key for the attribute used to fetch the attribute later on.
+     *  @param attribute The attribute value
+     */
+    public void setAttribute( String key, Object attribute );
+
+    /**
+     * Returns the full attributes Map, in case external code needs
+     * to iterate through the attributes.
+     * 
+     * @return The attribute Map.  Please note that this is a direct
+     *         reference, not a copy.
+     */
+    public Map<String,Object> getAttributes();
+
+    /**
+     *  Removes an attribute from the page, if it exists.
+     *  
+     *  @param  key The key for the attribute
+     *  @return If the attribute existed, returns the object.
+     *  @since 2.1.111
+     */
+    public Object removeAttribute( String key );
+
+    /**
+     *  Returns the date when this page was last modified.
+     *  
+     *  @return The last modification date
+     */
+    public Date getLastModified();
+
+    /**
+     *  Sets the last modification date.  In general, this is only
+     *  changed by the provider.
+     *  
+     *  @param date The date
+     */
+    public void setLastModified( Date date );
+
+    /**
+     *  Returns the version that this WikiPage instance represents.
+     *  
+     *  @return the version number of this page.
+     */
+    public int getVersion();
+
+    /**
+     *  Returns the size of the page.
+     *  
+     *  @return the size of the page. 
+     *  @since 2.1.109
+     */
+    public long getSize();
+
+    /**
+     *  Returns the Acl for this page.  May return <code>null</code>, 
+     *  in case there is no Acl defined, or it has not
+     *  yet been set by {@link #setAcl(Acl)}.
+     *  
+     *  @return The access control list.  May return null, if there is 
+     *          no acl.
+     */
+    public Acl getAcl();
+
+
+    /**
+     *  Returns author name, or null, if no author has been defined.
+     *  
+     *  @return Author name, or possibly null.
+     */
+    public String getAuthor();
+    
+    /**
+     *  Returns the wiki nanme for this page
+     *  
+     *  @return The name of the wiki.
+     */
+    public String getWiki();
+
+    /**
+     *  Creates a deep clone of a WikiPage.  Strings are not cloned, since
+     *  they're immutable.  Attributes are not cloned, only the internal
+     *  HashMap (so if you modify the contents of a value of an attribute,
+     *  these will reflect back to everyone).
+     *  
+     *  @return A deep clone of the WikiPage
+     */
+    public Object clone();
+    
+    /**
+     *  Compares a page with another.  The primary sorting order
+     *  is according to page name, and if they have the same name,
+     *  then according to the page version.
+     *  
+     *  @param o The object to compare against
+     *  @return -1, 0 or 1
+     */
+    public int compareTo( Object o );
+    
+    /**
+     *  {@inheritDoc}
+     */
+    public int hashCode();
+}

Added: incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiPlugin.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiPlugin.java?rev=708011&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiPlugin.java (added)
+++ incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiPlugin.java Sun Oct 26 09:32:05 2008
@@ -0,0 +1,62 @@
+/* 
+    JSPWiki - a JSP-based WikiWiki clone.
+
+    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.jspwiki.api;
+
+import java.util.Map;
+
+/**
+ *  Defines an interface for plugins.  Any instance of a wiki plugin
+ *  should implement this interface.
+ *
+ */
+public interface WikiPlugin
+{
+    /**
+     *  Name of the default plugin resource bundle.
+     */
+    static final String CORE_PLUGINS_RESOURCEBUNDLE = "plugin.PluginResources";
+
+    /**
+     *  This is the main entry point for any plugin.  The parameters are parsed,
+     *  and a special parameter called "_body" signifies the name of the plugin
+     *  body, i.e. the part of the plugin that is not a parameter of
+     *  the form "key=value".  This has been separated using an empty
+     *  line.
+     *  <P>
+     *  Note that it is preferred that the plugin returns
+     *  XHTML-compliant HTML (i.e. close all tags, use &lt;br /&gt;
+     *  instead of &lt;br&gt;, etc.
+     *
+     *  @param context The current WikiContext.
+     *  @param params  A Map which contains key-value pairs.  Any
+     *                 parameter that the user has specified on the
+     *                 wiki page will contain String-String
+     *  parameters, but it is possible that at some future date,
+     *  JSPWiki will give you other things that are not Strings.
+     *
+     *  @return HTML, ready to be included into the rendered page.
+     *
+     *  @throws PluginException In case anything goes wrong.
+     */
+
+    public String execute( WikiContext context, Map<String, Object> params )
+        throws PluginException;
+}

Added: incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiRenderer.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiRenderer.java?rev=708011&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiRenderer.java (added)
+++ incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiRenderer.java Sun Oct 26 09:32:05 2008
@@ -0,0 +1,61 @@
+/*
+    JSPWiki - a JSP-based WikiWiki clone.
+
+    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.jspwiki.api;
+
+import java.io.InputStream;
+
+/**
+ *  The WikiRenderer interface provides access to the JSPWiki rendering
+ *  engine.  The job of the WikiRenderer is to grab content in a
+ *  particular type, and shove it out in its native type.
+ *  <p>
+ *  Typical WikiRenderers might be:
+ *  <ul>
+ *    <li>XHTMLRenderer - takes in WikiMarkup and outputs XHTML</li>
+ *    <li>TextRenderer - takes in WikiMarkup and produces plain text</li>
+ *    <li>CleanRenderer - takes in WikiMarkup and makes it such that it can be included in HTML content.</li>
+ *    <li>PDFRenderer - takes in any sort of content and turns it into PDF content.</li>
+ *  </ul>
+ *
+ */
+public interface WikiRenderer
+{
+    /**
+     *  Returns the MIME type for the content that this Renderer
+     *  outputs.  For example, a PDF renderer might be returning
+     *  something like "application/pdf", and a HTML renderer might
+     *  be returning "text/html".
+     *  
+     *  @return A MIME type describing the output of the Renderer.
+     */
+    public String getContentType();
+    
+    /**
+     *  Returns the rendered content.
+     */
+    public InputStream render( AbstractContext context, String content );
+    
+    /**
+     *  Returns the rendered content as a String.  This is just a simplification
+     *  for those content types where it can be rendered as a String.
+     */
+    public String renderString( AbstractContext context, String content );
+}

Added: incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiSession.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiSession.java?rev=708011&view=auto
==============================================================================
--- incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiSession.java (added)
+++ incubator/jspwiki/trunk/src/org/apache/jspwiki/api/WikiSession.java Sun Oct 26 09:32:05 2008
@@ -0,0 +1,249 @@
+/*
+    JSPWiki - a JSP-based WikiWiki clone.
+
+    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.jspwiki.api;
+
+import java.security.Principal;
+import java.util.Locale;
+
+/**
+ * <p>Represents a long-running wiki session, with an associated user Principal,
+ * user Subject, and authentication status. This class is initialized with
+ * minimal, default-deny values: authentication is set to <code>false</code>,
+ * and the user principal is set to <code>null</code>.</p>
+ * <p>The WikiSession class allows callers to:</p>
+ * <ul>
+ *   <li>Obtain the authentication status of the user via
+ *     {@link #isAnonymous()} and {@link #isAuthenticated()}</li>
+ *   <li>Query the session for Principals representing the
+ *     user's identity via {@link #getLoginPrincipal()},
+ *     {@link #getUserPrincipal()} and {@link #getPrincipals()}</li>
+ *   <li>Store, retrieve and clear UI messages via
+ *     {@link #addMessage(String)}, {@link #getMessages(String)}
+ *     and {@link #clearMessages(String)}</li>
+ * </ul>
+ * <p>To keep track of the Principals each user posseses, each WikiSession
+ * stores a JAAS Subject. Various login processes add or remove Principals
+ * when users authenticate or log out.</p>
+ * <p>WikiSession implements the {@link com.ecyrd.jspwiki.event.WikiEventListener}
+ * interface and listens for group add/change/delete events fired by
+ * event sources the WikiSession is registered with. Normally,
+ * {@link com.ecyrd.jspwiki.auth.AuthenticationManager} registers each WikiSession
+ * with the {@link com.ecyrd.jspwiki.auth.authorize.GroupManager}
+ * so it can catch group events. Thus, when a user is added to a
+ * {@link com.ecyrd.jspwiki.auth.authorize.Group}, a corresponding
+ * {@link com.ecyrd.jspwiki.auth.GroupPrincipal} is injected into
+ * the Subject's Principal set. Likewise, when the user is removed from
+ * the Group or the Group is deleted, the GroupPrincipal is removed
+ * from the Subject. The effect that this strategy produces is extremely
+ * beneficial: when someone adds a user to a wiki group, that user
+ * <em>immediately</em> gains the privileges associated with that
+ * group; he or she does not need to re-authenticate.
+ * </p>
+ * <p>In addition to methods for examining individual <code>WikiSession</code>
+ * objects, this class also contains a number of static methods for
+ * managing WikiSessions for an entire wiki. These methods allow callers
+ * to find, query and remove WikiSession objects, and
+ * to obtain a list of the current wiki session users.</p>
+ * <p>WikiSession encloses a protected static class, {@link SessionMonitor},
+ * to keep track of WikiSessions registered with each wiki.</p>
+ * @author Andrew R. Jaquith
+ */
+public interface WikiSession
+{
+
+    /**
+     *  Returns true, if the current user has administrative permissions (i.e. the omnipotent
+     *  AllPermission).
+     *
+     *  @since 2.4.46
+     *  @return true, if the user has all permissions.
+     */
+    // NEW: moved from WikiContext.hasAdminPermissions()
+    public boolean isAdmin();
+
+    /**
+     * Returns <code>true</code> if the user is considered asserted via
+     * a session cookie; that is, the Subject contains the Principal
+     * Role.ASSERTED.
+     * @return Returns <code>true</code> if the user is asserted
+     */
+    public boolean isAsserted();
+
+    /**
+     * Returns the authentication status of the user's session. The user is
+     * considered authenticated if the Subject contains the Principal
+     * Role.AUTHENTICATED. If this method determines that an earlier
+     * LoginModule did not inject Role.AUTHENTICATED, it will inject one
+     * if the user is not anonymous <em>and</em> not asserted.
+     * @return Returns <code>true</code> if the user is authenticated
+     */
+    public boolean isAuthenticated();
+
+    /**
+     * <p>Determines whether the current session is anonymous. This will be
+     * true if any of these conditions are true:</p>
+     * <ul>
+     *   <li>The session's Principal set contains
+     *       {@link com.ecyrd.jspwiki.auth.authorize.Role#ANONYMOUS}</li>
+     *   <li>The session's Principal set contains
+     *       {@link com.ecyrd.jspwiki.auth.WikiPrincipal#GUEST}</li>
+     *   <li>The Principal returned by {@link #getUserPrincipal()} evaluates
+     *       to an IP address.</li>
+     * </ul>
+     * <p>The criteria above are listed in the order in which they are
+     * evaluated.</p>
+     * @return whether the current user's identity is equivalent to an IP
+     * address
+     */
+    public boolean isAnonymous();
+
+    /**
+     * <p> Returns the Principal used to log in to an authenticated session. The
+     * login principal is determined by examining the Subject's Principal set
+     * for PrincipalWrappers or WikiPrincipals with type designator
+     * <code>LOGIN_NAME</code>; the first one found is the login principal.
+     * If one is not found, this method returns the first principal that isn't
+     * of type Role or GroupPrincipal. If neither of these conditions hold, this method returns
+     * {@link com.ecyrd.jspwiki.auth.WikiPrincipal#GUEST}.
+     * @return the login Principal. If it is a PrincipalWrapper containing an
+     * externally-provided Principal, the object returned is the Principal, not
+     * the wrapper around it.
+     */
+    public Principal getLoginPrincipal();
+
+    /**
+     * <p>Returns the primary user Principal associated with this session. The
+     * primary user principal is determined as follows:</p> <ol> <li>If the
+     * Subject's Principal set contains WikiPrincipals, the first WikiPrincipal
+     * with type designator <code>WIKI_NAME</code> or (alternatively)
+     * <code>FULL_NAME</code> is the primary Principal.</li>
+     *   <li>For all other cases, the first Principal in the Subject's principal
+     *       collection that that isn't of type Role or GroupPrincipal is the primary.</li>
+     * </ol>
+     * If no primary user Principal is found, this method returns
+     * {@link com.ecyrd.jspwiki.auth.WikiPrincipal#GUEST}.
+     * @return the primary user Principal
+     */
+    public Principal getUserPrincipal();
+
+    /**
+     *  Returns a cached Locale object for this user.  It's better to use
+     *  WikiContext's corresponding getBundle() method, since that will actually
+     *  react if the user changes the locale in the middle, but if that's not
+     *  available (or, for some reason, you need the speed), this method can
+     *  also be used.  The Locale expires when the WikiSession expires, and
+     *  currently there is no way to reset the Locale.
+     *
+     *  @return A cached Locale object
+     *  @since 2.5.96
+     */
+    public Locale getLocale();
+
+    /**
+     * Adds a message to the generic list of messages associated with the
+     * session. These messages retain their order of insertion and remain until
+     * the {@link #clearMessages()} method is called.
+     * @param message the message to add; if <code>null</code> it is ignored.
+     */
+    public void addMessage(String message);
+
+
+    /**
+     * Adds a message to the specific set of messages associated with the
+     * session. These messages retain their order of insertion and remain until
+     * the {@link #clearMessages()} method is called.
+     * @param topic the topic to associate the message to;
+     * @param message the message to add
+     */
+    public void addMessage(String topic, String message);
+
+    /**
+     * Clears all messages associated with this session.
+     */
+    public void clearMessages();
+
+    /**
+     * Clears all messages associated with a session topic.
+     * @param topic the topic whose messages should be cleared.
+     */
+    public void clearMessages( String topic );
+
+    /**
+     * Returns all generic messages associated with this session.
+     * The messages stored with the session persist throughout the
+     * session unless they have been reset with {@link #clearMessages()}.
+     * @return the current messages.
+     */
+    public String[] getMessages();
+
+    /**
+     * Returns all messages associated with a session topic.
+     * The messages stored with the session persist throughout the
+     * session unless they have been reset with {@link #clearMessages(String)}.
+     * @return the current messages.
+     * @param topic The topic
+     */
+    public String[] getMessages( String topic );
+
+    /**
+     * Returns all user Principals associated with this session. User principals
+     * are those in the Subject's principal collection that aren't of type Role or
+     * of type GroupPrincipal. This is a defensive copy.
+     * @return Returns the user principal
+     * @see com.ecyrd.jspwiki.auth.AuthenticationManager#isUserPrincipal(Principal)
+     */
+    public Principal[] getPrincipals();
+
+    /**
+     * Returns an array of Principal objects that represents the groups and
+     * roles that the user associated with a WikiSession possesses. The array is
+     * built by iterating through the Subject's Principal set and extracting all
+     * Role and GroupPrincipal objects into a list. The list is returned as an
+     * array sorted in the natural order implied by each Principal's
+     * <code>getName</code> method. Note that this method does <em>not</em>
+     * consult the external Authorizer or GroupManager; it relies on the
+     * Principals that have been injected into the user's Subject at login time,
+     * or after group creation/modification/deletion.
+     * @return an array of Principal objects corresponding to the roles the
+     *         Subject possesses
+     */
+    public Principal[] getRoles();
+
+    /**
+     * Returns <code>true</code> if the WikiSession's Subject
+     * possess a supplied Principal. This method eliminates the need
+     * to externally request and inspect the JAAS subject.
+     * @param principal the Principal to test
+     * @return the result
+     */
+    public boolean hasPrincipal( Principal principal );
+
+    /**
+     * <p>Returns the status of the wiki session as a text string. Valid values are:</p>
+     * <ul>
+     *   <li>{@link #AUTHENTICATED}</li>
+     *   <li>{@link #ASSERTED}</li>
+     *   <li>{@link #ANONYMOUS}</li>
+     * </ul>
+     * @return the user's session status
+     */
+    public String getStatus();
+}



Mime
View raw message