org.apache.wiki.api.core

Interface Command

All Known Subinterfaces:

Context

public interface Command

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."

Commands come in two flavors: "static" and "targeted."

• Static commands are exactly what they sound like: static. They are final, threadsafe, and immutable. They have no intrinsic idea of the context they are acting in. For example, the static command org.apache.wiki.ui.PageCommand#VIEW embodies the idea of viewing a page — but exactly which 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.
• Targeted commands "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 targetedCommand(Object) and supplying the target object. Implementing classes generally require a specific target type. For example, the org.apache.wiki.ui.PageCommand class requires that the target object be of type Page.

Concrete implementations of Command include:

• PageCommand: commands for editing, renaming, and viewing pages
• GroupCommand: commands for viewing, editing and deleting wiki groups
• WikiCommand: commands for wiki-wide operations such as creating groups, editing preferences and profiles, and logging in/out
• RedirectCommand: commands for redirections to off-site special pages

For a given targeted Command, its getTarget() method will return a non-null value. In addition, its requiredPermission() method will generally also return a non-null 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 Main, the Command's associated permission is PagePermission "theWiki:Main", "view".

Static Commands, and targeted Commands that do not require specific permissions to execute, return a null result for requiredPermission().

Since:

2.4.22

Method Summary

Modifier and Type	Method and Description
java.lang.String	getContentTemplate() Returns the content template associated with a Command, such as PreferencesContent.jsp.
java.lang.String	getJSP() Returns the JSP associated with the Command.
java.lang.String	getName() Returns the human-friendly name for this command.
java.lang.String	getRequestContext() Returns the name of the request context (e.g.
java.lang.Object	getTarget() Returns the target associated with a Command, if it was created with one.
java.lang.String	getURLPattern() Returns the URL pattern associated with this Command.
java.security.Permission	requiredPermission() Returns the Permission required to successfully execute this Command.
Command	targetedCommand(java.lang.Object target) Creates and returns a targeted Command by combining a target, such as a WikiPage or GroupPrincipal into the existing Command.

Method Detail

targetedCommand

Command targetedCommand(java.lang.Object target)

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 target object is of the correct type. This method is guaranteed to return a non-null Command (unless the target is an incorrect type).

Parameters:

target - the object to combine, such as a GroupPrincipal or WikiPage

Returns:

the new, targeted Command

Throws:

java.lang.IllegalArgumentException - if the target is not of the correct type

getContentTemplate

java.lang.String getContentTemplate()

Returns the content template associated with a Command, such as PreferencesContent.jsp. For Commands that are not page-related, this method will always return null. Calling methods should always check to see if the result of this method is null.

Returns:

the content template

getJSP

java.lang.String getJSP()

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-null result, although in some cases the result may be an empty string.

Returns:

the JSP or url associated with the wiki command

getName

java.lang.String getName()

Returns the human-friendly name for this command.

Returns:

the name

getRequestContext

java.lang.String getRequestContext()

Returns the name of the request context (e.g. VIEW) associated with this Command. This method is guaranteed to return a non-null String.

Returns:

the request context

requiredPermission

java.security.Permission requiredPermission()

Returns the Permission required to successfully execute this Command. If no Permission is requred, this method returns null. For example, the static command 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 Main(via org.apache.wiki.ui.PageCommand#targetedCommand(Object), the resulting Command would require the permission PagePermission "yourWiki:Main", "view".

Returns:

the required permission, or null if not required

getTarget

java.lang.Object getTarget()

Returns the target associated with a Command, if it was created with one. Commands created with targetedCommand(Object) will always return a non-null object. Calling methods should always check to see if the result of this method is null.

Returns:

the wiki page

getURLPattern

java.lang.String getURLPattern()

Returns the URL pattern associated with this Command. This method is guaranteed to return a non-null String.

Returns:

the URL pattern