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 */
019 package org.apache.wiki.ui;
020
021 import java.security.Permission;
022
023 /**
024 * <p>
025 * Represents a logical "unit of work" that includes a request context, JSP,
026 * URLPattern, content template and (optionally) a target and required security
027 * permission. Examples of Commands include "view a page," "create a group," and
028 * "edit user preferences."
029 * </p>
030 * <p>
031 * Commands come in two flavors: "static" and "targeted."
032 * </p>
033 * <ul>
034 * <li><strong>Static commands</strong> are exactly what they sound like:
035 * static. They are <code>final</code>, threadsafe, and immutable. They have
036 * no intrinsic idea of the context they are acting in. For example, the static
037 * command {@link PageCommand#VIEW} embodies the idea of viewing a page —
038 * but exactly <em>which</em> page is left undefined. Static commands exist so
039 * that they can be freely shared and passed around without incurring the
040 * penalties of object creation. Static commands are a lot like naked request
041 * contexts ("edit", "view", etc.) except that they include additional,
042 * essential properites such as the associated URL pattern and content JSP.</li>
043 * <li><strong>Targeted commands</strong> "decorate" static commands by
044 * scoping a static Command at a specific target such as a WikiPage or
045 * GroupPrincipal. Targeted commands are created by calling an existing
046 * Command's {@link #targetedCommand(Object)} and supplying the target object.
047 * Implementing classes generally require a specific target type. For example,
048 * the {@link PageCommand} class requires that the target object be of type
049 * {@link org.apache.wiki.WikiPage}.</li>
050 * </ul>
051 * <p>
052 * Concrete implementations of Command include:
053 * </p>
054 * <ul>
055 * <li><strong>PageCommand</strong>: commands for editing, renaming, and
056 * viewing pages</li>
057 * <li><strong>GroupCommand</strong>: commands for viewing, editing and
058 * deleting wiki groups</li>
059 * <li><strong>WikiCommand</strong>: commands for wiki-wide operations such as
060 * creating groups, editing preferences and profiles, and logging in/out</li>
061 * <li><strong>RedirectCommand</strong>: commands for redirections to off-site
062 * special pages</li>
063 * </ul>
064 * <p>
065 * For a given targeted Command, its {@link #getTarget()} method will return a
066 * non-<code>null</code> value. In addition, its
067 * {@link #requiredPermission()} method will generally also return a non-<code>null</code>
068 * value. It is each implementation's responsibility to construct and store the
069 * correct Permission for a given Command and Target. For example, when
070 * PageCommand.VIEW is targeted at the WikiPage <code>Main</code>, the
071 * Command's associated permission is
072 * <code>PagePermission "<em>theWiki</em>:Main", "view".</code>
073 * </p>
074 * <p>
075 * Static Commands, and targeted Commands that do not require specific
076 * permissions to execute, return a <code>null</code> result for
077 * {@link #requiredPermission()}.
078 * </p>
079 * @since 2.4.22
080 */
081 public interface Command
082 {
083 /**
084 * Creates and returns a targeted Command by combining a target, such as a
085 * WikiPage or GroupPrincipal into the existing Command. Subclasses should
086 * check to make sure the supplied <code>target</code> object is of the
087 * correct type. This method is guaranteed to return a non-<code>null</code>
088 * Command (unless the target is an incorrect type).
089 * @param target the object to combine, such as a GroupPrincipal or WikiPage
090 * @return the new, targeted Command
091 * @throws IllegalArgumentException if the target is not of the correct type
092 */
093 Command targetedCommand( Object target );
094
095 /**
096 * Returns the content template associated with a Command, such as
097 * <code>PreferencesContent.jsp</code>. For Commands that are not
098 * page-related, this method will always return <code>null</code>.
099 * <em>Calling methods should always check to see if the result
100 * of this method is <code>null</code></em>.
101 * @return the content template
102 */
103 String getContentTemplate();
104
105 /**
106 * Returns the JSP associated with the Command. The JSP is
107 * a "local" JSP within the JSPWiki webapp; it is not
108 * a general HTTP URL. If it exists, the JSP will be expressed
109 * relative to the webapp root, without a leading slash.
110 * This method is guaranteed to return a non-<code>null</code>
111 * result, although in some cases the result may be an empty string.
112 * @return the JSP or url associated with the wiki command
113 */
114 String getJSP();
115
116 /**
117 * Returns the human-friendly name for this command.
118 * @return the name
119 */
120 String getName();
121
122 /**
123 * Returns the request context associated with this Command. This method is
124 * guaranteed to return a non-<code>null</code> String.
125 * @return the request context
126 */
127 String getRequestContext();
128
129 /**
130 * Returns the Permission required to successfully execute this Command. If
131 * no Permission is requred, this method returns <code>null</code>. For
132 * example, the static command {@link PageCommand#VIEW} doesn't require a
133 * permission because it isn't referring to a particular WikiPage. However,
134 * if this command targets a WikiPage called <code>Main</code>(via
135 * {@link PageCommand#targetedCommand(Object)}, the resulting Command
136 * would require the permission
137 * <code>PagePermission "<em>yourWiki</em>:Main", "view"</code>.
138 * @return the required permission, or <code>null</code> if not required
139 */
140 Permission requiredPermission();
141
142 /**
143 * Returns the target associated with a Command, if it was created with one.
144 * Commands created with {@link #targetedCommand(Object)} will
145 * <em>always</em> return a non-<code>null</code> object. <em>Calling
146 * methods should always check to see if the result of this method
147 * is <code>null</code></em>.
148 * @return the wiki page
149 */
150 Object getTarget();
151
152 /**
153 * Returns the URL pattern associated with this Command. This method is
154 * guaranteed to return a non-<code>null</code> String.
155 * @return the URL pattern
156 */
157 String getURLPattern();
158
159 }