001package org.apache.turbine.util; 002 003 004/* 005 * Licensed to the Apache Software Foundation (ASF) under one 006 * or more contributor license agreements. See the NOTICE file 007 * distributed with this work for additional information 008 * regarding copyright ownership. The ASF licenses this file 009 * to you under the Apache License, Version 2.0 (the 010 * "License"); you may not use this file except in compliance 011 * with the License. You may obtain a copy of the License at 012 * 013 * http://www.apache.org/licenses/LICENSE-2.0 014 * 015 * Unless required by applicable law or agreed to in writing, 016 * software distributed under the License is distributed on an 017 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 018 * KIND, either express or implied. See the License for the 019 * specific language governing permissions and limitations 020 * under the License. 021 */ 022 023 024import java.io.IOException; 025import java.io.PrintWriter; 026import java.util.Locale; 027import java.util.Map; 028 029import javax.naming.Context; 030import javax.servlet.ServletConfig; 031import javax.servlet.ServletContext; 032import javax.servlet.http.HttpServletRequest; 033import javax.servlet.http.HttpServletResponse; 034import javax.servlet.http.HttpSession; 035 036import org.apache.fulcrum.parser.CookieParser; 037import org.apache.fulcrum.parser.ParameterParser; 038import org.apache.fulcrum.security.acl.AccessControlList; 039import org.apache.turbine.om.security.User; 040import org.apache.turbine.pipeline.PipelineData; 041import org.apache.turbine.util.template.TemplateInfo; 042 043/** 044 * RunData is an interface to run-time information that is passed 045 * within Turbine. This provides the threading mechanism for the 046 * entire system because multiple requests can potentially come in 047 * at the same time. Thus, there is only one RunData instance 048 * for each request that is being serviced. 049 * 050 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a> 051 * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a> 052 * @author <a href="mailto:bhoeneis@ee.ethz.ch">Bernie Hoeneisen</a> 053 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a> 054 * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a> 055 * @version $Id: RunData.java 1792901 2017-04-27 14:08:57Z gk $ 056 */ 057public interface RunData extends PipelineData 058{ 059 /** 060 * Gets the parameters. 061 * 062 * @return a parameter parser. 063 */ 064 ParameterParser getParameters(); 065 066 /** 067 * Gets the cookies. 068 * 069 * @return a cookie parser. 070 */ 071 CookieParser getCookies(); 072 073 /** 074 * Gets the servlet request. 075 * 076 * @return the request. 077 */ 078 HttpServletRequest getRequest(); 079 080 /** 081 * Gets the servlet response. 082 * 083 * @return the resposne. 084 */ 085 HttpServletResponse getResponse(); 086 087 /** 088 * Gets the servlet session information. 089 * 090 * @return the session. 091 */ 092 HttpSession getSession(); 093 094 /** 095 * Gets the servlet configuration used during servlet init. 096 * 097 * @return the configuration. 098 */ 099 ServletConfig getServletConfig(); 100 101 /** 102 * Gets the servlet context used during servlet init. 103 * 104 * @return the context. 105 */ 106 ServletContext getServletContext(); 107 108 /** 109 * Gets the access control list. 110 * 111 * @return the access control list. 112 * 113 * @param <A> a type extending {@link AccessControlList} 114 */ 115 <A extends AccessControlList> A getACL(); 116 117 /** 118 * Sets the access control list. 119 * 120 * @param acl an access control list. 121 */ 122 <A extends AccessControlList> void setACL(A acl); 123 124 /** 125 * Whether or not an action has been defined. 126 * 127 * @return true if an action has been defined. 128 */ 129 boolean hasAction(); 130 131 /** 132 * Gets the action. It returns an empty string if null so 133 * that it is easy to do conditionals on it based on the 134 * equalsIgnoreCase() method. 135 * 136 * @return a string, "" if null. 137 */ 138 String getAction(); 139 140 /** 141 * Sets the action for the request. 142 * 143 * @param action a string. 144 */ 145 void setAction(String action); 146 147 /** 148 * If the Layout has not been defined by the screen then set the 149 * layout to be "DefaultLayout". The screen object can also 150 * override this method to provide intelligent determination of 151 * the Layout to execute. You can also define that logic here as 152 * well if you want it to apply on a global scale. For example, 153 * if you wanted to allow someone to define layout "preferences" 154 * where they could dynamically change the layout for the entire 155 * site. 156 * 157 * @return a string. 158 */ 159 String getLayout(); 160 161 /** 162 * Set the layout for the request. 163 * 164 * @param layout a string. 165 */ 166 void setLayout(String layout); 167 168 /** 169 * Convenience method for a template info that 170 * returns the layout template being used. 171 * 172 * @return a string. 173 */ 174 String getLayoutTemplate(); 175 176 /** 177 * Modifies the layout template for the screen. This convenience 178 * method allows for a layout to be modified from within a 179 * template. For example; 180 * 181 * $data.setLayoutTemplate("NewLayout.vm") 182 * 183 * @param layout a layout template. 184 */ 185 void setLayoutTemplate(String layout); 186 187 /** 188 * Whether or not a screen has been defined. 189 * 190 * @return true if a screen has been defined. 191 */ 192 boolean hasScreen(); 193 194 /** 195 * Gets the screen to execute. 196 * 197 * @return a string. 198 */ 199 String getScreen(); 200 201 /** 202 * Sets the screen for the request. 203 * 204 * @param screen a string. 205 */ 206 void setScreen(String screen); 207 208 /** 209 * Convenience method for a template info that 210 * returns the name of the template being used. 211 * 212 * @return a string. 213 */ 214 String getScreenTemplate(); 215 216 /** 217 * Sets the screen template for the request. For 218 * example; 219 * 220 * $data.setScreenTemplate("NewScreen.vm") 221 * 222 * @param screen a screen template. 223 */ 224 void setScreenTemplate(String screen); 225 226 /** 227 * Gets the character encoding to use for reading template files. 228 * 229 * @return the template encoding or null if not specified. 230 */ 231 String getTemplateEncoding(); 232 233 /** 234 * Sets the character encoding to use for reading template files. 235 * 236 * @param encoding the template encoding. 237 */ 238 void setTemplateEncoding(String encoding); 239 240 /** 241 * Gets the template info. Creates a new one if needed. 242 * 243 * @return a template info. 244 */ 245 TemplateInfo getTemplateInfo(); 246 247 /** 248 * Whether or not a message has been defined. 249 * 250 * @return true if a message has been defined. 251 */ 252 boolean hasMessage(); 253 254 /** 255 * Gets the results of an action or another message 256 * to be displayed as a string. 257 * 258 * @return a string. 259 */ 260 String getMessage(); 261 262 /** 263 * Sets the message for the request as a string. 264 * 265 * @param msg a string. 266 */ 267 void setMessage(String msg); 268 269 /** 270 * Adds the string to message. If message has prior messages from 271 * other actions or screens, this method can be used to chain them. 272 * 273 * @param msg a string. 274 */ 275 void addMessage(String msg); 276 277 /** 278 * Gets the results of an action or another message 279 * to be displayed as a string. 280 * 281 * @return a string. 282 */ 283 String getMessageAsHTML(); 284 285 /** 286 * Unsets the message for the request. 287 */ 288 void unsetMessage(); 289 290 /** 291 * Gets a FormMessages object where all the messages to the 292 * user should be stored. 293 * 294 * @return a FormMessages. 295 */ 296 FormMessages getMessages(); 297 298 /** 299 * Sets the FormMessages object for the request. 300 * 301 * @param msgs A FormMessages. 302 */ 303 void setMessages(FormMessages msgs); 304 305 /** 306 * Gets the title of the page. 307 * 308 * @return a string. 309 */ 310 String getTitle(); 311 312 /** 313 * Sets the title of the page. 314 * 315 * @param title a string. 316 */ 317 void setTitle(String title); 318 319 /** 320 * Checks if a user exists in this session. 321 * 322 * @return true if a user exists in this session. 323 */ 324 boolean userExists(); 325 326 /** 327 * Gets the user. 328 * 329 * @param <T> a type extending {@link User} 330 * 331 * @return a user. 332 */ 333 <T extends User> T getUser(); 334 335 /** 336 * Sets the user. 337 * 338 * @param user a user. 339 * 340 * @param <T> a type extending {@link User} 341 */ 342 <T extends User> void setUser(T user); 343 344 /** 345 * Attempts to get the user from the session. If it does 346 * not exist, it returns null. 347 * 348 * @return a user. 349 * 350 * @param <T> a type extending {@link User} 351 */ 352 <T extends User> T getUserFromSession(); 353 354 /** 355 * Allows one to invalidate the user in the default session. 356 * 357 * @return true if user was invalidated. 358 */ 359 boolean removeUserFromSession(); 360 361 /** 362 * Checks to see if out is set. 363 * 364 * @return true if out is set. 365 * @deprecated no replacement planned, response writer will not be cached 366 */ 367 @Deprecated 368 boolean isOutSet(); 369 370 /** 371 * Gets the print writer. First time calling this 372 * will set the print writer via the response. 373 * 374 * @return a print writer. 375 * @throws IOException on failure getting the PrintWriter 376 */ 377 PrintWriter getOut() 378 throws IOException; 379 380 /** 381 * Declares that output will be direct to the response stream, 382 * even though getOut() may never be called. Useful for response 383 * mechanisms that may call res.getWriter() themselves 384 * (such as JSP.) 385 */ 386 void declareDirectResponse(); 387 388 /** 389 * Gets the locale. If it has not already been defined with 390 * setLocale(), then properties named "locale.default.lang" 391 * and "locale.default.country" are checked from the Resource 392 * Service and the corresponding locale is returned. If these 393 * properties are undefined, JVM's default locale is returned. 394 * 395 * @return the locale. 396 */ 397 Locale getLocale(); 398 399 /** 400 * Sets the locale. 401 * 402 * @param locale the new locale. 403 */ 404 void setLocale(Locale locale); 405 406 /** 407 * Gets the charset. If it has not already been defined with 408 * setCharSet(), then a property named "locale.default.charset" 409 * is checked from the Resource Service and returned. If this 410 * property is undefined, the default charset of the locale 411 * is returned. If the locale is undefined, null is returned. 412 * 413 * @return the name of the charset or null. 414 */ 415 String getCharSet(); 416 417 /** 418 * Sets the charset. 419 * 420 * @param charset the name of the new charset. 421 */ 422 void setCharSet(String charset); 423 424 /** 425 * Gets the HTTP content type to return. If a charset 426 * has been specified, it is included in the content type. 427 * If the charset has not been specified and the main type 428 * of the content type is "text", the default charset is 429 * included. If the default charset is undefined, but the 430 * default locale is defined and it is not the US locale, 431 * a locale specific charset is included. 432 * 433 * @return the content type or an empty string. 434 */ 435 String getContentType(); 436 437 /** 438 * Sets the HTTP content type to return. 439 * 440 * @param ct the new content type. 441 */ 442 void setContentType(String ct); 443 444 /** 445 * Gets the redirect URI. If this is set, also make sure to set 446 * the status code to 302. 447 * 448 * @return a string, "" if null. 449 */ 450 String getRedirectURI(); 451 452 /** 453 * Sets the redirect uri. If this is set, also make sure to set 454 * the status code to 302. 455 * 456 * @param ruri a string. 457 */ 458 void setRedirectURI(String ruri); 459 460 /** 461 * Gets the HTTP status code to return. 462 * 463 * @return the status. 464 */ 465 int getStatusCode(); 466 467 /** 468 * Sets the HTTP status code to return. 469 * 470 * @param sc the status. 471 */ 472 void setStatusCode(int sc); 473 474 /** 475 * Gets an array of system errors. 476 * 477 * @return a SystemError[]. 478 */ 479 SystemError[] getSystemErrors(); 480 481 /** 482 * Adds a critical system error. 483 * 484 * @param err a system error. 485 */ 486 void setSystemError(SystemError err); 487 488 /** 489 * Gets JNDI Contexts. 490 * 491 * @return a hashtable. 492 */ 493 Map<String, Context> getJNDIContexts(); 494 495 /** 496 * Sets JNDI Contexts. 497 * 498 * @param contexts a hashtable. 499 */ 500 void setJNDIContexts(Map<String, Context> contexts); 501 502 /** 503 * Gets the cached server scheme. 504 * 505 * @return a string. 506 */ 507 String getServerScheme(); 508 509 /** 510 * Gets the cached server name. 511 * 512 * @return a string. 513 */ 514 String getServerName(); 515 516 /** 517 * Gets the cached server port. 518 * 519 * @return an int. 520 */ 521 int getServerPort(); 522 523 /** 524 * Gets the cached context path. 525 * 526 * @return a string. 527 */ 528 String getContextPath(); 529 530 /** 531 * Gets the cached script name. 532 * 533 * @return a string. 534 */ 535 String getScriptName(); 536 537 /** 538 * Gets the server data used by the request. 539 * 540 * @return server data. 541 */ 542 ServerData getServerData(); 543 544 /** 545 * Gets the IP address of the client that sent the request. 546 * 547 * @return a string. 548 */ 549 String getRemoteAddr(); 550 551 /** 552 * Gets the qualified name of the client that sent the request. 553 * 554 * @return a string. 555 */ 556 String getRemoteHost(); 557 558 /** 559 * Get the user agent for the request. 560 * 561 * @return a string. 562 */ 563 String getUserAgent(); 564 565 /** 566 * Pulls a user object from the session and increments the access 567 * counter and sets the last access date for the object. 568 */ 569 void populate(); 570 571 /** 572 * Saves a user object into the session. 573 */ 574 void save(); 575 576 /** 577 * Gets the stack trace if set. 578 * 579 * @return the stack trace. 580 */ 581 String getStackTrace(); 582 583 /** 584 * Gets the stack trace exception if set. 585 * 586 * @return the stack exception. 587 */ 588 Throwable getStackTraceException(); 589 590 /** 591 * Sets the stack trace. 592 * 593 * @param trace the stack trace. 594 * @param exp the exception. 595 */ 596 void setStackTrace(String trace, 597 Throwable exp); 598 599 /** 600 * Sets a name/value pair in an internal Map that is accessible from the 601 * Error screen. This is a good way to get debugging information 602 * when an exception is thrown. 603 * 604 * @param name name of the variable 605 * @param value value of the variable. 606 */ 607 void setDebugVariable(String name, Object value); 608 609 /** 610 * Gets a Map of debug variables. 611 * 612 * @return a Map of debug variables. 613 */ 614 Map<String, Object> getDebugVariables(); 615}