You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jspwiki.apache.org by ja...@apache.org on 2008/07/01 21:09:58 UTC
svn commit: r673183 - in /incubator/jspwiki/api: ./ .settings/ src/ src/org/
src/org/apache/ src/org/apache/jspwiki/ src/org/apache/jspwiki/api/
Author: jalkanen
Date: Tue Jul 1 12:09:58 2008
New Revision: 673183
URL: http://svn.apache.org/viewvc?rev=673183&view=rev
Log:
Initial proposal commit.
Added:
incubator/jspwiki/api/.classpath
incubator/jspwiki/api/.project
incubator/jspwiki/api/.settings/
incubator/jspwiki/api/.settings/org.eclipse.jdt.core.prefs
incubator/jspwiki/api/README
incubator/jspwiki/api/src/
incubator/jspwiki/api/src/org/
incubator/jspwiki/api/src/org/apache/
incubator/jspwiki/api/src/org/apache/jspwiki/
incubator/jspwiki/api/src/org/apache/jspwiki/api/
incubator/jspwiki/api/src/org/apache/jspwiki/api/FilterException.java
incubator/jspwiki/api/src/org/apache/jspwiki/api/PageFilter.java
incubator/jspwiki/api/src/org/apache/jspwiki/api/PluginException.java
incubator/jspwiki/api/src/org/apache/jspwiki/api/Release.java
incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiContext.java
incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiEngine.java
incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiException.java
incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiPage.java
incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiPlugin.java
incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiSession.java
Added: incubator/jspwiki/api/.classpath
URL: http://svn.apache.org/viewvc/incubator/jspwiki/api/.classpath?rev=673183&view=auto
==============================================================================
--- incubator/jspwiki/api/.classpath (added)
+++ incubator/jspwiki/api/.classpath Tue Jul 1 12:09:58 2008
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+ <classpathentry kind="src" path="src"/>
+ <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
+ <classpathentry kind="con" path="org.eclipse.jst.server.core.container/org.eclipse.jst.server.tomcat.runtimeTarget/Apache Tomcat v5.5"/>
+ <classpathentry kind="output" path="bin"/>
+</classpath>
Added: incubator/jspwiki/api/.project
URL: http://svn.apache.org/viewvc/incubator/jspwiki/api/.project?rev=673183&view=auto
==============================================================================
--- incubator/jspwiki/api/.project (added)
+++ incubator/jspwiki/api/.project Tue Jul 1 12:09:58 2008
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+ <name>JSPWiki-API</name>
+ <comment></comment>
+ <projects>
+ </projects>
+ <buildSpec>
+ <buildCommand>
+ <name>org.eclipse.jdt.core.javabuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
+ </buildSpec>
+ <natures>
+ <nature>org.eclipse.jdt.core.javanature</nature>
+ </natures>
+</projectDescription>
Added: incubator/jspwiki/api/.settings/org.eclipse.jdt.core.prefs
URL: http://svn.apache.org/viewvc/incubator/jspwiki/api/.settings/org.eclipse.jdt.core.prefs?rev=673183&view=auto
==============================================================================
--- incubator/jspwiki/api/.settings/org.eclipse.jdt.core.prefs (added)
+++ incubator/jspwiki/api/.settings/org.eclipse.jdt.core.prefs Tue Jul 1 12:09:58 2008
@@ -0,0 +1,12 @@
+#Tue Jul 01 21:32:08 EEST 2008
+eclipse.preferences.version=1
+org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled
+org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.5
+org.eclipse.jdt.core.compiler.codegen.unusedLocal=preserve
+org.eclipse.jdt.core.compiler.compliance=1.5
+org.eclipse.jdt.core.compiler.debug.lineNumber=generate
+org.eclipse.jdt.core.compiler.debug.localVariable=generate
+org.eclipse.jdt.core.compiler.debug.sourceFile=generate
+org.eclipse.jdt.core.compiler.problem.assertIdentifier=error
+org.eclipse.jdt.core.compiler.problem.enumIdentifier=error
+org.eclipse.jdt.core.compiler.source=1.5
Added: incubator/jspwiki/api/README
URL: http://svn.apache.org/viewvc/incubator/jspwiki/api/README?rev=673183&view=auto
==============================================================================
--- incubator/jspwiki/api/README (added)
+++ incubator/jspwiki/api/README Tue Jul 1 12:09:58 2008
@@ -0,0 +1,5 @@
+This is the JSPWiki 3.0 API directory. Please look for more information at
+
+http://www.jspwiki.org/wiki/JSPWiki3APIDesignProposal
+
+Any discussion should go to jspwiki-dev@incubator.apache.org.
Added: incubator/jspwiki/api/src/org/apache/jspwiki/api/FilterException.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/api/src/org/apache/jspwiki/api/FilterException.java?rev=673183&view=auto
==============================================================================
--- incubator/jspwiki/api/src/org/apache/jspwiki/api/FilterException.java (added)
+++ incubator/jspwiki/api/src/org/apache/jspwiki/api/FilterException.java Tue Jul 1 12:09:58 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/api/src/org/apache/jspwiki/api/PageFilter.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/api/src/org/apache/jspwiki/api/PageFilter.java?rev=673183&view=auto
==============================================================================
--- incubator/jspwiki/api/src/org/apache/jspwiki/api/PageFilter.java (added)
+++ incubator/jspwiki/api/src/org/apache/jspwiki/api/PageFilter.java Tue Jul 1 12:09:58 2008
@@ -0,0 +1,104 @@
+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/api/src/org/apache/jspwiki/api/PluginException.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/api/src/org/apache/jspwiki/api/PluginException.java?rev=673183&view=auto
==============================================================================
--- incubator/jspwiki/api/src/org/apache/jspwiki/api/PluginException.java (added)
+++ incubator/jspwiki/api/src/org/apache/jspwiki/api/PluginException.java Tue Jul 1 12:09:58 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/api/src/org/apache/jspwiki/api/Release.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/api/src/org/apache/jspwiki/api/Release.java?rev=673183&view=auto
==============================================================================
--- incubator/jspwiki/api/src/org/apache/jspwiki/api/Release.java (added)
+++ incubator/jspwiki/api/src/org/apache/jspwiki/api/Release.java Tue Jul 1 12:09:58 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/api/src/org/apache/jspwiki/api/WikiContext.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiContext.java?rev=673183&view=auto
==============================================================================
--- incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiContext.java (added)
+++ incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiContext.java Tue Jul 1 12:09:58 2008
@@ -0,0 +1,312 @@
+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;
+
+/**
+ * A WikiContext represents one single request transaction, from beginning to
+ * the end.
+ *
+ */
+public interface WikiContext
+{
+
+ /**
+ * {@inheritDoc}
+ * @see com.ecyrd.jspwiki.ui.Command#getContentTemplate()
+ */
+ public String getContentTemplate();
+
+ /**
+ * {@inheritDoc}
+ * @see com.ecyrd.jspwiki.ui.Command#getJSP()
+ */
+ public String getJSP();
+
+ /**
+ * 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
+ */
+
+ public String getRedirectURL();
+
+ /**
+ * Returns the handling engine.
+ *
+ * @return The wikiengine owning this context.
+ */
+ public WikiEngine getEngine();
+
+ /**
+ * Returns the page that is being handled.
+ *
+ * @return the page which was fetched.
+ */
+ public WikiPage getPage();
+
+ /**
+ * Returns the request context.
+ * @return The name of the request context (e.g. VIEW).
+ */
+ public String getRequestContext();
+
+ /**
+ * {@inheritDoc}
+ * @see com.ecyrd.jspwiki.ui.Command#getTarget()
+ */
+ public Object getTarget();
+
+ /**
+ * {@inheritDoc}
+ * @see com.ecyrd.jspwiki.ui.Command#getURLPattern()
+ */
+ public String getURLPattern();
+
+ /**
+ * 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.
+ */
+ 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 "&"
+ *
+ * @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
+ */
+ 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
+ */
+ 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/api/src/org/apache/jspwiki/api/WikiEngine.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiEngine.java?rev=673183&view=auto
==============================================================================
--- incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiEngine.java (added)
+++ incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiEngine.java Tue Jul 1 12:09:58 2008
@@ -0,0 +1,26 @@
+package org.apache.jspwiki.api;
+
+/**
+ * Provides the master interface to the content repository.
+ */
+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 );
+
+ /**
+ * Stores a version of the page to the repository.
+ *
+ * @param p
+ */
+ // FIXME: Should we rather use WikiPage.save()?
+ public void savePage( WikiPage p );
+
+
+}
Added: incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiException.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiException.java?rev=673183&view=auto
==============================================================================
--- incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiException.java (added)
+++ incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiException.java Tue Jul 1 12:09:58 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/api/src/org/apache/jspwiki/api/WikiPage.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiPage.java?rev=673183&view=auto
==============================================================================
--- incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiPage.java (added)
+++ incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiPage.java Tue Jul 1 12:09:58 2008
@@ -0,0 +1,158 @@
+package org.apache.jspwiki.api;
+
+import java.io.InputStream;
+import java.security.acl.Acl;
+import java.util.Date;
+import java.util.Map;
+
+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();
+
+ /**
+ * 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
+ */
+ //NEW
+ public String getContentAsString();
+
+ /**
+ * 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?
+ 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/api/src/org/apache/jspwiki/api/WikiPlugin.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiPlugin.java?rev=673183&view=auto
==============================================================================
--- incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiPlugin.java (added)
+++ incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiPlugin.java Tue Jul 1 12:09:58 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 <br />
+ * instead of <br>, 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/api/src/org/apache/jspwiki/api/WikiSession.java
URL: http://svn.apache.org/viewvc/incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiSession.java?rev=673183&view=auto
==============================================================================
--- incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiSession.java (added)
+++ incubator/jspwiki/api/src/org/apache/jspwiki/api/WikiSession.java Tue Jul 1 12:09:58 2008
@@ -0,0 +1,229 @@
+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();
+}