This is an automated email from the ASF dual-hosted git repository. juanpablo pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/jspwiki.git
commit 49940ae404e47904d6a2364102e123f6907eb7c9 Author: juanpablo <[email protected]> AuthorDate: Wed Mar 11 18:38:38 2020 +0100 JSPWIKI-303: public API package moved to its own module + added rest of proposed classes for that package - Right now only Engine and Session are widely used - new Plugin interface to replace current WikiPlugin one - PageFilter uses Context instead of WikiContext - classes in this module still need some more work, this first commit is more focused on providing a compilable module and make it being usable by jspwiki-main --- jspwiki-api/pom.xml | 73 +++++++ .../src/main/java/org/apache/wiki/api/Release.java | 0 .../main/java/org/apache/wiki/api/core/Acl.java | 101 +++++++++ .../java/org/apache/wiki/api/core/AclEntry.java | 90 ++++++++ .../java/org/apache/wiki/api/core/Attachment.java | 63 ++++++ .../java/org/apache/wiki/api/core/Command.java | 131 +++++++++++ .../java/org/apache/wiki/api/core/Context.java | 239 +++++++++++++++++++++ .../main/java/org/apache/wiki/api/core/Engine.java | 0 .../main/java/org/apache/wiki/api/core/Page.java | 183 ++++++++++++++++ .../java/org/apache/wiki/api/core/Session.java | 0 .../java/org/apache/wiki/api/core/package.html | 0 .../wiki/api/exceptions/FilterException.java | 2 +- .../exceptions/NoRequiredPropertyException.java | 2 +- .../api/exceptions/NoSuchVariableException.java | 2 +- .../wiki/api/exceptions/PluginException.java | 4 +- .../wiki/api/exceptions/ProviderException.java | 2 +- .../wiki/api/exceptions/RedirectException.java | 2 +- .../apache/wiki/api/exceptions/WikiException.java | 4 +- .../wiki/api/exceptions/WikiI18nException.java | 2 +- .../org/apache/wiki/api/exceptions/package.html | 0 .../apache/wiki/api/filters/BasicPageFilter.java | 0 .../org/apache/wiki/api/filters/PageFilter.java | 12 +- .../java/org/apache/wiki/api/filters/package.html | 0 .../src/main/java/org/apache/wiki/api/package.html | 0 .../wiki/api/plugin/InitializablePlugin.java | 0 .../apache/wiki/api/plugin/ParserStagePlugin.java | 4 +- .../java/org/apache/wiki/api/plugin/Plugin.java | 38 ++-- .../org/apache/wiki/api/plugin/PluginElement.java | 6 +- .../java/org/apache/wiki/api/plugin/package.html | 0 .../wiki/api/providers/AttachmentProvider.java | 145 +++++++++++++ .../apache/wiki/api/providers/PageProvider.java | 170 +++++++++++++++ .../apache/wiki/api/providers/WikiProvider.java | 57 +++++ .../org/apache/wiki/api/providers}/package.html | 6 +- .../java/org/apache/wiki/api/search/QueryItem.java | 45 ++-- .../org/apache/wiki/api/search/SearchResult.java | 41 ++-- .../java/org/apache/wiki/api/search}/package.html | 6 +- .../org/apache/wiki/api/plugin/WikiPlugin.java | 45 ++-- 37 files changed, 1349 insertions(+), 126 deletions(-) diff --git a/jspwiki-api/pom.xml b/jspwiki-api/pom.xml new file mode 100644 index 0000000..67b7a20 --- /dev/null +++ b/jspwiki-api/pom.xml @@ -0,0 +1,73 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + 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. +--> +<project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd";> + + <parent> + <groupId>org.apache.jspwiki</groupId> + <artifactId>jspwiki-builder</artifactId> + <version>2.11.0.M7-SNAPSHOT</version> + </parent> + + <modelVersion>4.0.0</modelVersion> + <artifactId>jspwiki-api</artifactId> + <name>Apache JSPWiki public API</name> + + <dependencies> + <dependency> + <groupId>${project.groupId}</groupId> + <artifactId>jspwiki-event</artifactId> + <version>${project.version}</version> + </dependency> + + <dependency> + <groupId>log4j</groupId> + <artifactId>log4j</artifactId> + </dependency> + + <dependency> + <groupId>org.apache.commons</groupId> + <artifactId>commons-lang3</artifactId> + </dependency> + + <dependency> + <groupId>javax.servlet</groupId> + <artifactId>javax.servlet-api</artifactId> + <scope>provided</scope> + </dependency> + + <dependency> + <groupId>org.junit.jupiter</groupId> + <artifactId>junit-jupiter-api</artifactId> + <scope>test</scope> + </dependency> + + <dependency> + <groupId>org.junit.jupiter</groupId> + <artifactId>junit-jupiter-params</artifactId> + <scope>test</scope> + </dependency> + + <dependency> + <groupId>org.junit.jupiter</groupId> + <artifactId>junit-jupiter-engine</artifactId> + <scope>test</scope> + </dependency> + </dependencies> +</project> diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/Release.java b/jspwiki-api/src/main/java/org/apache/wiki/api/Release.java similarity index 100% rename from jspwiki-main/src/main/java/org/apache/wiki/api/Release.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/Release.java diff --git a/jspwiki-api/src/main/java/org/apache/wiki/api/core/Acl.java b/jspwiki-api/src/main/java/org/apache/wiki/api/core/Acl.java new file mode 100644 index 0000000..be51eb9 --- /dev/null +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/core/Acl.java @@ -0,0 +1,101 @@ +/* + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + */ +package org.apache.wiki.api.core; + +import java.security.Permission; +import java.security.Principal; +import java.util.Enumeration; + + +/** + * <p> + * Defines an access control list (ACL) for wiki pages. An Access Control List is a data structure used to guard access to resources. + * An ACL can be thought of as a data structure with multiple ACL entries. Each ACL entry, of interface type AclEntry, contains a set + * of positive permissions associated with a particular principal. (A principal represents an entity such as an individual user or a + * group). The ACL Entries in each ACL observe the following rules: + * </p> + * <ul> + * <li>Each principal can have at most one ACL entry; that is, multiple ACL entries are not allowed for any principal. Each entry + * specifies the set of permissions that are to be granted</li> + * <li>If there is no entry for a particular principal, then the principal is considered to have a null (empty) permission set</li> + * </ul> + * <p> + * This interface is a highly stripped-down derivation of the java.security.acl.Acl interface. In particular, the notion of an Acl "owner" + * has been eliminated, since JSPWiki pages do not have owners. An additional simplification compared to the standard Java package is that + * negative permissions have been eliminated. Instead, JSPWiki assumes a "default-deny" security stance: principals are granted no + * permissions by default, and posesses only those that have been explicitly granted to them. And finally, the getPermissions() and + * checkPermission() methods have been eliminated due to the complexities associated with resolving Role principal membership. + * </p> + * @since 2.3 + */ +public interface Acl { + + /** + * Adds an ACL entry to this ACL. An entry associates a principal (e.g., an individual or a group) with a set of permissions. + * Each principal can have at most one positive ACL entry, specifying permissions to be granted to the principal. If there is + * already an ACL entry already in the ACL, false is returned. + * + * @param entry - the ACL entry to be added to this ACL + * @return true on success, false if an entry of the same type (positive or negative) for the same principal is already present + * in this ACL + */ + boolean addEntry( AclEntry entry ); + + /** + * Returns an enumeration of the entries in this ACL. Each element in the enumeration is of type AclEntry. + * + * @return an enumeration of the entries in this ACL. + */ + Enumeration< AclEntry > entries(); + + /** + * Returns <code>true</code>, if this Acl is empty. + * + * @return the result + * @since 2.4.68 + */ + boolean isEmpty(); + + /** + * Returns all Principal objects assigned a given Permission in the access control list. The Princiapls returned are those that + * have been granted either the supplied permission, or a permission implied by the supplied permission. Principals are not + * "expanded" if they are a role or group. + * + * @param permission the permission to search for + * @return an array of Principals posessing the permission + */ + Principal[] findPrincipals( Permission permission ); + + /** + * Returns an AclEntry for a supplied Principal, or <code>null</code> if the Principal does not have a matching AclEntry. + * + * @param principal the principal to search for + * @return the AclEntry associated with the principal, or <code>null</code> + */ + AclEntry getEntry( Principal principal ); + + /** + * Removes an ACL entry from this ACL. + * + * @param entry the ACL entry to be removed from this ACL + * @return true on success, false if the entry is not part of this ACL + */ + boolean removeEntry( AclEntry entry ); + +} diff --git a/jspwiki-api/src/main/java/org/apache/wiki/api/core/AclEntry.java b/jspwiki-api/src/main/java/org/apache/wiki/api/core/AclEntry.java new file mode 100644 index 0000000..2843f29 --- /dev/null +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/core/AclEntry.java @@ -0,0 +1,90 @@ +/* + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + */ +package org.apache.wiki.api.core; + +import java.security.Permission; +import java.security.Principal; +import java.util.Enumeration; + + +/** + * <p>Represents one entry in an Access Control List (ACL).</p> + * <p> + * An ACL can be thought of as a data structure with multiple ACL entry objects. Each ACL entry object contains a set of positive page + * permissions associated with a particular principal. (A principal represents an entity such as an individual user, group, or role). + * Each principal can have at most one ACL entry; that is, multiple ACL entries are not allowed for any principal. + * </p> + * <p>This interface is functionally equivalent to the java.security.acl.AclEntry interface, minus negative permissions. </p> + * + * @see Acl + * @since 2.3 + */ +public interface AclEntry { + + /** + * Adds the specified permission to this ACL entry. The permission <em>must</em> be of type + * {@link org.apache.wiki.auth.permissions.PagePermission}. Note: An entry can have multiple permissions. + * + * @param permission the permission to be associated with the principal in this entry + * @return <code>true</code> if the permission was added, <code>false</code> if the permission was + * already part of this entry's permission set, and <code>false</code> if the permission is not of type PagePermission + */ + boolean addPermission( Permission permission ); + + /** + * Checks if the specified permission is part of the permission set in this entry. + * + * @param permission the permission to be checked for. + * @return true if the permission is part of the permission set in this entry, false otherwise. + */ + boolean checkPermission( Permission permission ); + + /** + * Returns the principal for which permissions are granted by this ACL entry. Returns null if there is no principal set for this + * entry yet. + * + * @return the principal associated with this entry. + */ + Principal getPrincipal(); + + /** + * Returns an enumeration of the permissions in this ACL entry. + * + * @return an enumeration of the permissions + */ + Enumeration< Permission > permissions(); + + /** + * Removes the specified permission from this ACL entry. + * + * @param permission the permission to be removed from this entry. + * @return true if the permission is removed, false if the permission was not part of this entry's permission set. + */ + boolean removePermission( Permission permission ); + + /** + * Specifies the principal for which permissions are granted or denied by this ACL entry. If a principal was already set for + * this ACL entry, false is returned, otherwise true is returned. + * + * @param user the principal to be set for this entry + * @return true if the principal is set, false if there was already a principal set for this entry + */ + boolean setPrincipal( Principal user ); + +} diff --git a/jspwiki-api/src/main/java/org/apache/wiki/api/core/Attachment.java b/jspwiki-api/src/main/java/org/apache/wiki/api/core/Attachment.java new file mode 100644 index 0000000..2841ec3 --- /dev/null +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/core/Attachment.java @@ -0,0 +1,63 @@ +/* + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + */ +package org.apache.wiki.api.core; + +/** + * Describes an attachment. Attachments are actually derivatives of a WikiPage, since they do actually have a WikiName as well. + */ +public interface Attachment extends Page { + + /** + * Returns the file name of the attachment. + * + * @return A String with the file name. + */ + String getFileName(); + + /** + * Sets the file name of this attachment. + * + * @param name The name of the attachment. Must be a legal file name without the path. + */ + void setFileName( String name ); + + /** + * Returns the name of the parent of this Attachment, i.e. the page which contains this attachment. + * + * @return String depicting the parent of the attachment. + */ + String getParentName(); + + /** + * Returns true, if this attachment can be cached by the user agent. By default attachments are cacheable. + * + * @return False, if the attachment should not be cached by the user agent. + * @since 2.5.34 + */ + boolean isCacheable(); + + /** + * Sets this attachment to be cacheable or not. This mostly concerns things like DynamicAttachments, but it may be useful for + * certain AttachmentProviders as well. + * + * @param value True or false, depending on whether you want this attachment to be cacheable or not. + * @since 2.5.34 + */ + void setCacheable( boolean value ); +} diff --git a/jspwiki-api/src/main/java/org/apache/wiki/api/core/Command.java b/jspwiki-api/src/main/java/org/apache/wiki/api/core/Command.java new file mode 100644 index 0000000..38b14d3 --- /dev/null +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/core/Command.java @@ -0,0 +1,131 @@ +/* + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + */ +package org.apache.wiki.api.core; + +import java.security.Permission; + + +/** + * <p>Represents a logical "unit of work" that includes a request context, JSP, URLPattern, content template and (optionally) a target and + * required security permission. Examples of Commands include "view a page," "create a group," and "edit user preferences." </p> + * <p> Commands come in two flavors: "static" and "targeted." </p> + * <ul> + * <li><strong>Static commands</strong> are exactly what they sound like: static. They are <code>final</code>, threadsafe, and immutable. + * They have no intrinsic idea of the context they are acting in. For example, the static command {@link org.apache.wiki.ui.PageCommand#VIEW} embodies the + * idea of viewing a page — but exactly <em>which</em> page is left undefined. Static commands exist so that they can be freely + * shared and passed around without incurring the penalties of object creation. Static commands are a lot like naked request contexts + * ("edit", "view", etc.) except that they include additional, essential properties such as the associated URL pattern and content JSP.</li> + * <li><strong>Targeted commands</strong> "decorate" static commands by scoping a static Command at a specific target such as a WikiPage or + * GroupPrincipal. Targeted commands are created by calling an existing Command's {@link #targetedCommand(Object)} and supplying the target + * object. Implementing classes generally require a specific target type. For example, the {@link org.apache.wiki.ui.PageCommand} class requires that the + * target object be of type {@link org.apache.wiki.api.core.Page}.</li> + * </ul> + * <p> Concrete implementations of Command include: </p> + * <ul> + * <li><strong>PageCommand</strong>: commands for editing, renaming, and viewing pages</li> + * <li><strong>GroupCommand</strong>: commands for viewing, editing and + * deleting wiki groups</li> + * <li><strong>WikiCommand</strong>: commands for wiki-wide operations such as + * creating groups, editing preferences and profiles, and logging in/out</li> + * <li><strong>RedirectCommand</strong>: commands for redirections to off-site + * special pages</li> + * </ul> + * <p> + * For a given targeted Command, its {@link #getTarget()} method will return a non-<code>null</code> value. In addition, its + * {@link #requiredPermission()} method will generally also return a non-<code>null</code> value. It is each implementation's responsibility + * to construct and store the correct Permission for a given Command and Target. For example, when PageCommand.VIEW is targeted at the + * WikiPage <code>Main</code>, the Command's associated permission is <code>PagePermission "<em>theWiki</em>:Main", "view".</code></p> + * <p>Static Commands, and targeted Commands that do not require specific permissions to execute, return a <code>null</code> result for + * {@link #requiredPermission()}.</p> + * @since 2.4.22 + */ +public interface Command { + + /** + * Creates and returns a targeted Command by combining a target, such as a WikiPage or GroupPrincipal into the existing Command. + * Subclasses should check to make sure the supplied <code>target</code> object is of the correct type. This method is guaranteed + * to return a non-<code>null</code> Command (unless the target is an incorrect type). + * + * @param target the object to combine, such as a GroupPrincipal or WikiPage + * @return the new, targeted Command + * @throws IllegalArgumentException if the target is not of the correct type + */ + Command targetedCommand( Object target ); + + /** + * Returns the content template associated with a Command, such as <code>PreferencesContent.jsp</code>. For Commands that are not + * page-related, this method will always return <code>null</code>. <em>Calling methods should always check to see if the result + * of this method is <code>null</code></em>. + * + * @return the content template + */ + String getContentTemplate(); + + /** + * Returns the JSP associated with the Command. The JSP is a "local" JSP within the JSPWiki webapp; it is not a general HTTP URL. + * If it exists, the JSP will be expressed relative to the webapp root, without a leading slash. This method is guaranteed to return + * a non-<code>null</code> result, although in some cases the result may be an empty string. + * + * @return the JSP or url associated with the wiki command + */ + String getJSP(); + + /** + * Returns the human-friendly name for this command. + * + * @return the name + */ + String getName(); + + /** + * Returns the name of the request context (e.g. VIEW) associated with this Command. This method is guaranteed to return a + * non-<code>null</code> String. + * + * @return the request context + */ + String getRequestContext(); + + /** + * Returns the Permission required to successfully execute this Command. If no Permission is requred, this method returns + * <code>null</code>. For example, the static command {@link org.apache.wiki.ui.PageCommand#VIEW} doesn't require a permission because + * it isn't referring to a particular WikiPage. However, if this command targets a WikiPage called <code>Main</code>(via + * {@link org.apache.wiki.ui.PageCommand#targetedCommand(Object)}, the resulting Command would require the permission + * <code>PagePermission "<em>yourWiki</em>:Main", "view"</code>. + * + * @return the required permission, or <code>null</code> if not required + */ + Permission requiredPermission(); + + /** + * Returns the target associated with a Command, if it was created with one. Commands created with {@link #targetedCommand(Object)} will + * <em>always</em> return a non-<code>null</code> object. <em>Calling methods should always check to see if the result of this method + * is <code>null</code></em>. + * + * @return the wiki page + */ + Object getTarget(); + + /** + * Returns the URL pattern associated with this Command. This method is guaranteed to return a non-<code>null</code> String. + * + * @return the URL pattern + */ + String getURLPattern(); + +} diff --git a/jspwiki-api/src/main/java/org/apache/wiki/api/core/Context.java b/jspwiki-api/src/main/java/org/apache/wiki/api/core/Context.java new file mode 100644 index 0000000..17f837e --- /dev/null +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/core/Context.java @@ -0,0 +1,239 @@ +/* + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + */ +package org.apache.wiki.api.core; + +import javax.servlet.http.HttpServletRequest; +import java.security.Principal; + + +/** + * <p>Provides state information throughout the processing of a page. A Context is born when the JSP pages that are the main entry + * points, are invoked. The JSPWiki engine creates the new Context, which basically holds information about the page, the + * handling engine, and in which context (view, edit, etc) the call was done.</p> + * <p>A Context also provides request-specific variables, which can be used to communicate between plugins on the same page, or + * between different instances of the same plugin. A Context variable is valid until the processing of the WikiPage has ended. For + * an example, please see the Counter plugin.</p> + * <p>When a Context is created, it automatically associates a {@link Session} object with the user's + * HttpSession. The Session contains information about the user's authentication status, and is consulted by {@link #getCurrentUser()} + * object.</p> + * <p>Do not cache the WikiPage object that you get from the WikiContext; always use getPage()!</p> + * + * @see org.apache.wiki.plugin.Counter + */ +public interface Context extends Cloneable /*, Command*/ { + + /** + * Returns the WikiPage that is being handled. + * + * @return the WikiPage which was fetched. + */ + Page getPage(); + + /** + * Sets the WikiPage that is being handled. + * + * @param WikiPage The wikipage + * @since 2.1.37. + */ + void setPage( Page WikiPage ); + + /** + * Gets a reference to the real WikiPage 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 WikiPage added with InsertPageTag, you should consider what you want to + * do - do you wish to really reference the "master" WikiPage or the included page. + * <p> + * For example, in the default template, there is a WikiPage called "LeftMenu". Whenever you access a page, e.g. "Main", the master + * WikiPage 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 org.apache.wiki.tags.InsertPageTag + * @see org.apache.wiki.parser.JSPWikiMarkupParser + */ + Page getRealPage(); + + /** + * Sets a reference to the real WikiPage whose content is currently being rendered. + * <p> + * Sometimes you may want to render the WikiPage using some other page's context. In those cases, it is highly recommended that you set + * the setRealPage() to point at the real WikiPage 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 WikiPage added + * with InsertPageTag, you should consider what you want to do - do you wish to really reference the "master" WikiPage or the included + * page. + * + * @param WikiPage The real WikiPage which is being rendered. + * @return The previous real page + * @since 2.3.14 + * @see org.apache.wiki.tags.InsertPageTag + */ + Page setRealPage( Page WikiPage ); + + /** + * Returns the handling engine. + * + * @return The wikiengine owning this context. + */ + Engine getEngine(); + + /** + * Sets the request context. See above for the different request contexts (VIEW, EDIT, etc.) + * + * @param context The request context (one of the predefined contexts.) + */ + void setRequestContext( String context ); + + /** + * Gets a previously set variable. + * + * @param key The variable name. + * @return The variable contents. + */ + < T > T getVariable( String key ); + + /** + * Sets a variable. The variable is valid while the WikiContext is valid, i.e. while WikiPage processing continues. The variable data + * is discarded once the WikiPage processing is finished. + * + * @param key The variable name. + * @param data The variable value. + */ + void setVariable( String key, Object data ); + + /** + * This is just a simple helper method which will first check the context if there is already an override in place, and if there is not, + * it will then check the given properties. + * + * @param key What key are we searching for? + * @param defValue Default value for the boolean + * @return {@code true} or {@code false}. + */ + boolean getBooleanWikiProperty( String key, boolean defValue ); + + /** + * 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. + */ + 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. + */ + HttpServletRequest getHttpRequest(); + + /** + * Sets the template to be used for this request. + * + * @param dir The template name + * @since 2.1.15. + */ + void setTemplate( String dir ); + + /** + * Gets the template that is to be used throughout this request. + * + * @since 2.1.15. + * @return template name + */ + String getTemplate(); + + /** + * Returns the Session associated with the context. This method is guaranteed to always return a valid Session. + * If this context was constructed without an associated HttpServletRequest, it will return a guest session. + * + * @return The Session associate with this context. + */ + Session getWikiSession(); + + /** + * Convenience method that gets the current user. Delegates the lookup to the Session associated with this Context. + * May return null, in case the current user has not yet been determined; or this is an internal system. If the Session has not + * been set, <em>always</em> returns null. + * + * @return The current user; or maybe null in case of internal calls. + */ + Principal getCurrentUser(); + + /** + * 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. + */ + boolean hasAdminPermissions(); + + /** + * A shortcut to generate a VIEW url. + * + * @param WikiPage The WikiPage to which to link. + * @return An URL to the page. This honours the current absolute/relative setting. + */ + String getViewURL( String WikiPage ); + + /** + * Figure out to which WikiPage we are really going to. Considers special WikiPage names from the jspwiki.properties, and possible aliases. + * + * @return A complete URL to the new WikiPage to redirect to + * @since 2.2 + */ + String getRedirectURL(); + + /** + * Creates an URL for the given request context. + * + * @param context e.g. WikiContext.EDIT + * @param page The WikiPage to which to link + * @return An URL to the page. + */ + default String getURL( final String context, final String page ) { + return getURL( context, page, null ); + } + + /** + * Returns an URL from a page. It this Context 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 WikiPage to which to link + * @param params A list of parameters, separated with "&" + * + * @return An URL to the given context and page. + */ + default String getURL( final String context, final String page, final String params ) { + // FIXME: is rather slow + return getEngine().getURL( context, page, params ); + } + + /** + * Returns the Command associated with this Context. + * + * @return the command + */ + //Command getCommand(); + +} diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/core/Engine.java b/jspwiki-api/src/main/java/org/apache/wiki/api/core/Engine.java similarity index 100% rename from jspwiki-main/src/main/java/org/apache/wiki/api/core/Engine.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/core/Engine.java diff --git a/jspwiki-api/src/main/java/org/apache/wiki/api/core/Page.java b/jspwiki-api/src/main/java/org/apache/wiki/api/core/Page.java new file mode 100644 index 0000000..a455984 --- /dev/null +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/core/Page.java @@ -0,0 +1,183 @@ +/* + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + */ +package org.apache.wiki.api.core; + +import java.util.Date; +import java.util.Map; + + +public interface Page extends Cloneable { + + /** "Summary" is a short summary of the page. It is a String. */ + String DESCRIPTION = "summary"; + + /** A special variable name for storing a page alias. */ + String ALIAS = "alias"; + + /** A special variable name for storing a redirect note */ + String REDIRECT = "redirect"; + + /** A special variable name for storing the author. */ + String AUTHOR = "author"; + + /** A special variable name for storing a changenote. */ + String CHANGENOTE = "changenote"; + + /** A special variable name for storing a viewcount. */ + String VIEWCOUNT = "viewcount"; + + /** + * Returns the name of the page. + * + * @return The page name. + */ + String getName(); + + /** + * Returns the date when this page was last modified. + * + * @return The last modification date + */ + Date getLastModified(); + + /** + * Sets the last modification date. In general, this is only changed by the provider. + * + * @param date The date + */ + void setLastModified( Date date ); + + /** + * Sets the page version. In general, this is only changed by the provider. + * + * @param version The version number + */ + void setVersion( int version ); + + /** + * Returns the version that this WikiPage instance represents. + * + * @return the version number of this page. + */ + int getVersion(); + + /** + * Returns the size of the page. + * + * @return the size of the page. + * @since 2.1.109 + */ + long getSize(); + + /** + * Sets the size. Typically called by the provider only. + * + * @param size The size of the page. + * @since 2.1.109 + */ + void setSize( long size ); + + /** + * Sets the author of the page. Typically called only by the provider. + * + * @param author The author name. + */ + void setAuthor( String author ); + + /** + * Returns author name, or null, if no author has been defined. + * + * @return Author name, or possibly null. + */ + String getAuthor(); + + /** + * Returns the wiki name for this page + * + * @return The name of the wiki. + */ + String getWiki(); + + /** This method will remove all metadata from the page. */ + void invalidateMetadata(); + + /** + * Returns <code>true</code> if the page has valid metadata; that is, it has been parsed. Note that this method is a kludge to + * support our pre-3.0 metadata system, and as such will go away with the new API. + * + * @return true, if the page has metadata. + */ + boolean hasMetadata(); + + /** Sets the metadata flag to true. Never call. */ + void setHasMetadata(); + + /** + * 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. + */ + < T > T getAttribute( String key ); + + /** + * Sets an metadata attribute. + * + * @see #getAttribute(String) + * @param key The key for the attribute used to fetch the attribute later on. + * @param attribute The attribute value + */ + void setAttribute( String key, Object attribute ); + + /** + * 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 + */ + < T > T removeAttribute( String key ); + + /** + * 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. + */ + Map< String, Object > getAttributes(); + + /** + * 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. + */ + //Acl getAcl(); + + /** + * Sets the Acl for this page. Note that method does <em>not</em> persist the Acl itself to back-end storage or in page markup; + * it merely sets the internal field that stores the Acl. To persist the Acl, callers should invoke + * {@link org.apache.wiki.auth.acl.AclManager#setPermissions(org.apache.wiki.api.core.Page, org.apache.wiki.api.core.Acl)}. + * + * @param acl The Acl to set + */ + //void setAcl( Acl acl ); + +} diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/core/Session.java b/jspwiki-api/src/main/java/org/apache/wiki/api/core/Session.java similarity index 100% rename from jspwiki-main/src/main/java/org/apache/wiki/api/core/Session.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/core/Session.java diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/core/package.html b/jspwiki-api/src/main/java/org/apache/wiki/api/core/package.html similarity index 100% rename from jspwiki-main/src/main/java/org/apache/wiki/api/core/package.html rename to jspwiki-api/src/main/java/org/apache/wiki/api/core/package.html diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/FilterException.java b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/FilterException.java similarity index 96% rename from jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/FilterException.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/FilterException.java index 27ca868..934d19c 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/FilterException.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/FilterException.java @@ -33,7 +33,7 @@ public class FilterException extends WikiException { * * @param msg exception message. */ - public FilterException( String msg ) { + public FilterException( final String msg ) { super( msg ); } diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/NoRequiredPropertyException.java b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/NoRequiredPropertyException.java similarity index 94% rename from jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/NoRequiredPropertyException.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/NoRequiredPropertyException.java index 27ecfa7..0bcf30f 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/NoRequiredPropertyException.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/NoRequiredPropertyException.java @@ -36,7 +36,7 @@ public class NoRequiredPropertyException extends WikiException { * @param msg Message to show * @param key The key of the property in question. */ - public NoRequiredPropertyException( String msg, String key ) { + public NoRequiredPropertyException( final String msg, final String key ) { super( msg + ": key=" + key ); } diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/NoSuchVariableException.java b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/NoSuchVariableException.java similarity index 95% rename from jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/NoSuchVariableException.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/NoSuchVariableException.java index d5b247d..2e7fd91 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/NoSuchVariableException.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/NoSuchVariableException.java @@ -32,7 +32,7 @@ public class NoSuchVariableException extends WikiException { * * @param msg Message to show */ - public NoSuchVariableException( String msg ) { + public NoSuchVariableException( final String msg ) { super( msg ); } diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/PluginException.java b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/PluginException.java similarity index 92% rename from jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/PluginException.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/PluginException.java index 6d25cf9..b0ddf11 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/PluginException.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/PluginException.java @@ -33,7 +33,7 @@ public class PluginException extends WikiException { * * @param message exception message. */ - public PluginException( String message ) { + public PluginException( final String message ) { super( message ); m_throwable = null; } @@ -44,7 +44,7 @@ public class PluginException extends WikiException { * @param message exception message. * @param original The original exception. */ - public PluginException( String message, Throwable original ) { + public PluginException( final String message, final Throwable original ) { super( message, original ); m_throwable = original; } diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/ProviderException.java b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/ProviderException.java similarity index 96% rename from jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/ProviderException.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/ProviderException.java index 4059224..0fda596 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/ProviderException.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/ProviderException.java @@ -33,7 +33,7 @@ public class ProviderException extends WikiException { * * @param msg exception message. */ - public ProviderException( String msg ) { + public ProviderException( final String msg ) { super( msg ); } diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/RedirectException.java b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/RedirectException.java similarity index 95% rename from jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/RedirectException.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/RedirectException.java index a4b6a31..98b6c23 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/RedirectException.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/RedirectException.java @@ -36,7 +36,7 @@ public class RedirectException extends FilterException { * @param msg The message for the exception * @param redirect The redirect URI. */ - public RedirectException( String msg, String redirect ) { + public RedirectException( final String msg, final String redirect ) { super( msg ); m_where = redirect; } diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/WikiException.java b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/WikiException.java similarity index 92% copy from jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/WikiException.java copy to jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/WikiException.java index c807a56..0e3b6d1 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/WikiException.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/WikiException.java @@ -33,7 +33,7 @@ public class WikiException extends Exception { * * @param msg the message in the exception. */ - public WikiException( String msg ) { + public WikiException( final String msg ) { super( msg ); } @@ -43,7 +43,7 @@ public class WikiException extends Exception { * @param msg the message in the exception. * @param cause the cause of the exception */ - public WikiException( String msg, Throwable cause ) { + public WikiException( final String msg, final Throwable cause ) { super( msg, cause ); } diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/WikiI18nException.java b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/WikiI18nException.java similarity index 96% rename from jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/WikiI18nException.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/WikiI18nException.java index f83448b..f38fab7 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/WikiI18nException.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/WikiI18nException.java @@ -38,7 +38,7 @@ public class WikiI18nException extends WikiException { * @param key the key corresponding to the i18n message in the exception. * @param args arguments needed to construct the i18n message associated with the exception. */ - public WikiI18nException( String key, Object... args ) { + public WikiI18nException( final String key, final Object... args ) { super( key ); this.args = args; } diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/package.html b/jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/package.html similarity index 100% rename from jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/package.html rename to jspwiki-api/src/main/java/org/apache/wiki/api/exceptions/package.html diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/filters/BasicPageFilter.java b/jspwiki-api/src/main/java/org/apache/wiki/api/filters/BasicPageFilter.java similarity index 100% rename from jspwiki-main/src/main/java/org/apache/wiki/api/filters/BasicPageFilter.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/filters/BasicPageFilter.java diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/filters/PageFilter.java b/jspwiki-api/src/main/java/org/apache/wiki/api/filters/PageFilter.java similarity index 89% rename from jspwiki-main/src/main/java/org/apache/wiki/api/filters/PageFilter.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/filters/PageFilter.java index 36c906d..5ef3da8 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/filters/PageFilter.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/filters/PageFilter.java @@ -18,7 +18,7 @@ */ package org.apache.wiki.api.filters; -import org.apache.wiki.WikiContext; +import org.apache.wiki.api.core.Context; import org.apache.wiki.api.core.Engine; import org.apache.wiki.api.exceptions.FilterException; @@ -53,12 +53,12 @@ public interface PageFilter { * 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 context The current context. * @param content WikiMarkup. * @return The modified wikimarkup content. * @throws FilterException If something goes wrong. Throwing this causes the entire page processing to be abandoned. */ - default String preTranslate( final WikiContext wikiContext, final String content ) throws FilterException { + default String preTranslate( final Context context, final String content ) throws FilterException { return content; } @@ -71,7 +71,7 @@ public interface PageFilter { * @return The modified HTML * @throws FilterException If something goes wrong. Throwing this causes the entire page processing to be abandoned. */ - default String postTranslate( final WikiContext wikiContext, final String htmlContent ) throws FilterException { + default String postTranslate( final Context wikiContext, final String htmlContent ) throws FilterException { return htmlContent; } @@ -83,7 +83,7 @@ public interface PageFilter { * @return The modified wikimarkup * @throws FilterException If something goes wrong. Throwing this causes the entire page processing to be abandoned. */ - default String preSave( final WikiContext wikiContext, final String content ) throws FilterException { + default String preSave( final Context wikiContext, final String content ) throws FilterException { return content; } @@ -97,7 +97,7 @@ public interface PageFilter { * @param content The content which was just stored. * @throws FilterException If something goes wrong. As the page is already saved, This is just logged. */ - default void postSave( final WikiContext wikiContext, final String content ) throws FilterException {} + default void postSave( final Context wikiContext, final String content ) throws FilterException {} /** * Called for every filter, e.g. on wiki engine shutdown. Use this if you have to diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/filters/package.html b/jspwiki-api/src/main/java/org/apache/wiki/api/filters/package.html similarity index 100% rename from jspwiki-main/src/main/java/org/apache/wiki/api/filters/package.html rename to jspwiki-api/src/main/java/org/apache/wiki/api/filters/package.html diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/package.html b/jspwiki-api/src/main/java/org/apache/wiki/api/package.html similarity index 100% copy from jspwiki-main/src/main/java/org/apache/wiki/api/package.html copy to jspwiki-api/src/main/java/org/apache/wiki/api/package.html diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/plugin/InitializablePlugin.java b/jspwiki-api/src/main/java/org/apache/wiki/api/plugin/InitializablePlugin.java similarity index 100% rename from jspwiki-main/src/main/java/org/apache/wiki/api/plugin/InitializablePlugin.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/plugin/InitializablePlugin.java diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/plugin/ParserStagePlugin.java b/jspwiki-api/src/main/java/org/apache/wiki/api/plugin/ParserStagePlugin.java similarity index 90% rename from jspwiki-main/src/main/java/org/apache/wiki/api/plugin/ParserStagePlugin.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/plugin/ParserStagePlugin.java index cea2144..f426ec0 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/plugin/ParserStagePlugin.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/plugin/ParserStagePlugin.java @@ -18,7 +18,7 @@ */ package org.apache.wiki.api.plugin; -import org.apache.wiki.WikiContext; +import org.apache.wiki.api.core.Context; import java.util.Map; @@ -35,6 +35,6 @@ public interface ParserStagePlugin { * @param context WikiContext, as usual. * @param params Parsed parameters for the plugin. */ - void executeParser( PluginElement element, WikiContext context, Map< String, String > params ); + void executeParser( PluginElement element, Context context, Map< String, String > params ); } diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/plugin/WikiPlugin.java b/jspwiki-api/src/main/java/org/apache/wiki/api/plugin/Plugin.java similarity index 61% copy from jspwiki-main/src/main/java/org/apache/wiki/api/plugin/WikiPlugin.java copy to jspwiki-api/src/main/java/org/apache/wiki/api/plugin/Plugin.java index 2457c50..950496a 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/plugin/WikiPlugin.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/plugin/Plugin.java @@ -18,43 +18,35 @@ */ package org.apache.wiki.api.plugin; -import java.util.Map; - -import org.apache.wiki.WikiContext; +import org.apache.wiki.api.core.Context; import org.apache.wiki.api.exceptions.PluginException; +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. - */ +public interface Plugin { + + /** Name of the default plugin resource bundle. */ 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. + * 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. + * 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. - * + * @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. */ - String execute( WikiContext context, Map< String, String > params ) throws PluginException; + String execute( Context context, Map< String, String > params ) throws PluginException; } diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/plugin/PluginElement.java b/jspwiki-api/src/main/java/org/apache/wiki/api/plugin/PluginElement.java similarity index 94% rename from jspwiki-main/src/main/java/org/apache/wiki/api/plugin/PluginElement.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/plugin/PluginElement.java index ee7e33b..a7c2647 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/plugin/PluginElement.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/plugin/PluginElement.java @@ -18,7 +18,7 @@ */ package org.apache.wiki.api.plugin; -import org.apache.wiki.WikiContext; +import org.apache.wiki.api.core.Context; import org.apache.wiki.api.exceptions.PluginException; import java.util.Map; @@ -73,7 +73,7 @@ public interface PluginElement { * @param context WikiContext in which the plugin is executed. Must NOT be null. * @return plugin contents. */ - String invoke( WikiContext context ); + String invoke( Context context ); /** * Executes the executeParse() method. @@ -81,6 +81,6 @@ public interface PluginElement { * @param context The WikiContext * @throws PluginException If something goes wrong. */ - void executeParse( WikiContext context ) throws PluginException; + void executeParse( Context context ) throws PluginException; } diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/plugin/package.html b/jspwiki-api/src/main/java/org/apache/wiki/api/plugin/package.html similarity index 100% rename from jspwiki-main/src/main/java/org/apache/wiki/api/plugin/package.html rename to jspwiki-api/src/main/java/org/apache/wiki/api/plugin/package.html diff --git a/jspwiki-api/src/main/java/org/apache/wiki/api/providers/AttachmentProvider.java b/jspwiki-api/src/main/java/org/apache/wiki/api/providers/AttachmentProvider.java new file mode 100644 index 0000000..21f7fba --- /dev/null +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/providers/AttachmentProvider.java @@ -0,0 +1,145 @@ +/* + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + */ +package org.apache.wiki.api.providers; + +import org.apache.wiki.api.core.Attachment; +import org.apache.wiki.api.core.Page; +import org.apache.wiki.api.exceptions.ProviderException; +import org.apache.wiki.api.search.QueryItem; + +import java.io.IOException; +import java.io.InputStream; +import java.util.Collection; +import java.util.Date; +import java.util.List; + + +/** + * Defines an attachment provider - a class which is capable of saving binary data as attachments. + * <P> + * The difference between this class and WikiPageProvider is that there PageProviders handle Unicode text, whereas we handle binary data. + * While there are quite a lot of similarities in how we handle things, many providers can really use just one. In addition, + * since binary files can be really large, we rely on Input/OutputStreams. + */ +public interface AttachmentProvider extends WikiProvider { + + /** + * Put new attachment data. + * + * @param att Attachment object to add new data to + * @param data The stream from which the provider should read the data + * @throws IOException If writing fails + * @throws ProviderException If there are other errors. + */ + void putAttachmentData( Attachment att, InputStream data ) throws ProviderException, IOException; + + /** + * Get attachment data. + * + * @param att The attachment + * @return An InputStream which you contains the raw data of the object. It's your responsibility to close it. + * @throws ProviderException If the attachment cannot be found + * @throws IOException If the attachment cannot be opened + */ + InputStream getAttachmentData( Attachment att ) throws ProviderException, IOException; + + /** + * Lists all attachments attached to a page. + * + * @param page The page to list the attachments from. + * @return A collection of Attachment objects. May be empty, but never null. + * @throws ProviderException If something goes wrong when listing the attachments. + */ + List< Attachment > listAttachments( Page page ) throws ProviderException; + + /** + * Finds attachments based on the query. + * + * @param query An array of QueryItem objects to search for + * @return A Collection of Attachment objects. May be empty, but never null. + */ + Collection< Attachment > findAttachments( QueryItem[] query ); + + /** + * Lists changed attachments since given date. Can also be used to fetch a list of all pages. + * <P> + * This is different from WikiPageProvider, where you basically get a list of all pages, then sort them locally. However, since some + * providers can be more efficient in locating recently changed files (like any database) than our non-optimized Java code, it makes + * more sense to fetch the whole list this way. + * <P> + * To get all files, call this with Date(0L); + * + * @param timestamp List all files from this date onward. + * @return A List of Attachment objects, in most-recently-changed first order. + * @throws ProviderException If something goes wrong. + */ + List< Attachment > listAllChanged( Date timestamp ) throws ProviderException; + + /** + * Returns info about an attachment. + * + * @param page The parent page + * @param name The name of the attachment + * @param version The version of the attachment (it's okay to use WikiPage.LATEST_VERSION to find the latest one) + * @return An attachment object + * @throws ProviderException If the attachment cannot be found or some other error occurs. + */ + Attachment getAttachmentInfo( Page page, String name, int version ) throws ProviderException; + + /** + * Returns version history. Each element should be an Attachment. + * + * @param att The attachment for which to find the version history for. + * @return A List of Attachment objects. + */ + List< Attachment > getVersionHistory( Attachment att ); + + /** + * Removes a specific version from the repository. The implementations should really do no more security checks, since that is the + * domain of the AttachmentManager. Just delete it as efficiently as you can. + * + * @since 2.0.19. + * @param att Attachment to be removed. The version field is checked, and thus only that version is removed. + * @throws ProviderException If the attachment cannot be removed for some reason. + */ + void deleteVersion( Attachment att ) throws ProviderException; + + /** + * Removes an entire page from the repository. The implementations should really do no more security checks, since that is the domain + * of the AttachmentManager. Just delete it as efficiently as you can. You should also delete any auxiliary files and directories + * that belong to this attachment, IF they were created by this provider. + * + * @since 2.0.17. + * @param att Attachment to delete. + * @throws ProviderException If the page could not be removed for some reason. + */ + void deleteAttachment( Attachment att ) throws ProviderException; + + /** + * Move all the attachments for a given page so that they are attached to a new page. + * + * @param oldParent Name of the page we are to move the attachments from. + * @param newParent Name of the page we are to move the attachments to. + * @throws ProviderException If the attachments could not be moved for some reason. + */ + void moveAttachmentsForPage( String oldParent, String newParent ) throws ProviderException; + +} + + diff --git a/jspwiki-api/src/main/java/org/apache/wiki/api/providers/PageProvider.java b/jspwiki-api/src/main/java/org/apache/wiki/api/providers/PageProvider.java new file mode 100644 index 0000000..6bd238a --- /dev/null +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/providers/PageProvider.java @@ -0,0 +1,170 @@ +/* + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + */ +package org.apache.wiki.api.providers; + +import org.apache.wiki.api.core.Page; +import org.apache.wiki.api.exceptions.ProviderException; +import org.apache.wiki.api.search.QueryItem; +import org.apache.wiki.api.search.SearchResult; + +import java.util.Collection; +import java.util.Date; +import java.util.List; + + +/** + * Each Wiki page provider should implement this interface. + * <P> + * You can build whatever page providers based on this, just leave the unused methods do something useful. + * <P> + * WikiPageProvider uses Strings and ints to refer to pages. This may be a bit odd, since WikiAttachmentProviders all use Attachment + * instead of name/version. We will perhaps modify these in the future. In the mean time, name/version is quite sufficient. + * <P> + * FIXME: In reality we should have an AbstractWikiPageProvider, which would provide intelligent backups for subclasses. + */ +public interface PageProvider extends WikiProvider { + + /** + * Attempts to save the page text for page "page". Note that the provider creates a new version regardless of what the version + * parameter of the WikiPage is. + * + * @param page The WikiPage to save + * @param text The text to save. + * @throws ProviderException If something goes wrong. + */ + void putPageText( Page page, String text ) throws ProviderException; + + /** + * Return true, if page exists. + * + * @param page The page name. + * @return true, if the page exists; false otherwise. + */ + boolean pageExists( String page ); + + /** + * Return true, if page with a particular version exists. + * + * @param page The page name to check for + * @param version The version to check + * @return True, if page exists; false otherwise. + */ + boolean pageExists( String page, int version ); + + /** + * Finds pages based on the query. Only applicable to providers which implement the FastSearch interface. Otherwise JSPWiki + * will use its internal cache. + * <p> + * This method should really be a part of the FastSearch IF. + * + * @param query An array of QueryItems to match + * @return A Collection of WikiPages. + */ + Collection< SearchResult > findPages( QueryItem[] query ); + + /** + * Returns info about the page. + * + * @return A filled WikiPage. + * @param page The page name + * @param version The version number + * @throws ProviderException If something goes wrong. + */ + Page getPageInfo( String page, int version ) throws ProviderException; + + /** + * Returns all pages. Each element in the returned Collection should be a WikiPage. + * + * @return A collection of WikiPages + * @throws ProviderException If something goes wrong. + */ + Collection< Page > getAllPages() throws ProviderException; + + /** + * Gets a list of recent changes. + * + * @param date The date to check from + * @return A Collection of WikiPages + * @since 1.6.4 + */ + Collection< Page > getAllChangedSince( Date date ); + + /** + * Gets the number of pages. + * + * @return The number of pages in the repository + * @throws ProviderException If something goes wrong + * @since 1.6.4 + */ + int getPageCount() throws ProviderException; + + /** + * Returns version history. Each element should be a WikiPage. + * + * @param page The name of the page to get the history from. + * @return A collection of WikiPages. + * @throws ProviderException If something goes wrong. + */ + List< Page > getVersionHistory( String page ) throws ProviderException; + + /** + * Gets a specific version out of the repository. + * + * @param page Name of the page to fetch. + * @param version Version of the page to fetch. + * @return The content of the page, or null, if the page does not exist. + * @throws ProviderException If something goes wrong. + */ + String getPageText( String page, int version ) throws ProviderException; + + /** + * Removes a specific version from the repository. The implementations should really do no more security checks, since that is the + * domain of the PageManager. Just delete it as efficiently as you can. + * + * @since 2.0.17. + * @param pageName Name of the page to be removed. + * @param version Version of the page to be removed. May be LATEST_VERSION. + * @throws ProviderException If the page cannot be removed for some reason. + */ + void deleteVersion( String pageName, int version ) throws ProviderException; + + /** + * Removes an entire page from the repository. The implementations should really do no more security checks, since that is the domain + * of the PageManager. Just delete it as efficiently as you can. You should also delete any auxiliary files that belong to this page, + * IF they were created by this provider. + * + * <P>The reason why this is named differently from deleteVersion() (logically, this method should be an overloaded version) is that + * I want to be absolutely sure I don't accidentally use the wrong method. With overloading something like that happens sometimes... + * + * @since 2.0.17. + * @param pageName Name of the page to be removed completely. + * @throws ProviderException If the page could not be removed for some reason. + */ + void deletePage( String pageName ) throws ProviderException; + + /** + * Move a page + * + * @param from Name of the page to move. + * @param to New name of the page. + * @throws ProviderException If the page could not be moved for some reason. + */ + void movePage( String from, String to ) throws ProviderException; + +} \ No newline at end of file diff --git a/jspwiki-api/src/main/java/org/apache/wiki/api/providers/WikiProvider.java b/jspwiki-api/src/main/java/org/apache/wiki/api/providers/WikiProvider.java new file mode 100644 index 0000000..eb65de3 --- /dev/null +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/providers/WikiProvider.java @@ -0,0 +1,57 @@ +/* + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + */ +package org.apache.wiki.api.providers; + +import org.apache.wiki.api.core.Engine; +import org.apache.wiki.api.exceptions.NoRequiredPropertyException; + +import java.io.IOException; +import java.util.Properties; + + +/** + * A generic Wiki provider for all sorts of things that the Wiki can store. + * + * @since 2.0 + */ +public interface WikiProvider { + + /** Passing this to any method should get the latest version */ + int LATEST_VERSION = -1; + + /** + * Initializes the page provider. + * + * @param engine Engine to own this provider + * @param properties A set of properties used to initialize this provider + * @throws NoRequiredPropertyException If the provider needs a property which is not found in the property set + * @throws IOException If there is an IO problem + */ + void initialize( Engine engine, Properties properties ) throws NoRequiredPropertyException, IOException; + + /** + * Return a valid HTML string for information. May be anything. + * @since 1.6.4 + * @return A string describing the provider. + */ + String getProviderInfo(); + +} + + diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/package.html b/jspwiki-api/src/main/java/org/apache/wiki/api/providers/package.html similarity index 89% copy from jspwiki-main/src/main/java/org/apache/wiki/api/package.html copy to jspwiki-api/src/main/java/org/apache/wiki/api/providers/package.html index cb02016..363e83e 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/package.html +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/providers/package.html @@ -21,12 +21,12 @@ <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -<title>JSPWiki's APIs</title> +<title>JSPWiki's Providers API</title> </head> <body> -JSPWiki's API package. +Page Providers' API package of JSPWiki. -This package holds all the APIs provided by JSPWiki. +This package holds JSPWiki's page provider API <h3>Package Specification</h3> diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/WikiException.java b/jspwiki-api/src/main/java/org/apache/wiki/api/search/QueryItem.java similarity index 54% copy from jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/WikiException.java copy to jspwiki-api/src/main/java/org/apache/wiki/api/search/QueryItem.java index c807a56..fb61671 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/WikiException.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/search/QueryItem.java @@ -16,35 +16,28 @@ specific language governing permissions and limitations under the License. */ -package org.apache.wiki.api.exceptions; +package org.apache.wiki.api.search; /** - * A generic Wiki exception. - * - * @since 2.0 + * This simple class just fulfils the role of a container for searches. It tells the word and whether it is requested or not. */ -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 ); - } - - /** - * Constructs an exception with a supplied cause. - * - * @param msg the message in the exception. - * @param cause the cause of the exception - */ - public WikiException( String msg, Throwable cause ) { - super( msg, cause ); - } +public class QueryItem { + + /** The word is required to be in the pages */ + public static final int REQUIRED = 1; + + /** The word may NOT be in the pages */ + public static final int FORBIDDEN = -1; + + /** The word should be in the pages, but the search engine may + use its own discretion. */ + public static final int REQUESTED = 0; + + /** The word that is being searched */ + public String word; + + /** The type of the word. See above for types. The default is REQUESTED. */ + public int type = REQUESTED; } diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/WikiException.java b/jspwiki-api/src/main/java/org/apache/wiki/api/search/SearchResult.java similarity index 59% rename from jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/WikiException.java rename to jspwiki-api/src/main/java/org/apache/wiki/api/search/SearchResult.java index c807a56..bd623ae 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/exceptions/WikiException.java +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/search/SearchResult.java @@ -16,35 +16,36 @@ specific language governing permissions and limitations under the License. */ -package org.apache.wiki.api.exceptions; +package org.apache.wiki.api.search; + +import org.apache.wiki.api.core.Page; /** - * A generic Wiki exception. - * - * @since 2.0 + * Defines a search result. */ -public class WikiException extends Exception { - - private static final long serialVersionUID = 3257290231723210803L; +public interface SearchResult { + + /** + * Return the page. + * + * @return the WikiPage object containing this result + */ + < P extends Page> P getPage(); /** - * Constructs an exception. + * Returns the score. * - * @param msg the message in the exception. + * @return A positive score value. Note that there is no upper limit for the score. */ - public WikiException( String msg ) { - super( msg ); - } - + int getScore(); + /** - * Constructs an exception with a supplied cause. - * - * @param msg the message in the exception. - * @param cause the cause of the exception + * Collection of XHTML fragments representing some contexts in which the match was made (a.k.a., "snippets"). + * + * @return the search results + * @since 2.4 */ - public WikiException( String msg, Throwable cause ) { - super( msg, cause ); - } + String[] getContexts(); } diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/package.html b/jspwiki-api/src/main/java/org/apache/wiki/api/search/package.html similarity index 87% rename from jspwiki-main/src/main/java/org/apache/wiki/api/package.html rename to jspwiki-api/src/main/java/org/apache/wiki/api/search/package.html index cb02016..f229707 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/package.html +++ b/jspwiki-api/src/main/java/org/apache/wiki/api/search/package.html @@ -21,12 +21,12 @@ <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> -<title>JSPWiki's APIs</title> +<title>JSPWiki's Search API</title> </head> <body> -JSPWiki's API package. +Search's API package of JSPWiki. -This package holds all the APIs provided by JSPWiki. +This package holds JSPWiki's API Search related classes used by the PageProviders <h3>Package Specification</h3> diff --git a/jspwiki-main/src/main/java/org/apache/wiki/api/plugin/WikiPlugin.java b/jspwiki-main/src/main/java/org/apache/wiki/api/plugin/WikiPlugin.java index 2457c50..30a3b1b 100644 --- a/jspwiki-main/src/main/java/org/apache/wiki/api/plugin/WikiPlugin.java +++ b/jspwiki-main/src/main/java/org/apache/wiki/api/plugin/WikiPlugin.java @@ -18,43 +18,28 @@ */ package org.apache.wiki.api.plugin; -import java.util.Map; - +import org.apache.log4j.Logger; import org.apache.wiki.WikiContext; +import org.apache.wiki.api.core.Context; import org.apache.wiki.api.exceptions.PluginException; +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. - */ - 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 interface WikiPlugin extends Plugin { + + /** {@inheritDoc} */ + @Override + default String execute( final Context context, final Map< String, String > params ) throws PluginException { + Logger.getLogger( WikiPlugin.class ).warn( this.getClass().getName() + " implements deprecated org.apache.wiki.api.plugin.WikiPlugin" ); + Logger.getLogger( WikiPlugin.class ).warn( "Please contact the plugin's author so there can be a new release of the plugin " + + "implementing the new org.apache.wiki.api.plugin.Plugin interface" ); + return execute( ( WikiContext )context, params ); + } + String execute( WikiContext context, Map< String, String > params ) throws PluginException; }
