| Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
| RunData |
|
| 1.0;1 |
| 1 | package org.apache.turbine.util; | |
| 2 | ||
| 3 | ||
| 4 | /* | |
| 5 | * Licensed to the Apache Software Foundation (ASF) under one | |
| 6 | * or more contributor license agreements. See the NOTICE file | |
| 7 | * distributed with this work for additional information | |
| 8 | * regarding copyright ownership. The ASF licenses this file | |
| 9 | * to you under the Apache License, Version 2.0 (the | |
| 10 | * "License"); you may not use this file except in compliance | |
| 11 | * with the License. You may obtain a copy of the License at | |
| 12 | * | |
| 13 | * http://www.apache.org/licenses/LICENSE-2.0 | |
| 14 | * | |
| 15 | * Unless required by applicable law or agreed to in writing, | |
| 16 | * software distributed under the License is distributed on an | |
| 17 | * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| 18 | * KIND, either express or implied. See the License for the | |
| 19 | * specific language governing permissions and limitations | |
| 20 | * under the License. | |
| 21 | */ | |
| 22 | ||
| 23 | ||
| 24 | import java.io.IOException; | |
| 25 | import java.io.PrintWriter; | |
| 26 | import java.util.Locale; | |
| 27 | import java.util.Map; | |
| 28 | ||
| 29 | import javax.naming.Context; | |
| 30 | import javax.servlet.ServletConfig; | |
| 31 | import javax.servlet.ServletContext; | |
| 32 | import javax.servlet.http.HttpServletRequest; | |
| 33 | import javax.servlet.http.HttpServletResponse; | |
| 34 | import javax.servlet.http.HttpSession; | |
| 35 | ||
| 36 | import org.apache.ecs.Document; | |
| 37 | import org.apache.ecs.Element; | |
| 38 | import org.apache.ecs.StringElement; | |
| 39 | import org.apache.fulcrum.parser.CookieParser; | |
| 40 | import org.apache.fulcrum.parser.ParameterParser; | |
| 41 | import org.apache.turbine.om.security.User; | |
| 42 | import org.apache.turbine.pipeline.PipelineData; | |
| 43 | import org.apache.turbine.util.security.AccessControlList; | |
| 44 | import org.apache.turbine.util.template.TemplateInfo; | |
| 45 | ||
| 46 | /** | |
| 47 | * RunData is an interface to run-time information that is passed | |
| 48 | * within Turbine. This provides the threading mechanism for the | |
| 49 | * entire system because multiple requests can potentially come in | |
| 50 | * at the same time. Thus, there is only one RunData implementation | |
| 51 | * for each request that is being serviced. | |
| 52 | * | |
| 53 | * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a> | |
| 54 | * @author <a href="mailto:jon@clearink.com">Jon S. Stevens</a> | |
| 55 | * @author <a href="mailto:bhoeneis@ee.ethz.ch">Bernie Hoeneisen</a> | |
| 56 | * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a> | |
| 57 | * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a> | |
| 58 | * @version $Id: RunData.java 1066938 2011-02-03 20:14:53Z ludwig $ | |
| 59 | */ | |
| 60 | public interface RunData extends PipelineData | |
| 61 | { | |
| 62 | /** | |
| 63 | * Gets the parameters. | |
| 64 | * | |
| 65 | * @return a parameter parser. | |
| 66 | */ | |
| 67 | ParameterParser getParameters(); | |
| 68 | ||
| 69 | /** | |
| 70 | * Gets the cookies. | |
| 71 | * | |
| 72 | * @return a cookie parser. | |
| 73 | */ | |
| 74 | CookieParser getCookies(); | |
| 75 | ||
| 76 | /** | |
| 77 | * Gets the servlet request. | |
| 78 | * | |
| 79 | * @return the request. | |
| 80 | */ | |
| 81 | HttpServletRequest getRequest(); | |
| 82 | ||
| 83 | /** | |
| 84 | * Gets the servlet response. | |
| 85 | * | |
| 86 | * @return the resposne. | |
| 87 | */ | |
| 88 | HttpServletResponse getResponse(); | |
| 89 | ||
| 90 | /** | |
| 91 | * Gets the servlet session information. | |
| 92 | * | |
| 93 | * @return the session. | |
| 94 | */ | |
| 95 | HttpSession getSession(); | |
| 96 | ||
| 97 | /** | |
| 98 | * Gets the servlet configuration used during servlet init. | |
| 99 | * | |
| 100 | * @return the configuration. | |
| 101 | */ | |
| 102 | ServletConfig getServletConfig(); | |
| 103 | ||
| 104 | /** | |
| 105 | * Gets the servlet context used during servlet init. | |
| 106 | * | |
| 107 | * @return the context. | |
| 108 | */ | |
| 109 | ServletContext getServletContext(); | |
| 110 | ||
| 111 | /** | |
| 112 | * Gets the access control list. | |
| 113 | * | |
| 114 | * @return the access control list. | |
| 115 | */ | |
| 116 | AccessControlList getACL(); | |
| 117 | ||
| 118 | /** | |
| 119 | * Sets the access control list. | |
| 120 | * | |
| 121 | * @param acl an access control list. | |
| 122 | */ | |
| 123 | void setACL(AccessControlList acl); | |
| 124 | ||
| 125 | /** | |
| 126 | * Checks to see if the page is set. | |
| 127 | * | |
| 128 | * @return true if the page is set. | |
| 129 | * @deprecated no replacement planned, ECS is no longer a requirement | |
| 130 | */ | |
| 131 | @Deprecated | |
| 132 | boolean isPageSet(); | |
| 133 | ||
| 134 | /** | |
| 135 | * Gets the page. | |
| 136 | * | |
| 137 | * @return a document. | |
| 138 | * @deprecated no replacement planned, ECS is no longer a requirement | |
| 139 | */ | |
| 140 | @Deprecated | |
| 141 | Document getPage(); | |
| 142 | ||
| 143 | /** | |
| 144 | * Whether or not an action has been defined. | |
| 145 | * | |
| 146 | * @return true if an action has been defined. | |
| 147 | */ | |
| 148 | boolean hasAction(); | |
| 149 | ||
| 150 | /** | |
| 151 | * Gets the action. It returns an empty string if null so | |
| 152 | * that it is easy to do conditionals on it based on the | |
| 153 | * equalsIgnoreCase() method. | |
| 154 | * | |
| 155 | * @return a string, "" if null. | |
| 156 | */ | |
| 157 | String getAction(); | |
| 158 | ||
| 159 | /** | |
| 160 | * Sets the action for the request. | |
| 161 | * | |
| 162 | * @param action a atring. | |
| 163 | */ | |
| 164 | void setAction(String action); | |
| 165 | ||
| 166 | /** | |
| 167 | * If the Layout has not been defined by the screen then set the | |
| 168 | * layout to be "DefaultLayout". The screen object can also | |
| 169 | * override this method to provide intelligent determination of | |
| 170 | * the Layout to execute. You can also define that logic here as | |
| 171 | * well if you want it to apply on a global scale. For example, | |
| 172 | * if you wanted to allow someone to define layout "preferences" | |
| 173 | * where they could dynamicially change the layout for the entire | |
| 174 | * site. | |
| 175 | * | |
| 176 | * @return a string. | |
| 177 | */ | |
| 178 | String getLayout(); | |
| 179 | ||
| 180 | /** | |
| 181 | * Set the layout for the request. | |
| 182 | * | |
| 183 | * @param layout a string. | |
| 184 | */ | |
| 185 | void setLayout(String layout); | |
| 186 | ||
| 187 | /** | |
| 188 | * Convenience method for a template info that | |
| 189 | * returns the layout template being used. | |
| 190 | * | |
| 191 | * @return a string. | |
| 192 | */ | |
| 193 | String getLayoutTemplate(); | |
| 194 | ||
| 195 | /** | |
| 196 | * Modifies the layout template for the screen. This convenience | |
| 197 | * method allows for a layout to be modified from within a | |
| 198 | * template. For example; | |
| 199 | * | |
| 200 | * $data.setLayoutTemplate("NewLayout.vm") | |
| 201 | * | |
| 202 | * @param layout a layout template. | |
| 203 | */ | |
| 204 | void setLayoutTemplate(String layout); | |
| 205 | ||
| 206 | /** | |
| 207 | * Whether or not a screen has been defined. | |
| 208 | * | |
| 209 | * @return true if a screen has been defined. | |
| 210 | */ | |
| 211 | boolean hasScreen(); | |
| 212 | ||
| 213 | /** | |
| 214 | * Gets the screen to execute. | |
| 215 | * | |
| 216 | * @return a string. | |
| 217 | */ | |
| 218 | String getScreen(); | |
| 219 | ||
| 220 | /** | |
| 221 | * Sets the screen for the request. | |
| 222 | * | |
| 223 | * @param screen a string. | |
| 224 | */ | |
| 225 | void setScreen(String screen); | |
| 226 | ||
| 227 | /** | |
| 228 | * Convenience method for a template info that | |
| 229 | * returns the name of the template being used. | |
| 230 | * | |
| 231 | * @return a string. | |
| 232 | */ | |
| 233 | String getScreenTemplate(); | |
| 234 | ||
| 235 | /** | |
| 236 | * Sets the screen template for the request. For | |
| 237 | * example; | |
| 238 | * | |
| 239 | * $data.setScreenTemplate("NewScreen.vm") | |
| 240 | * | |
| 241 | * @param screen a screen template. | |
| 242 | */ | |
| 243 | void setScreenTemplate(String screen); | |
| 244 | ||
| 245 | /** | |
| 246 | * Gets the character encoding to use for reading template files. | |
| 247 | * | |
| 248 | * @return the template encoding or null if not specified. | |
| 249 | */ | |
| 250 | String getTemplateEncoding(); | |
| 251 | ||
| 252 | /** | |
| 253 | * Sets the character encoding to use for reading template files. | |
| 254 | * | |
| 255 | * @param encoding the template encoding. | |
| 256 | */ | |
| 257 | void setTemplateEncoding(String encoding); | |
| 258 | ||
| 259 | /** | |
| 260 | * Gets the template info. Creates a new one if needed. | |
| 261 | * | |
| 262 | * @return a template info. | |
| 263 | */ | |
| 264 | TemplateInfo getTemplateInfo(); | |
| 265 | ||
| 266 | /** | |
| 267 | * Whether or not a message has been defined. | |
| 268 | * | |
| 269 | * @return true if a message has been defined. | |
| 270 | */ | |
| 271 | boolean hasMessage(); | |
| 272 | ||
| 273 | /** | |
| 274 | * Gets the results of an action or another message | |
| 275 | * to be displayed as a string. | |
| 276 | * | |
| 277 | * @return a string. | |
| 278 | */ | |
| 279 | String getMessage(); | |
| 280 | ||
| 281 | /** | |
| 282 | * Sets the message for the request as a string. | |
| 283 | * | |
| 284 | * @param msg a string. | |
| 285 | */ | |
| 286 | void setMessage(String msg); | |
| 287 | ||
| 288 | /** | |
| 289 | * Adds the string to message. If message has prior messages from | |
| 290 | * other actions or screens, this method can be used to chain them. | |
| 291 | * | |
| 292 | * @param msg a string. | |
| 293 | */ | |
| 294 | void addMessage(String msg); | |
| 295 | ||
| 296 | /** | |
| 297 | * Gets the results of an action or another message | |
| 298 | * to be displayed as an ECS string element. | |
| 299 | * | |
| 300 | * @return a string element. | |
| 301 | */ | |
| 302 | StringElement getMessageAsHTML(); | |
| 303 | ||
| 304 | /** | |
| 305 | * Sets the message for the request as an ECS element. | |
| 306 | * | |
| 307 | * @param msg an element. | |
| 308 | */ | |
| 309 | void setMessage(Element msg); | |
| 310 | ||
| 311 | /** | |
| 312 | * Adds the ECS element to message. If message has prior messages from | |
| 313 | * other actions or screens, this method can be used to chain them. | |
| 314 | * | |
| 315 | * @param msg an element. | |
| 316 | */ | |
| 317 | void addMessage(Element msg); | |
| 318 | ||
| 319 | /** | |
| 320 | * Unsets the message for the request. | |
| 321 | */ | |
| 322 | void unsetMessage(); | |
| 323 | ||
| 324 | /** | |
| 325 | * Gets a FormMessages object where all the messages to the | |
| 326 | * user should be stored. | |
| 327 | * | |
| 328 | * @return a FormMessages. | |
| 329 | */ | |
| 330 | FormMessages getMessages(); | |
| 331 | ||
| 332 | /** | |
| 333 | * Sets the FormMessages object for the request. | |
| 334 | * | |
| 335 | * @param msgs A FormMessages. | |
| 336 | */ | |
| 337 | void setMessages(FormMessages msgs); | |
| 338 | ||
| 339 | /** | |
| 340 | * Gets the title of the page. | |
| 341 | * | |
| 342 | * @return a string. | |
| 343 | */ | |
| 344 | String getTitle(); | |
| 345 | ||
| 346 | /** | |
| 347 | * Sets the title of the page. | |
| 348 | * | |
| 349 | * @param title a string. | |
| 350 | */ | |
| 351 | void setTitle(String title); | |
| 352 | ||
| 353 | /** | |
| 354 | * Checks if a user exists in this session. | |
| 355 | * | |
| 356 | * @return true if a user exists in this session. | |
| 357 | */ | |
| 358 | boolean userExists(); | |
| 359 | ||
| 360 | /** | |
| 361 | * Gets the user. | |
| 362 | * | |
| 363 | * @return a user. | |
| 364 | */ | |
| 365 | User getUser(); | |
| 366 | ||
| 367 | /** | |
| 368 | * Sets the user. | |
| 369 | * | |
| 370 | * @param user a user. | |
| 371 | */ | |
| 372 | void setUser(User user); | |
| 373 | ||
| 374 | /** | |
| 375 | * Attempts to get the user from the session. If it does | |
| 376 | * not exist, it returns null. | |
| 377 | * | |
| 378 | * @return a user. | |
| 379 | */ | |
| 380 | User getUserFromSession(); | |
| 381 | ||
| 382 | /** | |
| 383 | * Allows one to invalidate the user in the default session. | |
| 384 | * | |
| 385 | * @return true if user was invalidated. | |
| 386 | */ | |
| 387 | boolean removeUserFromSession(); | |
| 388 | ||
| 389 | /** | |
| 390 | * Checks to see if out is set. | |
| 391 | * | |
| 392 | * @return true if out is set. | |
| 393 | * @deprecated no replacement planned, response writer will not be cached | |
| 394 | */ | |
| 395 | @Deprecated | |
| 396 | boolean isOutSet(); | |
| 397 | ||
| 398 | /** | |
| 399 | * Gets the print writer. First time calling this | |
| 400 | * will set the print writer via the response. | |
| 401 | * | |
| 402 | * @return a print writer. | |
| 403 | * @throws IOException | |
| 404 | * @deprecated no replacement planned, response writer will not be cached | |
| 405 | */ | |
| 406 | @Deprecated | |
| 407 | PrintWriter getOut() | |
| 408 | throws IOException; | |
| 409 | ||
| 410 | /** | |
| 411 | * Declares that output will be direct to the response stream, | |
| 412 | * even though getOut() may never be called. Useful for response | |
| 413 | * mechanisms that may call res.getWriter() themselves | |
| 414 | * (such as JSP.) | |
| 415 | */ | |
| 416 | void declareDirectResponse(); | |
| 417 | ||
| 418 | /** | |
| 419 | * Gets the locale. If it has not already been defined with | |
| 420 | * setLocale(), then properties named "locale.default.lang" | |
| 421 | * and "locale.default.country" are checked from the Resource | |
| 422 | * Service and the corresponding locale is returned. If these | |
| 423 | * properties are undefined, JVM's default locale is returned. | |
| 424 | * | |
| 425 | * @return the locale. | |
| 426 | */ | |
| 427 | Locale getLocale(); | |
| 428 | ||
| 429 | /** | |
| 430 | * Sets the locale. | |
| 431 | * | |
| 432 | * @param locale the new locale. | |
| 433 | */ | |
| 434 | void setLocale(Locale locale); | |
| 435 | ||
| 436 | /** | |
| 437 | * Gets the charset. If it has not already been defined with | |
| 438 | * setCharSet(), then a property named "locale.default.charset" | |
| 439 | * is checked from the Resource Service and returned. If this | |
| 440 | * property is undefined, the default charset of the locale | |
| 441 | * is returned. If the locale is undefined, null is returned. | |
| 442 | * | |
| 443 | * @return the name of the charset or null. | |
| 444 | */ | |
| 445 | String getCharSet(); | |
| 446 | ||
| 447 | /** | |
| 448 | * Sets the charset. | |
| 449 | * | |
| 450 | * @param charset the name of the new charset. | |
| 451 | */ | |
| 452 | void setCharSet(String charset); | |
| 453 | ||
| 454 | /** | |
| 455 | * Gets the HTTP content type to return. If a charset | |
| 456 | * has been specified, it is included in the content type. | |
| 457 | * If the charset has not been specified and the main type | |
| 458 | * of the content type is "text", the default charset is | |
| 459 | * included. If the default charset is undefined, but the | |
| 460 | * default locale is defined and it is not the US locale, | |
| 461 | * a locale specific charset is included. | |
| 462 | * | |
| 463 | * @return the content type or an empty string. | |
| 464 | */ | |
| 465 | String getContentType(); | |
| 466 | ||
| 467 | /** | |
| 468 | * Sets the HTTP content type to return. | |
| 469 | * | |
| 470 | * @param ct the new content type. | |
| 471 | */ | |
| 472 | void setContentType(String ct); | |
| 473 | ||
| 474 | /** | |
| 475 | * Gets the redirect URI. If this is set, also make sure to set | |
| 476 | * the status code to 302. | |
| 477 | * | |
| 478 | * @return a string, "" if null. | |
| 479 | */ | |
| 480 | String getRedirectURI(); | |
| 481 | ||
| 482 | /** | |
| 483 | * Sets the redirect uri. If this is set, also make sure to set | |
| 484 | * the status code to 302. | |
| 485 | * | |
| 486 | * @param ruri a string. | |
| 487 | */ | |
| 488 | void setRedirectURI(String ruri); | |
| 489 | ||
| 490 | /** | |
| 491 | * Gets the HTTP status code to return. | |
| 492 | * | |
| 493 | * @return the status. | |
| 494 | */ | |
| 495 | int getStatusCode(); | |
| 496 | ||
| 497 | /** | |
| 498 | * Sets the HTTP status code to return. | |
| 499 | * | |
| 500 | * @param sc the status. | |
| 501 | */ | |
| 502 | void setStatusCode(int sc); | |
| 503 | ||
| 504 | /** | |
| 505 | * Gets an array of system errors. | |
| 506 | * | |
| 507 | * @return a SystemError[]. | |
| 508 | */ | |
| 509 | SystemError[] getSystemErrors(); | |
| 510 | ||
| 511 | /** | |
| 512 | * Adds a critical system error. | |
| 513 | * | |
| 514 | * @param err a system error. | |
| 515 | */ | |
| 516 | void setSystemError(SystemError err); | |
| 517 | ||
| 518 | /** | |
| 519 | * Gets JNDI Contexts. | |
| 520 | * | |
| 521 | * @return a hashtable. | |
| 522 | */ | |
| 523 | Map<String, Context> getJNDIContexts(); | |
| 524 | ||
| 525 | /** | |
| 526 | * Sets JNDI Contexts. | |
| 527 | * | |
| 528 | * @param contexts a hashtable. | |
| 529 | */ | |
| 530 | void setJNDIContexts(Map<String, Context> contexts); | |
| 531 | ||
| 532 | /** | |
| 533 | * Gets the cached server scheme. | |
| 534 | * | |
| 535 | * @return a string. | |
| 536 | */ | |
| 537 | String getServerScheme(); | |
| 538 | ||
| 539 | /** | |
| 540 | * Gets the cached server name. | |
| 541 | * | |
| 542 | * @return a string. | |
| 543 | */ | |
| 544 | String getServerName(); | |
| 545 | ||
| 546 | /** | |
| 547 | * Gets the cached server port. | |
| 548 | * | |
| 549 | * @return an int. | |
| 550 | */ | |
| 551 | int getServerPort(); | |
| 552 | ||
| 553 | /** | |
| 554 | * Gets the cached context path. | |
| 555 | * | |
| 556 | * @return a string. | |
| 557 | */ | |
| 558 | String getContextPath(); | |
| 559 | ||
| 560 | /** | |
| 561 | * Gets the cached script name. | |
| 562 | * | |
| 563 | * @return a string. | |
| 564 | */ | |
| 565 | String getScriptName(); | |
| 566 | ||
| 567 | /** | |
| 568 | * Gets the server data used by the request. | |
| 569 | * | |
| 570 | * @return server data. | |
| 571 | */ | |
| 572 | ServerData getServerData(); | |
| 573 | ||
| 574 | /** | |
| 575 | * Gets the IP address of the client that sent the request. | |
| 576 | * | |
| 577 | * @return a string. | |
| 578 | */ | |
| 579 | String getRemoteAddr(); | |
| 580 | ||
| 581 | /** | |
| 582 | * Gets the qualified name of the client that sent the request. | |
| 583 | * | |
| 584 | * @return a string. | |
| 585 | */ | |
| 586 | String getRemoteHost(); | |
| 587 | ||
| 588 | /** | |
| 589 | * Get the user agent for the request. | |
| 590 | * | |
| 591 | * @return a string. | |
| 592 | */ | |
| 593 | String getUserAgent(); | |
| 594 | ||
| 595 | /** | |
| 596 | * Pulls a user object from the session and increments the access | |
| 597 | * counter and sets the last access date for the object. | |
| 598 | */ | |
| 599 | void populate(); | |
| 600 | ||
| 601 | /** | |
| 602 | * Saves a user object into the session. | |
| 603 | */ | |
| 604 | void save(); | |
| 605 | ||
| 606 | /** | |
| 607 | * Gets the stack trace if set. | |
| 608 | * | |
| 609 | * @return the stack trace. | |
| 610 | */ | |
| 611 | String getStackTrace(); | |
| 612 | ||
| 613 | /** | |
| 614 | * Gets the stack trace exception if set. | |
| 615 | * | |
| 616 | * @return the stack exception. | |
| 617 | */ | |
| 618 | Throwable getStackTraceException(); | |
| 619 | ||
| 620 | /** | |
| 621 | * Sets the stack trace. | |
| 622 | * | |
| 623 | * @param trace the stack trace. | |
| 624 | * @param exp the exception. | |
| 625 | */ | |
| 626 | void setStackTrace(String trace, | |
| 627 | Throwable exp); | |
| 628 | ||
| 629 | /** | |
| 630 | * Gets a table of debug variables. | |
| 631 | * | |
| 632 | * @return a Map of debug variables. | |
| 633 | * @deprecated use {@link #getDebugVariables} instead | |
| 634 | */ | |
| 635 | @Deprecated | |
| 636 | Map<String, Object> getVarDebug(); | |
| 637 | ||
| 638 | /** | |
| 639 | * Sets a name/value pair in an internal Map that is accessible from the | |
| 640 | * Error screen. This is a good way to get debugging information | |
| 641 | * when an exception is thrown. | |
| 642 | * | |
| 643 | * @param name name of the variable | |
| 644 | * @param value value of the variable. | |
| 645 | */ | |
| 646 | void setDebugVariable(String name, Object value); | |
| 647 | ||
| 648 | /** | |
| 649 | * Gets a Map of debug variables. | |
| 650 | * | |
| 651 | * @return a Map of debug variables. | |
| 652 | */ | |
| 653 | Map<String, Object> getDebugVariables(); | |
| 654 | } |