Package org.apache.wiki.api.core

Interface Command

  • All Known Subinterfaces:
    Context
    All Known Implementing Classes:
    AbstractCommand, GroupCommand, PageCommand, RedirectCommand, WikiCommand, WikiContext
    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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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 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

        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