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

## Method Details

### targetedCommand

Command targetedCommand(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:
  `IllegalArgumentException` - if the target is not of the correct type

### getContentTemplate

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

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

String getName()
Returns the human-friendly name for this command.

Returns:
  the name

### getRequestContext

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

Permission requiredPermission()
Returns the Permission required to successfully execute this Command. If no Permission is required, 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

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

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

Returns:
  the URL pattern