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 requred, 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}