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 jakarta.servlet.http.HttpServletRequest; 022import jakarta.servlet.jsp.PageContext; 023import java.security.Principal; 024 025 026/** 027 * <p>Provides state information throughout the processing of a page. A Context is born when the JSP pages that are the main entry 028 * points, are invoked. The JSPWiki engine creates the new Context, which basically holds information about the page, the 029 * handling engine, and in which context (view, edit, etc) the call was done.</p> 030 * <p>A Context also provides request-specific variables, which can be used to communicate between plugins on the same page, or 031 * between different instances of the same plugin. A Context variable is valid until the processing of the WikiPage has ended. For 032 * an example, please see the Counter plugin.</p> 033 * <p>When a Context is created, it automatically associates a {@link Session} object with the user's 034 * HttpSession. The Session contains information about the user's authentication status, and is consulted by {@link #getCurrentUser()} 035 * object.</p> 036 * <p>Do not cache the WikiPage object that you get from the WikiContext; always use getPage()!</p> 037 * 038 * @see {@code org.apache.wiki.plugin.Counter} 039 */ 040public interface Context extends Cloneable, Command { 041 042 String ATTR_CONTEXT = "jspwiki.context"; 043 044 /** 045 * Variable name which tells whether plugins should be executed or not. Value can be either {@code Boolean.TRUE} or 046 * {@code Boolean.FALSE}. While not set its value is {@code null}. 047 */ 048 String VAR_EXECUTE_PLUGINS = "_PluginContent.execute"; 049 050 /** Name of the variable which is set to Boolean.TRUE or Boolean.FALSE depending on whether WYSIWYG is currently in effect. */ 051 String VAR_WYSIWYG_EDITOR_MODE = "WYSIWYG_EDITOR_MODE"; 052 053 /** 054 * Name of the variable that holds the markup being translated to HTML, as it was before the page filters ran. It is set while 055 * the text is rendered, so that a plugin sees an edited text that is not saved yet, for instance in a preview. While nothing is 056 * rendered its value is {@code null}. 057 * 058 * @since 3.0.1 059 */ 060 String VAR_RENDERED_TEXT = "_Rendering.text"; 061 062 /** 063 * Returns the WikiPage that is being handled. 064 * 065 * @return the WikiPage which was fetched. 066 */ 067 Page getPage(); 068 069 /** 070 * Sets the WikiPage that is being handled. 071 * 072 * @param wikiPage The wikipage 073 * @since 2.1.37. 074 */ 075 void setPage( Page wikiPage ); 076 077 /** 078 * Gets a reference to the real WikiPage whose content is currently being rendered. If your plugin e.g. does some variable setting, be 079 * aware that if it is embedded in the LeftMenu or some other WikiPage added with InsertPageTag, you should consider what you want to 080 * do - do you wish to really reference the "master" WikiPage or the included page. 081 * <p> 082 * For example, in the default template, there is a WikiPage called "LeftMenu". Whenever you access a page, e.g. "Main", the master 083 * WikiPage will be Main, and that's what the getPage() will return - regardless of whether your plugin resides on the LeftMenu or on 084 * the Main page. However, getRealPage() will return "LeftMenu". 085 * 086 * @return A reference to the real page. 087 * @see {@code org.apache.wiki.tags.InsertPageTag} 088 * @see {@code org.apache.wiki.parser.JSPWikiMarkupParser} 089 */ 090 Page getRealPage(); 091 092 /** 093 * Sets a reference to the real WikiPage whose content is currently being rendered. 094 * <p> 095 * Sometimes you may want to render the WikiPage using some other page's context. In those cases, it is highly recommended that you set 096 * the setRealPage() to point at the real WikiPage you are rendering. Please see InsertPageTag for an example. 097 * <p> 098 * Also, if your plugin e.g. does some variable setting, be aware that if it is embedded in the LeftMenu or some other WikiPage added 099 * with InsertPageTag, you should consider what you want to do - do you wish to really reference the "master" WikiPage or the included 100 * page. 101 * 102 * @param wikiPage The real WikiPage which is being rendered. 103 * @return The previous real page 104 * @since 2.3.14 105 * @see {@code org.apache.wiki.tags.InsertPageTag} 106 */ 107 Page setRealPage( Page wikiPage ); 108 109 /** 110 * Returns the handling engine. 111 * 112 * @return The wikiengine owning this context. 113 */ 114 Engine getEngine(); 115 116 /** 117 * Sets the request context. See above for the different request contexts (VIEW, EDIT, etc.) 118 * 119 * @param context The request context (one of the predefined contexts.) 120 */ 121 void setRequestContext( String context ); 122 123 /** 124 * Gets a previously set variable. 125 * 126 * @param key The variable name. 127 * @return The variable contents. 128 */ 129 < T > T getVariable( String key ); 130 131 /** 132 * Sets a variable. The variable is valid while the WikiContext is valid, i.e. while WikiPage processing continues. The variable data 133 * is discarded once the WikiPage processing is finished. 134 * 135 * @param key The variable name. 136 * @param data The variable value. 137 */ 138 void setVariable( String key, Object data ); 139 140 /** 141 * This is just a simple helper method which will first check the context if there is already an override in place, and if there is not, 142 * it will then check the given properties. 143 * 144 * @param key What key are we searching for? 145 * @param defValue Default value for the boolean 146 * @return {@code true} or {@code false}. 147 */ 148 boolean getBooleanWikiProperty( String key, boolean defValue ); 149 150 /** 151 * This method will safely return any HTTP parameters that might have been defined. You should use this method instead 152 * of peeking directly into the result of getHttpRequest(), since this method is smart enough to do all the right things, 153 * figure out UTF-8 encoded parameters, etc. 154 * 155 * @since 2.0.13. 156 * @param paramName Parameter name to look for. 157 * @return HTTP parameter, or null, if no such parameter existed. 158 */ 159 String getHttpParameter( String paramName ); 160 161 /** 162 * If the request did originate from an HTTP request, then the HTTP request can be fetched here. However, if the request 163 * did NOT originate from an HTTP request, then this method will return null, and YOU SHOULD CHECK FOR IT! 164 * 165 * @return Null, if no HTTP request was done. 166 * @since 2.0.13. 167 */ 168 HttpServletRequest getHttpRequest(); 169 170 /** 171 * Sets the template to be used for this request. 172 * 173 * @param dir The template name 174 * @since 2.1.15. 175 */ 176 void setTemplate( String dir ); 177 178 /** 179 * Gets the template that is to be used throughout this request. 180 * 181 * @since 2.1.15. 182 * @return template name 183 */ 184 String getTemplate(); 185 186 /** 187 * Returns the Session associated with the context. This method is guaranteed to always return a valid Session. 188 * If this context was constructed without an associated HttpServletRequest, it will return a guest session. 189 * 190 * @return The Session associate with this context. 191 */ 192 Session getWikiSession(); 193 194 /** 195 * Convenience method that gets the current user. Delegates the lookup to the Session associated with this Context. 196 * May return null, in case the current user has not yet been determined; or this is an internal system. If the Session has not 197 * been set, <em>always</em> returns null. 198 * 199 * @return The current user; or maybe null in case of internal calls. 200 */ 201 Principal getCurrentUser(); 202 203 /** 204 * Returns true, if the current user has administrative permissions (i.e. the omnipotent AllPermission). 205 * 206 * @since 2.4.46 207 * @return true, if the user has all permissions. 208 */ 209 boolean hasAdminPermissions(); 210 211 /** 212 * A shortcut to generate a VIEW url. 213 * 214 * @param WikiPage The WikiPage to which to link. 215 * @return A URL to the page. This honours the current absolute/relative setting. 216 */ 217 String getViewURL( String WikiPage ); 218 219 /** 220 * Figure out to which WikiPage we are really going to. Considers special WikiPage names from the jspwiki.properties, and possible aliases. 221 * 222 * @return A complete URL to the new WikiPage to redirect to 223 * @since 2.2 224 */ 225 String getRedirectURL(); 226 227 /** 228 * Returns the Command associated with this Context. 229 * 230 * @return the command 231 */ 232 Command getCommand(); 233 234 /** 235 * Creates a URL for the given request context. 236 * 237 * @param context e.g. WikiContext.EDIT 238 * @param page The WikiPage to which to link 239 * @return A URL to the page. 240 */ 241 default String getURL( final String context, final String page ) { 242 return getURL( context, page, null ); 243 } 244 245 /** 246 * Returns a URL from a page. It this Context instance was constructed with an actual HttpServletRequest, we will attempt to 247 * construct the URL using HttpUtil, which preserves the HTTPS portion if it was used. 248 * 249 * @param context The request context (e.g. WikiContext.UPLOAD) 250 * @param page The WikiPage to which to link 251 * @param params A list of parameters, separated with "&" 252 * 253 * @return A URL to the given context and page. 254 */ 255 default String getURL( final String context, final String page, final String params ) { 256 // FIXME: is rather slow 257 return getEngine().getURL( context, page, params ); 258 } 259 260 /** {@inheritDoc} */ 261 Context clone(); 262 263 /** 264 * Creates a deep clone of the Context. This is useful when you want to be sure that you don't accidentally mess with page 265 * attributes, etc. 266 * 267 * @since 2.8.0 268 * @return A deep clone of the Context. 269 */ 270 Context deepClone(); 271 272 /** 273 * This method can be used to find the WikiContext programmatically from a JSP PageContext. We check the request context. 274 * The wiki context, if it exists, is looked up using the key {@link #ATTR_CONTEXT}. 275 * 276 * @since 2.4 277 * @param pageContext the JSP page context 278 * @return Current WikiContext, or null, of no context exists. 279 */ 280 static Context findContext( final PageContext pageContext ) { 281 final HttpServletRequest request = ( HttpServletRequest )pageContext.getRequest(); 282 return ( Context )request.getAttribute( ATTR_CONTEXT ); 283 } 284 285}