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