    001/*
    002    Licensed to the Apache Software Foundation (ASF) under one
    003    or more contributor license agreements.  See the NOTICE file
    004    distributed with this work for additional information
    005    regarding copyright ownership.  The ASF licenses this file
    006    to you under the Apache License, Version 2.0 (the
    007    "License"); you may not use this file except in compliance
    008    with the License.  You may obtain a copy of the License at
    009
    010       http://www.apache.org/licenses/LICENSE-2.0
    011
    012    Unless required by applicable law or agreed to in writing,
    013    software distributed under the License is distributed on an
    014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    015    KIND, either express or implied.  See the License for the
    016    specific language governing permissions and limitations
    017    under the License.
    018 */
    019package org.apache.wiki.api.core;
    020
    021import java.security.Permission;
    022
    023
    024/**
    025 * <p>Represents a logical "unit of work" that includes a request context, JSP, URLPattern, content template and (optionally) a target and
    026 * required security permission. Examples of Commands include "view a page," "create a group," and "edit user preferences." </p>
    027 * <p> Commands come in two flavors: "static" and "targeted." </p>
    028 * <ul>
    029 * <li><strong>Static commands</strong> are exactly what they sound like: static. They are <code>final</code>, threadsafe, and immutable.
    030 * They have no intrinsic idea of the context they are acting in. For example, the static command {@code org.apache.wiki.ui.PageCommand#VIEW} embodies the
    031 * idea of viewing a page &#8212; but exactly <em>which</em> page is left undefined. Static commands exist so that they can be freely
    032 * shared and passed around without incurring the penalties of object creation. Static commands are a lot like naked request contexts
    033 * ("edit", "view", etc.) except that they include additional, essential properties such as the associated URL pattern and content JSP.</li>
    034 * <li><strong>Targeted commands</strong> "decorate" static commands by scoping a static Command at a specific target such as a WikiPage or
    035 * GroupPrincipal. Targeted commands are created by calling an existing Command's {@link #targetedCommand(Object)} and supplying the target
    036 * object. Implementing classes generally require a specific target type. For example, the {@code org.apache.wiki.ui.PageCommand} class requires that the
    037 * target object be of type {@link org.apache.wiki.api.core.Page}.</li>
    038 * </ul>
    039 * <p> Concrete implementations of Command include: </p>
    040 * <ul>
    041 * <li><strong>PageCommand</strong>: commands for editing, renaming, and viewing pages</li>
    042 * <li><strong>GroupCommand</strong>: commands for viewing, editing and
    043 * deleting wiki groups</li>
    044 * <li><strong>WikiCommand</strong>: commands for wiki-wide operations such as
    045 * creating groups, editing preferences and profiles, and logging in/out</li>
    046 * <li><strong>RedirectCommand</strong>: commands for redirections to off-site
    047 * special pages</li>
    048 * </ul>
    049 * <p>
    050 * For a given targeted Command, its {@link #getTarget()} method will return a non-<code>null</code> value. In addition, its
    051 * {@link #requiredPermission()} method will generally also return a non-<code>null</code> value. It is each implementation's responsibility
    052 * to construct and store the correct Permission for a given Command and Target. For example, when PageCommand.VIEW is targeted at the
    053 * WikiPage <code>Main</code>, the Command's associated permission is <code>PagePermission "<em>theWiki</em>:Main", "view".</code></p>
    054 * <p>Static Commands, and targeted Commands that do not require specific permissions to execute, return a <code>null</code> result for
    055 * {@link #requiredPermission()}.</p>
    056 * @since 2.4.22
    057 */
    058public interface Command {
    059
    060    /**
    061     * Creates and returns a targeted Command by combining a target, such as a WikiPage or GroupPrincipal into the existing Command.
    062     * Subclasses should check to make sure the supplied <code>target</code> object is of the correct type. This method is guaranteed
    063     * to return a non-<code>null</code> Command (unless the target is an incorrect type).
    064     *
    065     * @param target the object to combine, such as a GroupPrincipal or WikiPage
    066     * @return the new, targeted Command
    067     * @throws IllegalArgumentException if the target is not of the correct type
    068     */
    069    Command targetedCommand( Object target );
    070
    071    /**
    072     * Returns the content template associated with a Command, such as <code>PreferencesContent.jsp</code>. For Commands that are not
    073     * page-related, this method will always return <code>null</code>. <em>Calling methods should always check to see if the result
    074     * of this method is <code>null</code></em>.
    075     *
    076     * @return the content template
    077     */
    078    String getContentTemplate();
    079
    080    /**
    081     * Returns the JSP associated with the Command. The JSP is a "local" JSP within the JSPWiki webapp; it is not a general HTTP URL.
    082     * If it exists, the JSP will be expressed relative to the webapp root, without a leading slash. This method is guaranteed to return
    083     * a non-<code>null</code> result, although in some cases the result may be an empty string.
    084     *
    085     * @return the JSP or url associated with the wiki command
    086     */
    087    String getJSP();
    088
    089    /**
    090     * Returns the human-friendly name for this command.
    091     *
    092     * @return the name
    093     */
    094    String getName();
    095
    096    /**
    097     * Returns the name of the request context (e.g. VIEW) associated with this Command. This method is guaranteed to return a
    098     * non-<code>null</code> String.
    099     *
    100     * @return the request context
    101     */
    102    String getRequestContext();
    103
    104    /**
    105     * Returns the Permission required to successfully execute this Command. If no Permission is required, this method returns
    106     * <code>null</code>. For example, the static command {@code org.apache.wiki.ui.PageCommand#VIEW} doesn't require a permission because
    107     * it isn't referring to a particular WikiPage. However, if this command targets a WikiPage called <code>Main</code>(via
    108     * {@code org.apache.wiki.ui.PageCommand#targetedCommand(Object)}, the resulting Command would require the permission
    109     * <code>PagePermission "<em>yourWiki</em>:Main", "view"</code>.
    110     *
    111     * @return the required permission, or <code>null</code> if not required
    112     */
    113    Permission requiredPermission();
    114
    115    /**
    116     * Returns the target associated with a Command, if it was created with one. Commands created with {@link #targetedCommand(Object)} will
    117     * <em>always</em> return a non-<code>null</code> object. <em>Calling methods should always check to see if the result of this method
    118     * is <code>null</code></em>.
    119     *
    120     * @return the wiki page
    121     */
    122    Object getTarget();
    123
    124    /**
    125     * Returns the URL pattern associated with this Command. This method is guaranteed to return a non-<code>null</code> String.
    126     *
    127     * @return the URL pattern
    128     */
    129    String getURLPattern();
    130
    131}