0001: /*
0002: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
0003: * Distributed under the terms of either:
0004: * - the common development and distribution license (CDDL), v1.0; or
0005: * - the GNU Lesser General Public License, v2.1 or later
0006: * $Id: ElementSupport.java 3846 2007-07-11 11:33:53Z gbevin $
0007: */
0008: package com.uwyn.rife.engine;
0009:
0010: import java.io.OutputStream;
0011: import java.io.Serializable;
0012: import java.util.*;
0013:
0014: import javax.servlet.ServletContext;
0015: import javax.servlet.http.Cookie;
0016: import javax.servlet.http.HttpServletRequest;
0017: import javax.servlet.http.HttpServletResponse;
0018:
0019: import com.uwyn.rife.continuations.ContinuableObject;
0020: import com.uwyn.rife.continuations.ContinuationContext;
0021: import com.uwyn.rife.continuations.exceptions.ContinuationsNotActiveException;
0022: import com.uwyn.rife.engine.exceptions.*;
0023: import com.uwyn.rife.template.Template;
0024: import com.uwyn.rife.template.TemplateTransformer;
0025: import com.uwyn.rife.template.exceptions.TemplateException;
0026: import com.uwyn.rife.tools.*;
0027: import com.uwyn.rife.tools.exceptions.ConversionException;
0028: import com.uwyn.rife.tools.exceptions.SerializationUtilsErrorException;
0029:
0030: /**
0031: * <p>The <code>ElementSupport</code> class provides all the methods to
0032: * communicate from inside an element with the context in which it is being
0033: * executed.
0034: *
0035: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
0036: * @version $Revision: 3846 $
0037: * @see ElementAware
0038: * @since 1.0
0039: */
0040: public class ElementSupport implements ContinuableObject, Cloneable {
0041: private ElementAware mElementAware = null;
0042: private transient ElementInfo mElementInfo = null;
0043: private transient ElementContext mElementContext = null;
0044: private boolean mRequestAccessEnabled = true;
0045:
0046: private ElementInitializer mInitializer = null;
0047: private ElementChildTrigger mChildTrigger = null;
0048: private Class mDeploymentClass = null;
0049: private boolean mProhibitRawAccess = true;
0050: private boolean mCloneContinuations = true;
0051:
0052: protected ElementSupport() {
0053: }
0054:
0055: /**
0056: * Sets the <code>ElementInitializer</code> class that will be used to
0057: * initialize the element.
0058: * <p>Customizing the initialization can also simply be done by
0059: * overloading the <code>initialize()</code> method if the element extends
0060: * the {@link Element} class.
0061: *
0062: * @param initializer the initializer
0063: * @see #initialize()
0064: * @see ElementInitializer
0065: * @since 1.0
0066: */
0067: public void setInitializer(ElementInitializer initializer) {
0068: mInitializer = initializer;
0069: }
0070:
0071: /**
0072: * Initializes the element, this method should never be called explicitly.
0073: * <p>The initialization happens in a fully setup context and is the first
0074: * method that will be called by the engine.
0075: * <p>The default implementation executes the {@link ElementInitializer}
0076: * that has been registered with {@link #setInitializer}.
0077: *
0078: * @see #setInitializer(ElementInitializer)
0079: * @since 1.0
0080: */
0081: public void initialize() {
0082: if (mInitializer != null) {
0083: mInitializer.initialize();
0084: }
0085: }
0086:
0087: /**
0088: * Sets the <code>ElementChildTrigger</code> class that will be used to
0089: * child trigger is executed.
0090: * <p>Customizing the child trigger can also simply be done by overloading
0091: * the <code>childTriggered()</code> method if the element extends the
0092: * {@link Element} class.
0093: *
0094: * @param childTrigger the child trigger
0095: * @see #childTriggered(String, String[])
0096: * @see ElementChildTrigger
0097: * @since 1.0
0098: */
0099: public void setChildTrigger(ElementChildTrigger childTrigger) {
0100: mChildTrigger = childTrigger;
0101: }
0102:
0103: /**
0104: * Called by the engine when a child trigger occurs, this method should
0105: * never be called explicitly.
0106: * <p>The default implementation executes the {@link ElementChildTrigger}
0107: * that has been registered with {@link #setChildTrigger}.
0108: *
0109: * @param name the name of the variable that initiated the child trigger
0110: * @param values the values of the variable that initiated the child
0111: * trigger
0112: * @return <code>true</code> if the execution should be interrupted and
0113: * step down the inheritance stack (ie. when the activation of the child
0114: * has been triggered); or
0115: * <p><code>false</code> if the execution should just continue
0116: * @see #setChildTrigger(ElementChildTrigger)
0117: * @since 1.0
0118: */
0119: public boolean childTriggered(String name, String[] values) {
0120: if (null == mChildTrigger) {
0121: throw new ChildTriggerNotImplementedException(getClass()
0122: .getName(), name);
0123: }
0124:
0125: return mChildTrigger.childTriggered(name, values);
0126: }
0127:
0128: /**
0129: * Set the <code>ElementDeployer</code> class that will be used for
0130: * deployment.
0131: * <p>An instance of this class will be created when the element is
0132: * deployed within a site. The instance's {@link ElementDeployer#deploy()}
0133: * method will be called. This is handy if you need to setup
0134: * element-specific resources for all its instances.
0135: * <p>Customizing the element deployer can also simply be done by
0136: * overloading the <code>getDeploymentClass()</code> method if the element
0137: * extends the {@link Element} class.
0138: *
0139: * @param klass the <code>ElementDeployer</code> that will be used to
0140: * deploy the element
0141: * @see ElementDeployer#deploy()
0142: * @see #getDeploymentClass()
0143: * @see #getDeployer()
0144: * @since 1.0
0145: */
0146: public void setDeploymentClass(
0147: Class<? extends ElementDeployer> klass) {
0148: mDeploymentClass = klass;
0149: }
0150:
0151: /**
0152: * Retrieves the class that will be used for the deployment of the
0153: * element.
0154: *
0155: * @return an instance of <code>ElementDeployer</code>; or
0156: * <p>null if no deployment class is used
0157: * @see #setDeploymentClass(Class)
0158: * @see #getDeployer()
0159: * @since 1.0
0160: */
0161: public Class getDeploymentClass() {
0162: return mDeploymentClass;
0163: }
0164:
0165: /**
0166: * Changes the access permissions to raw servlet API methods.
0167: * <p>By default, RIFE shields you away from raw access to the servlet API
0168: * and controls all incoming and outgoing data. This makes it possible to
0169: * offer the advanced engine features.
0170: * <p>Sometimes it's useful however to still be able to access the raw
0171: * servlet API features, for instance when integrating other libraries.
0172: * The fact that a method needs to be called before being able to do so
0173: * makes it easy to identify which elements are outside of the controlled
0174: * context of the RIFE application.
0175: *
0176: * @param access <code>true</code> if the raw servlet API access is
0177: * prohibited; or
0178: * <p><code>false</code> if it is allowed
0179: * @see #prohibitRawAccess()
0180: * @since 1.0
0181: */
0182: public void setProhibitRawAccess(boolean access) {
0183: mProhibitRawAccess = access;
0184: }
0185:
0186: /**
0187: * Indicates whether the access to raw servlet API methods is allowed.
0188: * <p>Instead of using the {@link #setProhibitRawAccess(boolean)} method,
0189: * one can also overload this method to allow raw access. By default, raw
0190: * access is forbidden.
0191: *
0192: * @return <code>true</code> if the raw servlet API access is prohibited;
0193: * or
0194: * <p><code>false</code> if it is allowed
0195: * @see #setProhibitRawAccess(boolean)
0196: * @since 1.0
0197: */
0198: public boolean prohibitRawAccess() {
0199: return mProhibitRawAccess;
0200: }
0201:
0202: /**
0203: * Changes the engine's behavior when new continuation steps are created.
0204: * <p>By default, the active continuation is cloned when a new step needs
0205: * to be created. This makes it possible to use the browser's back button
0206: * and start a new continuation trail. Each previous step thus keeps it
0207: * associated state. By disabling the cloning, performance will increase
0208: * and memory usage will decrease since the active continuation will
0209: * simply be migrated to the new continuation step. Note that none of the
0210: * previous steps will be usable anymore though.
0211: *
0212: * @param clone <code>true</code> to make the engine clone continuations;
0213: * or
0214: * <p><code>false</code> to disable the cloning
0215: * @see #cloneContinuations()
0216: * @since 1.0
0217: */
0218: public void setCloneContinuations(boolean clone) {
0219: mCloneContinuations = clone;
0220: }
0221:
0222: /**
0223: * Indicates whether continuations are cloned at each step.
0224: * <p>Instead of using the {@link #setCloneContinuations(boolean)} method,
0225: * one can also overload this method to configure the cloning. By default,
0226: * cloning is active.
0227: *
0228: * @return <code>true</code> to make the engine clone continuations; or
0229: * <p><code>false</code> to disable the cloning
0230: * @see #setCloneContinuations (boolean)
0231: * @since 1.0
0232: */
0233: public boolean cloneContinuations() {
0234: return mCloneContinuations;
0235: }
0236:
0237: /**
0238: * Pauses the execution of the element and creates a new continuation.
0239: * <p>The next request will resume exactly at the same location with a
0240: * completely restored call stack and variable stack.
0241: *
0242: * @since 1.0
0243: */
0244: public final void pause() {
0245: // this is deliberately empty since the continuation support
0246: // rewrites method calls to pause
0247: throw new ContinuationsNotActiveException();
0248: }
0249:
0250: /**
0251: * Steps back to the start of the previous continuation.
0252: * <p>If there is no previous continuation, the element will be executed
0253: * from the beginning again.
0254: *
0255: * @see #duringStepBack
0256: * @since 1.5
0257: */
0258: public final void stepBack() {
0259: // this is deliberately empty since the continuation support
0260: // rewrites method calls to pause
0261: throw new ContinuationsNotActiveException();
0262: }
0263:
0264: /**
0265: * Indicates whether the current element execution is a step back.
0266: *
0267: * @return <code>true</code> if a step back occurred in this request; or
0268: * <p><code>false</code> otherwise
0269: * @see #stepBack
0270: * @since 1.5
0271: */
0272: public boolean duringStepBack() {
0273: return mElementContext.duringStepBack();
0274: }
0275:
0276: /**
0277: * Pauses the execution of the element and creates a new continuation. The
0278: * execution will immediately continue in the element that is the target
0279: * of the called exit.
0280: * <p>As soon as the called element returns or executes {@link #answer()},
0281: * the execution will resume in the calling element with a completely
0282: * restored call stack and variable stack.
0283: *
0284: * @param exit the name of the exit whose target element will be called
0285: * @return the object that was provided through the {@link #answer(Object)}
0286: * method in the called element; or
0287: * <p><code>null</code> if no answer was provided
0288: * @see #answer()
0289: * @see #answer(Object)
0290: * @since 1.0
0291: */
0292: public final Object call(String exit) {
0293: // this is deliberately empty since the continuation support
0294: // rewrites method calls to call
0295: throw new ContinuationsNotActiveException();
0296: }
0297:
0298: /**
0299: * Resumes the execution in the calling element by providing no answer
0300: * object.
0301: * <p>The execution in the active element will be interrupted immediately
0302: * and the call continuation will be resumed exactly where is was paused
0303: * before.
0304: *
0305: * @exception com.uwyn.rife.engine.exceptions.EngineException a runtime
0306: * exception that is used to immediately interrupt the execution, don't
0307: * catch this exception
0308: * @see #call(String)
0309: * @see #answer(Object)
0310: * @since 1.0
0311: */
0312: public final void answer() throws EngineException {
0313: // this is deliberately empty since the continuation support
0314: // rewrites method calls to answer
0315: throw new ContinuationsNotActiveException();
0316: }
0317:
0318: /**
0319: * Resumes the execution in the calling element by providing an answer.
0320: * <p>The execution in the active element will be interrupted immediately
0321: * and the call continuation will be resumed exactly where is was paused
0322: * before.
0323: *
0324: * @param answer the object that will be answered to the calling element
0325: * @exception com.uwyn.rife.engine.exceptions.EngineException a runtime
0326: * exception that is used to immediately interrupt the execution, don't
0327: * catch this exception
0328: * @see #call(String)
0329: * @see #answer()
0330: * @since 1.0
0331: */
0332: public final void answer(Object answer) throws EngineException {
0333: // this is deliberately empty since the continuation support
0334: // rewrites method calls to answer
0335: throw new ContinuationsNotActiveException();
0336: }
0337:
0338: /**
0339: * Creates a new template instance of the {@link
0340: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEHTML enginehtml}
0341: * type, using the current element's absolute ID as the template name.
0342: * <p>If the element is an arrival, the absolute ID of the real element it
0343: * points to will be used.
0344: *
0345: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0346: * error occurred during the retrieval, parsing or compilation of the
0347: * template
0348: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0349: * occurs during the initialization of the template in the element
0350: * context; or if you don't have access to the request data (eg. you're
0351: * inside a child trigger); or if there's no active element context (eg.
0352: * you're using this method inside the constructor instead of inside the
0353: * {@link #initialize()} method)
0354: * @return a new instance of the template
0355: * @see #getHtmlTemplate(String)
0356: * @see #getHtmlTemplate(String, TemplateTransformer)
0357: * @see #getHtmlTemplate(String, String)
0358: * @see #getHtmlTemplate(String, String, TemplateTransformer)
0359: * @since 1.3
0360: */
0361: public Template getHtmlTemplate() throws TemplateException,
0362: EngineException {
0363: return getHtmlTemplate(getElementInfo().getReferenceId()
0364: .substring(1), null, null);
0365: }
0366:
0367: /**
0368: * Creates a new template instance of the {@link
0369: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEHTML enginehtml}
0370: * type.
0371: *
0372: * @param name the name of the template. Note that this follows the Java
0373: * naming conventions for classes and packages. Directories correspond to
0374: * package names and file separators correspond to dots. Any non-valid
0375: * class name character will be replaced by an underscore.
0376: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0377: * error occurred during the retrieval, parsing or compilation of the
0378: * template
0379: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0380: * occurs during the initialization of the template in the element
0381: * context; or if you don't have access to the request data (eg. you're
0382: * inside a child trigger); or if there's no active element context (eg.
0383: * you're using this method inside the constructor instead of inside the
0384: * {@link #initialize()} method)
0385: * @return a new instance of the template
0386: * @see #getHtmlTemplate()
0387: * @see #getHtmlTemplate(String, TemplateTransformer)
0388: * @see #getHtmlTemplate(String, String)
0389: * @see #getHtmlTemplate(String, String, TemplateTransformer)
0390: * @since 1.0
0391: */
0392: public Template getHtmlTemplate(String name)
0393: throws TemplateException, EngineException {
0394: return getHtmlTemplate(name, null, null);
0395: }
0396:
0397: /**
0398: * Creates a new template instance of the {@link
0399: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEHTML enginehtml}
0400: * type.
0401: *
0402: * @param name the name of the template. Note that this follows the Java
0403: * naming conventions for classes and packages. Directories correspond to
0404: * package names and file separators correspond to dots. Any non-valid
0405: * class name character will be replaced by an underscore.
0406: * @param transformer the template transformer that will be used to modify
0407: * the template's source before it's parsed
0408: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0409: * error occurred during the retrieval, parsing or compilation of the
0410: * template
0411: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0412: * occurs during the initialization of the template in the element
0413: * context; or if you don't have access to the request data (eg. you're
0414: * inside a child trigger); or if there's no active element context (eg.
0415: * you're using this method inside the constructor instead of inside the
0416: * {@link #initialize()} method)
0417: * @return a new instance of the template
0418: * @see #getHtmlTemplate()
0419: * @see #getHtmlTemplate(String)
0420: * @see #getHtmlTemplate(String, String)
0421: * @see #getHtmlTemplate(String, String, TemplateTransformer)
0422: * @since 1.0
0423: */
0424: public Template getHtmlTemplate(String name,
0425: TemplateTransformer transformer) throws TemplateException,
0426: EngineException {
0427: return getHtmlTemplate(name, null, transformer);
0428: }
0429:
0430: /**
0431: * Creates a new template instance of the {@link
0432: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEHTML enginehtml}
0433: * type.
0434: *
0435: * @param name the name of the template. Note that this follows the Java
0436: * naming conventions for classes and packages. Directories correspond to
0437: * package names and file separators correspond to dots. Any non-valid
0438: * class name character will be replaced by an underscore.
0439: * @param encoding the encoding of the template's source
0440: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0441: * error occurred during the retrieval, parsing or compilation of the
0442: * template
0443: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0444: * occurs during the initialization of the template in the element
0445: * context; or if you don't have access to the request data (eg. you're
0446: * inside a child trigger); or if there's no active element context (eg.
0447: * you're using this method inside the constructor instead of inside the
0448: * {@link #initialize()} method)
0449: * @return a new instance of the template
0450: * @see #getHtmlTemplate()
0451: * @see #getHtmlTemplate(String)
0452: * @see #getHtmlTemplate(String, TemplateTransformer)
0453: * @see #getHtmlTemplate(String, String, TemplateTransformer)
0454: * @since 1.0
0455: */
0456: public Template getHtmlTemplate(String name, String encoding)
0457: throws TemplateException, EngineException {
0458: return getHtmlTemplate(name, encoding, null);
0459: }
0460:
0461: /**
0462: * Creates a new template instance of the {@link
0463: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEHTML enginehtml}
0464: * type.
0465: * <p>The special engine template types contain additional block and value
0466: * filters to offer the following features:
0467: * <ul>
0468: * <li>embedded elements<br>(eg.: <code><!--V
0469: * 'ELEMENT:my.elementid'/--></code>)
0470: * <li>role user context for scripted block assignment to values<br>(eg<code>.:
0471: * <!--V 'OGNL:ROLEUSER:rolecheck'-->User is not in role
0472: * "admin"<!--/V--><br><!--B 'OGNL:ROLEUSER:rolecheck:[[
0473: * isInRole("admin") ]]'-->User is in role "admin"<!--/B--></code>)
0474: * </ul>
0475: * <p>Non-engine versions of the same template types are not able to
0476: * provide these functionalities.
0477: *
0478: * @param name the name of the template. Note that this follows the Java
0479: * naming conventions for classes and packages. Directories correspond to
0480: * package names and file separators correspond to dots. Any non-valid
0481: * class name character will be replaced by an underscore.
0482: * @param encoding the encoding of the template's source
0483: * @param transformer the template transformer that will be used to modify
0484: * the template's source before it's parsed
0485: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0486: * error occurred during the retrieval, parsing or compilation of the
0487: * template
0488: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0489: * occurs during the initialization of the template in the element
0490: * context; or if you don't have access to the request data (eg. you're
0491: * inside a child trigger); or if there's no active element context (eg.
0492: * you're using this method inside the constructor instead of inside the
0493: * {@link #initialize()} method)
0494: * @return a new instance of the template
0495: * @see #getHtmlTemplate()
0496: * @see #getHtmlTemplate(String)
0497: * @see #getHtmlTemplate(String, TemplateTransformer)
0498: * @see #getHtmlTemplate(String, String)
0499: * @since 1.0
0500: */
0501: public Template getHtmlTemplate(String name, String encoding,
0502: TemplateTransformer transformer) throws TemplateException,
0503: EngineException {
0504: if (!mRequestAccessEnabled)
0505: throw new RequestAccessDeniedException();
0506: if (null == mElementContext)
0507: throw new ElementContextMissingException();
0508:
0509: return mElementContext.getHtmlTemplate(name, encoding,
0510: transformer);
0511: }
0512:
0513: /**
0514: * Creates a new template instance of the {@link
0515: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXHTML
0516: * enginexhtml} type, using the current element's absolute ID as the
0517: * template name.
0518: *
0519: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0520: * error occurred during the retrieval, parsing or compilation of the
0521: * template
0522: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0523: * occurs during the initialization of the template in the element
0524: * context; or if you don't have access to the request data (eg. you're
0525: * inside a child trigger); or if there's no active element context (eg.
0526: * you're using this method inside the constructor instead of inside the
0527: * {@link #initialize()} method)
0528: * @return a new instance of the template
0529: * @see #getXhtmlTemplate(String)
0530: * @see #getXhtmlTemplate(String, TemplateTransformer)
0531: * @see #getXhtmlTemplate(String, String)
0532: * @see #getXhtmlTemplate(String, String, TemplateTransformer)
0533: * @since 1.3
0534: */
0535: public Template getXhtmlTemplate() throws TemplateException,
0536: EngineException {
0537: return getXhtmlTemplate(getElementInfo().getReferenceId()
0538: .substring(1), null, null);
0539: }
0540:
0541: /**
0542: * Creates a new template instance of the {@link
0543: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXHTML
0544: * enginexhtml} type.
0545: *
0546: * @param name the name of the template. Note that this follows the Java
0547: * naming conventions for classes and packages. Directories correspond to
0548: * package names and file separators correspond to dots. Any non-valid
0549: * class name character will be replaced by an underscore.
0550: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0551: * error occurred during the retrieval, parsing or compilation of the
0552: * template
0553: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0554: * occurs during the initialization of the template in the element
0555: * context; or if you don't have access to the request data (eg. you're
0556: * inside a child trigger); or if there's no active element context (eg.
0557: * you're using this method inside the constructor instead of inside the
0558: * {@link #initialize()} method)
0559: * @return a new instance of the template
0560: * @see #getXhtmlTemplate()
0561: * @see #getXhtmlTemplate(String, TemplateTransformer)
0562: * @see #getXhtmlTemplate(String, String)
0563: * @see #getXhtmlTemplate(String, String, TemplateTransformer)
0564: * @since 1.0
0565: */
0566: public Template getXhtmlTemplate(String name)
0567: throws TemplateException, EngineException {
0568: return getXhtmlTemplate(name, null, null);
0569: }
0570:
0571: /**
0572: * Creates a new template instance of the {@link
0573: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXHTML
0574: * enginexhtml} type.
0575: *
0576: * @param name the name of the template. Note that this follows the Java
0577: * naming conventions for classes and packages. Directories correspond to
0578: * package names and file separators correspond to dots. Any non-valid
0579: * class name character will be replaced by an underscore.
0580: * @param transformer the template transformer that will be used to modify
0581: * the template's source before it's parsed
0582: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0583: * error occurred during the retrieval, parsing or compilation of the
0584: * template
0585: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0586: * occurs during the initialization of the template in the element
0587: * context; or if you don't have access to the request data (eg. you're
0588: * inside a child trigger); or if there's no active element context (eg.
0589: * you're using this method inside the constructor instead of inside the
0590: * {@link #initialize()} method)
0591: * @return a new instance of the template
0592: * @see #getXhtmlTemplate()
0593: * @see #getXhtmlTemplate(String)
0594: * @see #getXhtmlTemplate(String, String)
0595: * @see #getXhtmlTemplate(String, String, TemplateTransformer)
0596: * @since 1.0
0597: */
0598: public Template getXhtmlTemplate(String name,
0599: TemplateTransformer transformer) throws TemplateException,
0600: EngineException {
0601: return getXhtmlTemplate(name, null, transformer);
0602: }
0603:
0604: /**
0605: * Creates a new template instance of the {@link
0606: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXHTML
0607: * enginexhtml} type.
0608: *
0609: * @param name the name of the template. Note that this follows the Java
0610: * naming conventions for classes and packages. Directories correspond to
0611: * package names and file separators correspond to dots. Any non-valid
0612: * class name character will be replaced by an underscore.
0613: * @param encoding the encoding of the template's source
0614: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0615: * error occurred during the retrieval, parsing or compilation of the
0616: * template
0617: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0618: * occurs during the initialization of the template in the element
0619: * context; or if you don't have access to the request data (eg. you're
0620: * inside a child trigger); or if there's no active element context (eg.
0621: * you're using this method inside the constructor instead of inside the
0622: * {@link #initialize()} method)
0623: * @return a new instance of the template
0624: * @see #getXhtmlTemplate()
0625: * @see #getXhtmlTemplate(String)
0626: * @see #getXhtmlTemplate(String, TemplateTransformer)
0627: * @see #getXhtmlTemplate(String, String, TemplateTransformer)
0628: * @since 1.0
0629: */
0630: public Template getXhtmlTemplate(String name, String encoding)
0631: throws TemplateException, EngineException {
0632: return getXhtmlTemplate(name, encoding, null);
0633: }
0634:
0635: /**
0636: * Creates a new template instance of the {@link
0637: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXHTML
0638: * enginexhtml} type.
0639: * <p>The special engine template types contain additional block and value
0640: * filters to offer the following features:
0641: * <ul>
0642: * <li>embedded elements<br>(eg.: <code><!--V
0643: * 'ELEMENT:my.elementid'/--></code>)
0644: * <li>role user context for scripted block assignment to values<br>(eg<code>.:
0645: * <!--V 'OGNL:ROLEUSER:rolecheck'-->User is not in role
0646: * "admin"<!--/V--><br><!--B 'OGNL:ROLEUSER:rolecheck:[[
0647: * isInRole("admin") ]]'-->User is in role "admin"<!--/B--></code>)
0648: * </ul>
0649: * <p>Non-engine versions of the same template types are not able to
0650: * provide these functionalities.
0651: *
0652: * @param name the name of the template. Note that this follows the Java
0653: * naming conventions for classes and packages. Directories correspond to
0654: * package names and file separators correspond to dots. Any non-valid
0655: * class name character will be replaced by an underscore.
0656: * @param encoding the encoding of the template's source
0657: * @param transformer the template transformer that will be used to modify
0658: * the template's source before it's parsed
0659: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0660: * error occurred during the retrieval, parsing or compilation of the
0661: * template
0662: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0663: * occurs during the initialization of the template in the element
0664: * context; or if you don't have access to the request data (eg. you're
0665: * inside a child trigger); or if there's no active element context (eg.
0666: * you're using this method inside the constructor instead of inside the
0667: * {@link #initialize()} method)
0668: * @return a new instance of the template
0669: * @see #getXhtmlTemplate()
0670: * @see #getXhtmlTemplate(String)
0671: * @see #getXhtmlTemplate(String, TemplateTransformer)
0672: * @see #getXhtmlTemplate(String, String)
0673: * @since 1.0
0674: */
0675: public Template getXhtmlTemplate(String name, String encoding,
0676: TemplateTransformer transformer) throws TemplateException,
0677: EngineException {
0678: if (!mRequestAccessEnabled)
0679: throw new RequestAccessDeniedException();
0680: if (null == mElementContext)
0681: throw new ElementContextMissingException();
0682:
0683: return mElementContext.getXhtmlTemplate(name, encoding,
0684: transformer);
0685: }
0686:
0687: /**
0688: * Creates a new template instance of the {@link
0689: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXML enginexml}
0690: * type, using the current element's absolute ID as the template name.
0691: *
0692: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0693: * error occurred during the retrieval, parsing or compilation of the
0694: * template
0695: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0696: * occurs during the initialization of the template in the element
0697: * context; or if you don't have access to the request data (eg. you're
0698: * inside a child trigger); or if there's no active element context (eg.
0699: * you're using this method inside the constructor instead of inside the
0700: * {@link #initialize()} method)
0701: * @return a new instance of the template
0702: * @see #getXmlTemplate(String)
0703: * @see #getXmlTemplate(String, TemplateTransformer)
0704: * @see #getXmlTemplate(String, String)
0705: * @see #getXmlTemplate(String, String, TemplateTransformer)
0706: * @since 1.3
0707: */
0708: public Template getXmlTemplate() throws TemplateException,
0709: EngineException {
0710: return getXmlTemplate(getElementInfo().getReferenceId()
0711: .substring(1), null, null);
0712: }
0713:
0714: /**
0715: * Creates a new template instance of the {@link
0716: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXML enginexml}
0717: * type.
0718: *
0719: * @param name the name of the template. Note that this follows the Java
0720: * naming conventions for classes and packages. Directories correspond to
0721: * package names and file separators correspond to dots. Any non-valid
0722: * class name character will be replaced by an underscore.
0723: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0724: * error occurred during the retrieval, parsing or compilation of the
0725: * template
0726: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0727: * occurs during the initialization of the template in the element
0728: * context; or if you don't have access to the request data (eg. you're
0729: * inside a child trigger); or if there's no active element context (eg.
0730: * you're using this method inside the constructor instead of inside the
0731: * {@link #initialize()} method)
0732: * @return a new instance of the template
0733: * @see #getXmlTemplate()
0734: * @see #getXmlTemplate(String, TemplateTransformer)
0735: * @see #getXmlTemplate(String, String)
0736: * @see #getXmlTemplate(String, String, TemplateTransformer)
0737: * @since 1.0
0738: */
0739: public Template getXmlTemplate(String name)
0740: throws TemplateException, EngineException {
0741: return getXmlTemplate(name, null, null);
0742: }
0743:
0744: /**
0745: * Creates a new template instance of the {@link
0746: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXML enginexml}
0747: * type.
0748: *
0749: * @param name the name of the template. Note that this follows the Java
0750: * naming conventions for classes and packages. Directories correspond to
0751: * package names and file separators correspond to dots. Any non-valid
0752: * class name character will be replaced by an underscore.
0753: * @param transformer the template transformer that will be used to modify
0754: * the template's source before it's parsed
0755: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0756: * error occurred during the retrieval, parsing or compilation of the
0757: * template
0758: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0759: * occurs during the initialization of the template in the element
0760: * context; or if you don't have access to the request data (eg. you're
0761: * inside a child trigger); or if there's no active element context (eg.
0762: * you're using this method inside the constructor instead of inside the
0763: * {@link #initialize()} method)
0764: * @return a new instance of the template
0765: * @see #getXmlTemplate(String)
0766: * @see #getXmlTemplate(String)
0767: * @see #getXmlTemplate(String, String)
0768: * @see #getXmlTemplate(String, String, TemplateTransformer)
0769: * @since 1.0
0770: */
0771: public Template getXmlTemplate(String name,
0772: TemplateTransformer transformer) throws TemplateException,
0773: EngineException {
0774: return getXmlTemplate(name, null, transformer);
0775: }
0776:
0777: /**
0778: * Creates a new template instance of the {@link
0779: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXML enginexml}
0780: * type.
0781: *
0782: * @param name the name of the template. Note that this follows the Java
0783: * naming conventions for classes and packages. Directories correspond to
0784: * package names and file separators correspond to dots. Any non-valid
0785: * class name character will be replaced by an underscore.
0786: * @param encoding the encoding of the template's source
0787: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0788: * error occurred during the retrieval, parsing or compilation of the
0789: * template
0790: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0791: * occurs during the initialization of the template in the element
0792: * context; or if you don't have access to the request data (eg. you're
0793: * inside a child trigger); or if there's no active element context (eg.
0794: * you're using this method inside the constructor instead of inside the
0795: * {@link #initialize()} method)
0796: * @return a new instance of the template
0797: * @see #getXmlTemplate(String)
0798: * @see #getXmlTemplate(String)
0799: * @see #getXmlTemplate(String, TemplateTransformer)
0800: * @see #getXmlTemplate(String, String, TemplateTransformer)
0801: * @since 1.0
0802: */
0803: public Template getXmlTemplate(String name, String encoding)
0804: throws TemplateException, EngineException {
0805: return getXmlTemplate(name, encoding, null);
0806: }
0807:
0808: /**
0809: * Creates a new template instance of the {@link
0810: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXML enginexml}
0811: * type.
0812: * <p>The special engine template types contain additional block and value
0813: * filters to offer the following features:
0814: * <ul>
0815: * <li>embedded elements<br>(eg.: <code><!--V
0816: * 'ELEMENT:my.elementid'/--></code>)
0817: * <li>role user context for scripted block assignment to values<br>(eg<code>.:
0818: * <!--V 'OGNL:ROLEUSER:rolecheck'-->User is not in role
0819: * "admin"<!--/V--><br><!--B 'OGNL:ROLEUSER:rolecheck:[[
0820: * isInRole("admin") ]]'-->User is in role "admin"<!--/B--></code>)
0821: * </ul>
0822: * <p>Non-engine versions of the same template types are not able to
0823: * provide these functionalities.
0824: *
0825: * @param name the name of the template. Note that this follows the Java
0826: * naming conventions for classes and packages. Directories correspond to
0827: * package names and file separators correspond to dots. Any non-valid
0828: * class name character will be replaced by an underscore.
0829: * @param encoding the encoding of the template's source
0830: * @param transformer the template transformer that will be used to modify
0831: * the template's source before it's parsed
0832: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0833: * error occurred during the retrieval, parsing or compilation of the
0834: * template
0835: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0836: * occurs during the initialization of the template in the element
0837: * context; or if you don't have access to the request data (eg. you're
0838: * inside a child trigger); or if there's no active element context (eg.
0839: * you're using this method inside the constructor instead of inside the
0840: * {@link #initialize()} method)
0841: * @return a new instance of the template
0842: * @see #getXmlTemplate(String)
0843: * @see #getXmlTemplate(String)
0844: * @see #getXmlTemplate(String, TemplateTransformer)
0845: * @see #getXmlTemplate(String, String)
0846: * @since 1.0
0847: */
0848: public Template getXmlTemplate(String name, String encoding,
0849: TemplateTransformer transformer) throws TemplateException,
0850: EngineException {
0851: if (!mRequestAccessEnabled)
0852: throw new RequestAccessDeniedException();
0853: if (null == mElementContext)
0854: throw new ElementContextMissingException();
0855:
0856: return mElementContext.getXmlTemplate(name, encoding,
0857: transformer);
0858: }
0859:
0860: /**
0861: * Creates a new template instance of the {@link
0862: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINETXT enginetxt}
0863: * type, using the current element's absolute ID as the template name.
0864: *
0865: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0866: * error occurred during the retrieval, parsing or compilation of the
0867: * template
0868: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0869: * occurs during the initialization of the template in the element
0870: * context; or if you don't have access to the request data (eg. you're
0871: * inside a child trigger); or if there's no active element context (eg.
0872: * you're using this method inside the constructor instead of inside the
0873: * {@link #initialize()} method)
0874: * @return a new instance of the template
0875: * @see #getTxtTemplate(String)
0876: * @see #getTxtTemplate(String, TemplateTransformer)
0877: * @see #getTxtTemplate(String, String)
0878: * @see #getTxtTemplate(String, String, TemplateTransformer)
0879: * @since 1.3
0880: */
0881: public Template getTxtTemplate() throws TemplateException,
0882: EngineException {
0883: return getTxtTemplate(getElementInfo().getReferenceId()
0884: .substring(1), null, null);
0885: }
0886:
0887: /**
0888: * Creates a new template instance of the {@link
0889: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINETXT enginetxt}
0890: * type.
0891: *
0892: * @param name the name of the template. Note that this follows the Java
0893: * naming conventions for classes and packages. Directories correspond to
0894: * package names and file separators correspond to dots. Any non-valid
0895: * class name character will be replaced by an underscore.
0896: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0897: * error occurred during the retrieval, parsing or compilation of the
0898: * template
0899: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0900: * occurs during the initialization of the template in the element
0901: * context; or if you don't have access to the request data (eg. you're
0902: * inside a child trigger); or if there's no active element context (eg.
0903: * you're using this method inside the constructor instead of inside the
0904: * {@link #initialize()} method)
0905: * @return a new instance of the template
0906: * @see #getTxtTemplate()
0907: * @see #getTxtTemplate(String, TemplateTransformer)
0908: * @see #getTxtTemplate(String, String)
0909: * @see #getTxtTemplate(String, String, TemplateTransformer)
0910: * @since 1.0
0911: */
0912: public Template getTxtTemplate(String name)
0913: throws TemplateException, EngineException {
0914: return getTxtTemplate(name, null, null);
0915: }
0916:
0917: /**
0918: * Creates a new template instance of the {@link
0919: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINETXT enginetxt}
0920: * type.
0921: *
0922: * @param name the name of the template. Note that this follows the Java
0923: * naming conventions for classes and packages. Directories correspond to
0924: * package names and file separators correspond to dots. Any non-valid
0925: * class name character will be replaced by an underscore.
0926: * @param transformer the template transformer that will be used to modify
0927: * the template's source before it's parsed
0928: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0929: * error occurred during the retrieval, parsing or compilation of the
0930: * template
0931: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0932: * occurs during the initialization of the template in the element
0933: * context; or if you don't have access to the request data (eg. you're
0934: * inside a child trigger); or if there's no active element context (eg.
0935: * you're using this method inside the constructor instead of inside the
0936: * {@link #initialize()} method)
0937: * @return a new instance of the template
0938: * @see #getTxtTemplate()
0939: * @see #getTxtTemplate(String)
0940: * @see #getTxtTemplate(String, String)
0941: * @see #getTxtTemplate(String, String, TemplateTransformer)
0942: * @since 1.0
0943: */
0944: public Template getTxtTemplate(String name,
0945: TemplateTransformer transformer) throws TemplateException,
0946: EngineException {
0947: return getTxtTemplate(name, null, transformer);
0948: }
0949:
0950: /**
0951: * Creates a new template instance of the {@link
0952: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINETXT enginetxt}
0953: * type.
0954: *
0955: * @param name the name of the template. Note that this follows the Java
0956: * naming conventions for classes and packages. Directories correspond to
0957: * package names and file separators correspond to dots. Any non-valid
0958: * class name character will be replaced by an underscore.
0959: * @param encoding the encoding of the template's source
0960: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
0961: * error occurred during the retrieval, parsing or compilation of the
0962: * template
0963: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
0964: * occurs during the initialization of the template in the element
0965: * context; or if you don't have access to the request data (eg. you're
0966: * inside a child trigger); or if there's no active element context (eg.
0967: * you're using this method inside the constructor instead of inside the
0968: * {@link #initialize()} method)
0969: * @return a new instance of the template
0970: * @see #getTxtTemplate()
0971: * @see #getTxtTemplate(String)
0972: * @see #getTxtTemplate(String, TemplateTransformer)
0973: * @see #getTxtTemplate(String, String, TemplateTransformer)
0974: * @since 1.0
0975: */
0976: public Template getTxtTemplate(String name, String encoding)
0977: throws TemplateException, EngineException {
0978: return getTxtTemplate(name, encoding, null);
0979: }
0980:
0981: /**
0982: * Creates a new template instance of the {@link
0983: * com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINETXT enginetxt}
0984: * type.
0985: * <p>The special engine template types contain additional block and value
0986: * filters to offer the following features:
0987: * <ul>
0988: * <li>embedded elements<br>(eg.: <code>[!V 'ELEMENT:my.elementid'/]</code>)
0989: * <li>role user context for scripted block assignment to values<br>(eg<code>.:
0990: * [!V 'OGNL:ROLEUSER:rolecheck']User is not in role "admin"[!/V]<br>[!B
0991: * 'OGNL:ROLEUSER:rolecheck:[[ isInRole("admin") ]]']User is in role
0992: * "admin"[!/B]</code>)
0993: * </ul>
0994: * <p>Non-engine versions of the same template types are not able to
0995: * provide these functionalities.
0996: *
0997: * @param name the name of the template. Note that this follows the Java
0998: * naming conventions for classes and packages. Directories correspond to
0999: * package names and file separators correspond to dots. Any non-valid
1000: * class name character will be replaced by an underscore.
1001: * @param encoding the encoding of the template's source
1002: * @param transformer the template transformer that will be used to modify
1003: * the template's source before it's parsed
1004: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
1005: * error occurred during the retrieval, parsing or compilation of the
1006: * template
1007: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
1008: * occurs during the initialization of the template in the element
1009: * context; or if you don't have access to the request data (eg. you're
1010: * inside a child trigger); or if there's no active element context (eg.
1011: * you're using this method inside the constructor instead of inside the
1012: * {@link #initialize()} method)
1013: * @return a new instance of the template
1014: * @see #getTxtTemplate()
1015: * @see #getTxtTemplate(String)
1016: * @see #getTxtTemplate(String, TemplateTransformer)
1017: * @see #getTxtTemplate(String, String)
1018: * @since 1.0
1019: */
1020: public Template getTxtTemplate(String name, String encoding,
1021: TemplateTransformer transformer) throws TemplateException,
1022: EngineException {
1023: if (!mRequestAccessEnabled)
1024: throw new RequestAccessDeniedException();
1025: if (null == mElementContext)
1026: throw new ElementContextMissingException();
1027:
1028: return mElementContext.getTxtTemplate(name, encoding,
1029: transformer);
1030: }
1031:
1032: /**
1033: * Transforms a provided <code>String</code> object into a new string,
1034: * containing only valid HTML characters.
1035: *
1036: * @param source The string that has to be transformed into a valid HTML
1037: * string.
1038: * @return The encoded <code>String</code> object.
1039: * @see #encodeXml(String)
1040: * @since 1.0
1041: */
1042: public String encodeHtml(String source) {
1043: return StringUtils.encodeHtml(source);
1044: }
1045:
1046: /**
1047: * Transforms a provided <code>String</code> object into a new string,
1048: * containing only valid XML characters.
1049: *
1050: * @param source The string that has to be transformed into a valid XML
1051: * string.
1052: * @return The encoded <code>String</code> object.
1053: * @see #encodeHtml(String)
1054: * @since 1.0
1055: */
1056: public String encodeXml(String source) {
1057: return StringUtils.encodeXml(source);
1058: }
1059:
1060: /**
1061: * Enables or disables the response text buffer. By default, it is
1062: * enabled.
1063: * <p>Disabling an enabled text buffer, flushes the already buffered
1064: * content first.
1065: * <p>If the text buffer is disabled, text content will be send
1066: * immediately to the client, this can decrease performance. Unless you
1067: * need to stream content in real time, it's best to leave the text buffer
1068: * enabled. It will be flushed and sent in one go at the end of the
1069: * request.
1070: * <p>Exits that cancel embedding rely on the fact that the text buffer is
1071: * active to be able to discard the partial content of the embedding
1072: * element.
1073: *
1074: * @param enabled <code>true</code> to enable the text buffer; or
1075: * <p><code>false</code> to disable it
1076: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
1077: * occurred during the modification of the text buffer presence; or if you
1078: * don't have access to the request data (eg. you're inside a child
1079: * trigger); or if there's no active element context (eg. you're using
1080: * this method inside the constructor instead of inside the {@link
1081: * #initialize()} method)
1082: * @see #isTextBufferEnabled()
1083: * @see #flush()
1084: * @see #clearBuffer()
1085: * @since 1.0
1086: */
1087: public void enableTextBuffer(boolean enabled)
1088: throws EngineException {
1089: if (!mRequestAccessEnabled)
1090: throw new RequestAccessDeniedException();
1091: if (null == mElementContext)
1092: throw new ElementContextMissingException();
1093:
1094: mElementContext.getResponse().enableTextBuffer(enabled);
1095: }
1096:
1097: /**
1098: * Indicates whether the response text buffer is enabled or disabled.
1099: *
1100: * @return <code>true</code> if the text buffer is enabled; or
1101: * <p><code>false</code> if it is disabled
1102: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
1103: * have access to the request data (eg. you're inside a child trigger); or
1104: * if there's no active element context (eg. you're using this method
1105: * inside the constructor instead of inside the {@link #initialize()}
1106: * method)
1107: * @see #enableTextBuffer(boolean)
1108: * @see #flush()
1109: * @see #clearBuffer()
1110: * @since 1.0
1111: */
1112: public boolean isTextBufferEnabled() throws EngineException {
1113: if (!mRequestAccessEnabled)
1114: throw new RequestAccessDeniedException();
1115: if (null == mElementContext)
1116: throw new ElementContextMissingException();
1117:
1118: return mElementContext.getResponse().isTextBufferEnabled();
1119: }
1120:
1121: /**
1122: * Prints the content of a template to the request text output. The
1123: * template is first processed in the active element context by the {@link
1124: * #processTemplate(Template)} method.
1125: *
1126: * @param template the template that will be printed
1127: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
1128: * error occurs during the retrieval of the template content
1129: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
1130: * occurs during the output of the template content; or if you don't have
1131: * access to the request data (eg. you're inside a child trigger); or if
1132: * there's no active element context (eg. you're using this method inside
1133: * the constructor instead of inside the {@link #initialize()} method)
1134: * @see #print(Object)
1135: * @see #processTemplate(Template)
1136: * @since 1.0
1137: */
1138: public void print(Template template) throws TemplateException,
1139: EngineException {
1140: if (!mRequestAccessEnabled)
1141: throw new RequestAccessDeniedException();
1142: if (null == mElementContext)
1143: throw new ElementContextMissingException();
1144:
1145: if (null == template)
1146: throw new IllegalArgumentException(
1147: "template can't be null.");
1148:
1149: mElementContext.print(template);
1150: }
1151:
1152: /**
1153: * Processes a template in the active element context.
1154: * <p>This performs the following value replacements if they haven't
1155: * already been set.
1156: * <p>Each template type can have a value encoder attached to it (for
1157: * instance a HTML encoder to replace non-ascii characters with the
1158: * appropriate entities). All variable content that is handled in this
1159: * method will be encoded before being set in the template.
1160: * <table border="0">
1161: * <tr>
1162: * <td><code>OGNL:ROLEUSER:valueid<br><code>GROOVY:ROLEUSER:valueid<br></code><code>JANINO:ROLEUSER:valueid<br></code></code>
1163: * <td>These scripted block value tags will be processed according to the
1164: * active element context.
1165: * <p>For example: <code><!--V 'OGNL:ROLEUSER:rolecheck'-->User is
1166: * no admin<!--/V--><br><!--B 'OGNL:ROLEUSER:rolecheck:[[
1167: * isInRole("admin") ]]'-->User is admin<!--/B--></code>
1168: * <p>Will display '<code>User is admin</code>' if the user has the admin
1169: * role, and otherwise '<code>User is no admin</code>'.
1170: * <tr>
1171: * <td><code>EXIT:QUERY:exitname</code>
1172: * <td>Will be replaced with the URL that links to the target of the named
1173: * exit. The state will be carried around according to the currently set
1174: * outputs.
1175: * <tr>
1176: * <td><code>EXIT:FORM:exitname</code>
1177: * <td>Will be replaced with the URL that links to the target of the named
1178: * exit. No state information will be added to the URL. The
1179: * <code>EXIT:PARAMS</code> value tag should be put at the location where
1180: * hidden form parameters are allowed.
1181: * <tr>
1182: * <td><code>EXIT:PARAMS:exitname</code>
1183: * <td>Will be replaced by the hidden form parameters that are need to
1184: * carry the state around according to the currently set outputs. This tag
1185: * goes hand-in-hand with the <code>EXIT:FORM</code> tag.
1186: * <tr>
1187: * <td><code>SUBMISSION:QUERY:submissionname</code>
1188: * <td>Will be replaced with the URL that sends the named submission to
1189: * currently the active element. The state will be carried around
1190: * according to the currently set inputs.
1191: * <tr>
1192: * <td><code>SUBMISSION:FORM:submissionname</code>
1193: * <td>Will be replaced with the URL that sends the named submission to
1194: * currently the active element. No state information will be added to the
1195: * URL. The <code>SUBMISSION:PARAMS</code> value tag should be put at the
1196: * location where hidden form parameters are allowed.
1197: * <tr>
1198: * <td><code>SUBMISSION:PARAMS:submissionname</code>
1199: * <td>Will be replaced by the hidden form parameters that are need to
1200: * carry the state around according to the currently set inputs. This tag
1201: * goes hand-in-hand with the <code>SUBMISSION:FORM</code> tag.
1202: * <tr>
1203: * <td><code>PARAM:name</code>
1204: * <td>Will be replaced with the encoded content of the named submission
1205: * parameter.
1206: * <tr>
1207: * <td><code>INPUT:name</code>
1208: * <td>Will be replaced with the encoded content of the named input.
1209: * <tr>
1210: * <td><code>OUTPUT:name</code>
1211: * <td>Will be replaced with the encoded content of the named output.
1212: * <tr>
1213: * <td><code>INCOOKIE:name</code>
1214: * <td>Will be replaced with the encoded content of the named incookie.
1215: * <tr>
1216: * <td><code>OUTCOOKIE:nam</code>
1217: * <td>Will be replaced with the encoded content of the named outcookie.
1218: * <tr>
1219: * <td><code>WEBAPP:ROOTURL</code>
1220: * <td>Will be replaced with the absolute root URL of the web application.
1221: * This is typically used in a <base href=""> tag. All URLs can then
1222: * be relative according to this root URL and the application can be used
1223: * anywhere and with any web application name.
1224: * <tr>
1225: * <td>automated form building for submission beans
1226: * <td>see {@link com.uwyn.rife.site.FormBuilder}
1227: * </table>
1228: *
1229: * @param template the template instance that needs to be processed
1230: * @exception com.uwyn.rife.template.exceptions.TemplateException if an
1231: * error occurs during the manipulation of the template
1232: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
1233: * occurs during the retrieval of the values from the current element
1234: * context, or during the output of the template content; or if you don't
1235: * have access to the request data (eg. you're inside a child trigger); or
1236: * if there's no active element context (eg. you're using this method
1237: * inside the constructor instead of inside the {@link #initialize()}
1238: * method)
1239: * @return a list with the ids of all the template values that have been
1240: * set
1241: * @since 1.0
1242: */
1243: public List<String> processTemplate(Template template)
1244: throws TemplateException, EngineException {
1245: if (!mRequestAccessEnabled)
1246: throw new RequestAccessDeniedException();
1247: if (null == mElementContext)
1248: throw new ElementContextMissingException();
1249:
1250: if (null == template)
1251: throw new IllegalArgumentException(
1252: "template can't be null.");
1253:
1254: return mElementContext.processTemplate(template);
1255: }
1256:
1257: /**
1258: * Prints the string representation of an object to the request text
1259: * output. The string representation will be created through a
1260: * <code>String.valueOf(value)</code> call.
1261: *
1262: * @param value the object that will be output
1263: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
1264: * occurs during the output of the content; or if you don't have access to
1265: * the request data (eg. you're inside a child trigger); or if there's no
1266: * active element context (eg. you're using this method inside the
1267: * constructor instead of inside the {@link #initialize()} method)
1268: * @since 1.0
1269: */
1270: public void print(Object value) throws EngineException {
1271: if (!mRequestAccessEnabled)
1272: throw new RequestAccessDeniedException();
1273: if (null == mElementContext)
1274: throw new ElementContextMissingException();
1275:
1276: mElementContext.getResponse().print(value);
1277: }
1278:
1279: /**
1280: * Retrieves an output stream to send binary data through the response.
1281: * <p>Note that the text output is written to the same output stream. Of
1282: * course, when the text buffer is active this only happen at the end of
1283: * the request.
1284: *
1285: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
1286: * occurs during the creation of the output stream; or if you don't have
1287: * access to the request data (eg. you're inside a child trigger); or if
1288: * there's no active element context (eg. you're using this method inside
1289: * the constructor instead of inside the {@link #initialize()} method)
1290: * @return an instance of the response output stream
1291: * @since 1.0
1292: */
1293: public OutputStream getOutputStream() throws EngineException {
1294: if (!mRequestAccessEnabled)
1295: throw new RequestAccessDeniedException();
1296: if (null == mElementContext)
1297: throw new ElementContextMissingException();
1298:
1299: return mElementContext.getResponse().getOutputStream();
1300: }
1301:
1302: /**
1303: * Clears the request text output buffer, all buffered text will be
1304: * discarded.
1305: * <p>If no text buffer is active, this method doesn't do anything.
1306: *
1307: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
1308: * have access to the request data (eg. you're inside a child trigger); or
1309: * if there's no active element context (eg. you're using this method
1310: * inside the constructor instead of inside the {@link #initialize()}
1311: * method)
1312: * @see #isTextBufferEnabled()
1313: * @see #enableTextBuffer(boolean)
1314: * @see #flush()
1315: * @since 1.0
1316: */
1317: public void clearBuffer() throws EngineException {
1318: if (!mRequestAccessEnabled)
1319: throw new RequestAccessDeniedException();
1320: if (null == mElementContext)
1321: throw new ElementContextMissingException();
1322:
1323: mElementContext.getResponse().clearBuffer();
1324: }
1325:
1326: /**
1327: * Flushes the request text output buffer and the request output stream.
1328: * This sends any buffered data immediately to the client.
1329: * <p>All text in the active buffer will be sent to the client and the
1330: * buffer will be empty again, if no text buffer is enabled only the
1331: * output stream will be flushed.
1332: *
1333: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
1334: * occurs during the output of the content; or if you don't have access to
1335: * the request data (eg. you're inside a child trigger); or if there's no
1336: * active element context (eg. you're using this method inside the
1337: * constructor instead of inside the {@link #initialize()} method)
1338: * @see #isTextBufferEnabled()
1339: * @see #enableTextBuffer(boolean)
1340: * @see #clearBuffer()
1341: * @since 1.0
1342: */
1343: public void flush() throws EngineException {
1344: if (!mRequestAccessEnabled)
1345: throw new RequestAccessDeniedException();
1346: if (null == mElementContext)
1347: throw new ElementContextMissingException();
1348:
1349: mElementContext.getResponse().flush();
1350: }
1351:
1352: /**
1353: * Retrieves the site in which this element is declared.
1354: *
1355: * @return a site instance
1356: * @exception com.uwyn.rife.engine.exceptions.EngineException if the
1357: * element information hasn't been provided yet (eg. you're using this
1358: * method inside the constructor instead of inside the {@link
1359: * #initialize()} method)
1360: * @since 1.0
1361: */
1362: public Site getSite() throws EngineException {
1363: if (null == mElementInfo)
1364: throw new ElementInfoMissingException();
1365:
1366: return mElementInfo.getSite();
1367: }
1368:
1369: /**
1370: * Retrieves the deployer of this element.
1371: *
1372: * @return the instance of the deployer that was used to deploy the
1373: * element; or
1374: * <p><code>null</code> if no deployment class has been declared
1375: * @exception com.uwyn.rife.engine.exceptions.EngineException if the
1376: * element information hasn't been provided yet (eg. you're using this
1377: * method inside the constructor instead of inside the {@link
1378: * #initialize()} method)
1379: * @see #getDeploymentClass()
1380: * @see #setDeploymentClass(Class)
1381: * @since 1.0
1382: */
1383: public ElementDeployer getDeployer() throws EngineException {
1384: if (null == mElementInfo)
1385: throw new ElementInfoMissingException();
1386:
1387: return mElementInfo.getDeployer();
1388: }
1389:
1390: /**
1391: * Retrieves the declaration information of this element.
1392: *
1393: * @return the declaration information of this element
1394: * @exception com.uwyn.rife.engine.exceptions.EngineException if the
1395: * element information hasn't been provided yet (eg. you're using this
1396: * method inside the constructor instead of inside the {@link
1397: * #initialize()} method)
1398: * @since 1.0
1399: */
1400: public ElementInfo getElementInfo() throws EngineException {
1401: if (null == mElementInfo)
1402: throw new ElementInfoMissingException();
1403: return _getElementInfo();
1404: }
1405:
1406: ElementInfo _getElementInfo() throws EngineException {
1407: return mElementInfo;
1408: }
1409:
1410: /**
1411: * Retrieves the source implementation name of this element.
1412: *
1413: * @return the source implementation name
1414: * @exception com.uwyn.rife.engine.exceptions.EngineException if the
1415: * element information hasn't been provided yet (eg. you're using this
1416: * method inside the constructor instead of inside the {@link
1417: * #initialize()} method)
1418: * @since 1.0
1419: */
1420: public String getSourceName() throws EngineException {
1421: if (null == mElementInfo)
1422: throw new ElementInfoMissingException();
1423:
1424: return mElementInfo.getImplementation();
1425: }
1426:
1427: /**
1428: * Retrieves the declaration name of this element.
1429: *
1430: * @return the declaration name
1431: * @exception com.uwyn.rife.engine.exceptions.EngineException if the
1432: * element information hasn't been provided yet (eg. you're using this
1433: * method inside the constructor instead of inside the {@link
1434: * #initialize()} method)
1435: * @since 1.0
1436: */
1437: public String getDeclarationName() throws EngineException {
1438: if (null == mElementInfo)
1439: throw new ElementInfoMissingException();
1440:
1441: return mElementInfo.getDeclarationName();
1442: }
1443:
1444: /**
1445: * Retrieves the information of the target element of the active request.
1446: * <p>This can be different from the current element due to precedence,
1447: * behavioural inheritance, child triggers, element embedding, ...
1448: *
1449: * @return the request's target element information
1450: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
1451: * no active element context (eg. you're using this method inside the
1452: * constructor instead of inside the {@link #initialize()} method)
1453: * @since 1.0
1454: */
1455: public ElementInfo getTarget() throws EngineException {
1456: if (null == mElementContext)
1457: throw new ElementContextMissingException();
1458:
1459: return mElementContext.getRequestState().getTarget();
1460: }
1461:
1462: /**
1463: * Retrieves the element that is embedding the current element.
1464: *
1465: * @return the embedding element; or
1466: * <p><code>null</code> if this element is not embedded
1467: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
1468: * no active element context (eg. you're using this method inside the
1469: * constructor instead of inside the {@link #initialize()} method)
1470: * @see #getEmbeddingTemplate()
1471: * @see #getEmbedDifferentiator()
1472: * @see #hasEmbedValue()
1473: * @see #getEmbedValue()
1474: * @see #hasEmbedData()
1475: * @see #getEmbedData()
1476: * @see #getEmbedProperties()
1477: * @see #isEmbedded()
1478: * @since 1.0
1479: */
1480: public ElementSupport getEmbeddingElement() throws EngineException {
1481: if (null == mElementContext)
1482: throw new ElementContextMissingException();
1483:
1484: EmbeddingContext embedding_context = mElementContext
1485: .getRequestState().getEmbeddingContext();
1486: if (null == embedding_context) {
1487: return null;
1488: }
1489:
1490: return embedding_context.getEmbeddingElement();
1491: }
1492:
1493: /**
1494: * Retrieves the template that is embedding the current element.
1495: *
1496: * @return the embedding template; or
1497: * <p><code>null</code> if this element is not embedded
1498: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
1499: * no active element context (eg. you're using this method inside the
1500: * constructor instead of inside the {@link #initialize()} method)
1501: * @see #getEmbeddingElement()
1502: * @see #getEmbedDifferentiator()
1503: * @see #hasEmbedValue()
1504: * @see #getEmbedValue()
1505: * @see #hasEmbedData()
1506: * @see #getEmbedData()
1507: * @see #getEmbedProperties()
1508: * @see #isEmbedded()
1509: * @since 1.0
1510: */
1511: public Template getEmbeddingTemplate() throws EngineException {
1512: if (null == mElementContext)
1513: throw new ElementContextMissingException();
1514:
1515: EmbeddingContext embedding_context = mElementContext
1516: .getRequestState().getEmbeddingContext();
1517: if (null == embedding_context) {
1518: return null;
1519: }
1520:
1521: return embedding_context.getTemplate();
1522: }
1523:
1524: /**
1525: * Retrieves the differentiator that was used to set this embedded element apart.
1526: *
1527: * @return this embedded element's differentiator; or
1528: * <p><code>null</code> if this embedded element didn't have a differentiator
1529: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
1530: * no active element context (eg. you're using this method inside the
1531: * constructor instead of inside the {@link #initialize()} method)
1532: * @see #getEmbeddingTemplate()
1533: * @see #getEmbeddingElement()
1534: * @see #hasEmbedValue()
1535: * @see #getEmbedValue()
1536: * @see #hasEmbedData()
1537: * @see #getEmbedData()
1538: * @see #getEmbedProperties()
1539: * @see #isEmbedded()
1540: * @since 1.0
1541: */
1542: public String getEmbedDifferentiator() throws EngineException {
1543: if (null == mElementContext)
1544: throw new ElementContextMissingException();
1545:
1546: return mElementContext.getRequestState()
1547: .getEmbedDifferentiator();
1548: }
1549:
1550: /**
1551: * Indicates whether the embedded element's template value has content.
1552: *
1553: * @return <code>true</code> if the value has content; or
1554: * <p><code>false</code> otherwise
1555: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
1556: * no active element context (eg. you're using this method inside the
1557: * constructor instead of inside the {@link #initialize()} method)
1558: * @see #getEmbeddingTemplate()
1559: * @see #getEmbeddingElement()
1560: * @see #getEmbedDifferentiator()
1561: * @see #getEmbedValue()
1562: * @see #hasEmbedData()
1563: * @see #getEmbedData()
1564: * @see #getEmbedProperties()
1565: * @see #isEmbedded()
1566: * @since 1.0
1567: */
1568: public boolean hasEmbedValue() throws EngineException {
1569: if (null == mElementContext)
1570: throw new ElementContextMissingException();
1571:
1572: return mElementContext.getRequestState().getEmbedValue() != null;
1573: }
1574:
1575: /**
1576: * Retrieves the current content of the value tag of this embedded element.
1577: * <p>For example:
1578: * <pre><!--V 'ELEMENT:my.element'-->this is the embed value<!--/V--></pre>
1579: * <p>Will return:
1580: * <pre>this is the embed value</pre>
1581: * <p>Note that when you have several embedded elements in the same
1582: * template with the same element id, you have to use embedded element
1583: * differentiators if you want to provide different embed values. For
1584: * example:
1585: * <pre><!--V 'ELEMENT:my.element:differentiator1'-->this is the first embed value<!--/V-->
1586: *<!--V 'ELEMENT:my.element:differentiator2'-->this is the second embed value<!--/V--></pre>
1587: *
1588: * @return the value from the embedded template; or
1589: * <p>null if no default value was provided or if the current element is
1590: * not embedded
1591: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
1592: * no active element context (eg. you're using this method inside the
1593: * constructor instead of inside the {@link #initialize()} method)
1594: * @see #getEmbeddingTemplate()
1595: * @see #getEmbeddingElement()
1596: * @see #getEmbedDifferentiator()
1597: * @see #hasEmbedValue()
1598: * @see #getEmbedData()
1599: * @see #hasEmbedData()
1600: * @see #getEmbedProperties()
1601: * @see #isEmbedded()
1602: * @since 1.0
1603: */
1604: public String getEmbedValue() throws EngineException {
1605: if (null == mElementContext)
1606: throw new ElementContextMissingException();
1607:
1608: return mElementContext.getRequestState().getEmbedValue();
1609: }
1610:
1611: /**
1612: * Indicates whether data was passed on during the processing of this embedded element.
1613: *
1614: * @return <code>true</code> if data was passed on; or
1615: * <p><code>false</code> otherwise
1616: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
1617: * no active element context (eg. you're using this method inside the
1618: * constructor instead of inside the {@link #initialize()} method)
1619: * @see #getEmbeddingTemplate()
1620: * @see #getEmbeddingElement()
1621: * @see #getEmbedDifferentiator()
1622: * @see #hasEmbedValue()
1623: * @see #getEmbedValue()
1624: * @see #getEmbedData()
1625: * @see #getEmbedProperties()
1626: * @see #isEmbedded()
1627: * @since 1.0
1628: */
1629: public boolean hasEmbedData() throws EngineException {
1630: if (null == mElementContext)
1631: throw new ElementContextMissingException();
1632:
1633: return mElementContext.getRequestState().getEmbedValue() != null;
1634: }
1635:
1636: /**
1637: * Retrieves the data that was passed on for the processing of this embedded element.
1638: * @return the value from the embedded template; or
1639: * <p>null if no data was provided or if the current element is
1640: * not embedded
1641: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
1642: * no active element context (eg. you're using this method inside the
1643: * constructor instead of inside the {@link #initialize()} method)
1644: * @see #getEmbeddingTemplate()
1645: * @see #getEmbeddingElement()
1646: * @see #getEmbedDifferentiator()
1647: * @see #getEmbedValue()
1648: * @see #hasEmbedValue()
1649: * @see #hasEmbedData()
1650: * @see #getEmbedProperties()
1651: * @see #isEmbedded()
1652: * @since 1.5
1653: */
1654: public Object getEmbedData() throws EngineException {
1655: if (null == mElementContext)
1656: throw new ElementContextMissingException();
1657:
1658: return mElementContext.getRequestState().getEmbedData();
1659: }
1660:
1661: /**
1662: * Retrieves the embed value as a property list (see {@link
1663: * #getEmbedValue()} for more information about embed values).
1664: * <p>The content of the embed value will be parsed as a property list
1665: * according to the format described in {@link
1666: * java.util.Properties#load(java.io.InputStream)}.
1667: * <p>For instance:
1668: * <pre><!--V 'ELEMENT:my.element'-->
1669: *key1 = value1
1670: *key2 = value1
1671: *<!--/V--></pre>
1672: * <p>Will return a property list where the key '<code>key1</code>' is
1673: * associated to '<code>value1</code>' and '<code>key2</code>' to '<code>value2</code>'.
1674: *
1675: * @return the embed value parsed as a property list; or
1676: * <p>null if no default value was provided, if the current element is not
1677: * embedded
1678: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
1679: * no active element context (eg. you're using this method inside the
1680: * constructor instead of inside the {@link #initialize()} method)
1681: * @see #getEmbeddingTemplate()
1682: * @see #getEmbeddingElement()
1683: * @see #getEmbedDifferentiator()
1684: * @see #hasEmbedValue()
1685: * @see #getEmbedValue()
1686: * @see #hasEmbedData()
1687: * @see #isEmbedded()
1688: * @since 1.0
1689: */
1690: public Properties getEmbedProperties() throws EngineException {
1691: if (null == mElementContext)
1692: throw new ElementContextMissingException();
1693:
1694: return mElementContext.getRequestState().getEmbedProperties();
1695: }
1696:
1697: /**
1698: * Indicates whether this element is running embedded inside another
1699: * element's template.
1700: *
1701: * @return <code>true</code> if this element is embedded; or
1702: * <p><code>false</code> otherwise
1703: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
1704: * no active element context (eg. you're using this method inside the
1705: * constructor instead of inside the {@link #initialize()} method)
1706: * @see #getEmbeddingTemplate()
1707: * @see #getEmbeddingElement()
1708: * @see #getEmbedDifferentiator()
1709: * @see #hasEmbedValue()
1710: * @see #getEmbedValue()
1711: * @see #hasEmbedData()
1712: * @see #getEmbedProperties()
1713: * @since 1.4
1714: */
1715: public boolean isEmbedded() throws EngineException {
1716: if (null == mElementContext)
1717: throw new ElementContextMissingException();
1718:
1719: return mElementContext.getRequestState().isEmbedded();
1720: }
1721:
1722: /**
1723: * Indicates whether this element has a certain injected named property.
1724: *
1725: * @param name the name of the property
1726: * @exception com.uwyn.rife.engine.exceptions.EngineException if the
1727: * element information hasn't been provided yet (eg. you're using this
1728: * method inside the constructor instead of inside the {@link
1729: * #initialize()} method)
1730: * @return <code>true</code> if the element contains the property; or
1731: * <p><code>false</code> otherwise
1732: * @see #getProperty(String)
1733: * @see #getProperty(String, Object)
1734: * @see #getPropertyTyped(String, Class)
1735: * @see #getPropertyTyped(String, Class, Object)
1736: * @see #getPropertyString(String)
1737: * @see #getPropertyString(String, String)
1738: * @see #isPropertyEmpty(String)
1739: * @since 1.0
1740: */
1741: public boolean hasProperty(String name) throws EngineException {
1742: if (null == mElementInfo)
1743: throw new ElementInfoMissingException();
1744:
1745: return mElementInfo.containsProperty(name);
1746: }
1747:
1748: /**
1749: * Retrieves the value of an injected named property.
1750: * <p>Note that there are two types of properties, fixed value properties
1751: * ({@link com.uwyn.rife.ioc.PropertyValueObject string literals}) and dynamic value
1752: * properties ({@link com.uwyn.rife.ioc.PropertyValueParticipant participant objects},
1753: * {@link com.uwyn.rife.ioc.PropertyValueTemplate template instances}, ...). The fixed value
1754: * is set during the declaration of the property and the dynamic value is
1755: * retrieved or instantiated each time the property value is obtained.
1756: * <p>Property values can be of any type and class. If the resulting value
1757: * needs to be a certain standard type or primitive value, use the {@link
1758: * com.uwyn.rife.tools.Convert} helper class to perform the conversion
1759: * in-line. Since properties are very often used as string literals,
1760: * there's {@link #getPropertyString(String)} method to make this more
1761: * convenient.
1762: *
1763: * @param name the name of the property
1764: * @exception com.uwyn.rife.engine.exceptions.EngineException if the
1765: * element information hasn't been provided yet (eg. you're using this
1766: * method inside the constructor instead of inside the {@link
1767: * #initialize()} method)
1768: * @return the property value; or
1769: * <p><code>null</code> if no such property exists
1770: * @see #hasProperty(String)
1771: * @see #getProperty(String, Object)
1772: * @see #getPropertyTyped(String, Class)
1773: * @see #getPropertyTyped(String, Class, Object)
1774: * @see #getPropertyString(String)
1775: * @see #getPropertyString(String, String)
1776: * @see #isPropertyEmpty(String)
1777: * @since 1.0
1778: */
1779: public Object getProperty(String name) throws EngineException {
1780: if (null == mElementInfo)
1781: throw new ElementInfoMissingException();
1782:
1783: return mElementInfo.getProperty(name);
1784: }
1785:
1786: /**
1787: * Retrieves the value of an injected named property, using a default value
1788: * as fallback.
1789: *
1790: * @param name the name of the property
1791: * @param defaultValue the value that should be used if the
1792: * property can't be found
1793: * @exception com.uwyn.rife.engine.exceptions.EngineException if the
1794: * element information hasn't been provided yet (eg. you're using this
1795: * method inside the constructor instead of inside the {@link
1796: * #initialize()} method)
1797: * @return the property value; or
1798: * <p>the default value if no such property exists
1799: * @see #hasProperty(String)
1800: * @see #getProperty(String)
1801: * @see #getPropertyTyped(String, Class)
1802: * @see #getPropertyTyped(String, Class, Object)
1803: * @see #getPropertyString(String)
1804: * @see #getPropertyString(String, String)
1805: * @see #isPropertyEmpty(String)
1806: * @since 1.0
1807: */
1808: public Object getProperty(String name, Object defaultValue)
1809: throws EngineException {
1810: if (null == mElementInfo)
1811: throw new ElementInfoMissingException();
1812:
1813: return mElementInfo.getProperty(name, defaultValue);
1814: }
1815:
1816: /**
1817: * Retrieves the value of an injected named property and converts it to the
1818: * specified type.
1819: * <p>This method has advantages over a regular cast, since it throws a
1820: * meaningful exception to the user in case the type of the property value
1821: * is not compatible.
1822: *
1823: * @param name the name of the property
1824: * @param type the class you want the property to be converted to
1825: * @exception com.uwyn.rife.engine.exceptions.EngineException if the
1826: * element information hasn't been provided yet (eg. you're using this
1827: * method inside the constructor instead of inside the {@link
1828: * #initialize()} method)
1829: * @exception com.uwyn.rife.engine.exceptions.PropertyIncompatibleTypeException
1830: * if the type of the property value wasn't compatible with the requested type
1831: * @return the property value, casted to the requested type; or
1832: * <p><code>null</code> if no such property exists
1833: * @see #hasProperty(String)
1834: * @see #getProperty(String)
1835: * @see #getProperty(String, Object)
1836: * @see #getPropertyTyped(String, Class, Object)
1837: * @see #getPropertyString(String)
1838: * @see #getPropertyString(String, String)
1839: * @see #isPropertyEmpty(String)
1840: * @since 1.3
1841: */
1842: public <T> T getPropertyTyped(String name, Class<T> type) {
1843: if (null == mElementInfo)
1844: throw new ElementInfoMissingException();
1845:
1846: return (T) mElementInfo.getPropertyTyped(name, type);
1847: }
1848:
1849: /**
1850: * Retrieves the value of an injected named property and converts it to the
1851: * specified type, using a default value as fallback.
1852: * <p>This method has advantages over a regular cast, since it throws a
1853: * meaningful exception to the user in case the type of the property value
1854: * is not compatible.
1855: *
1856: * @param name the name of the property
1857: * @param type the class you want the property to be converted to
1858: * @param defaultValue the object that should be used if the
1859: * property can't be found
1860: * @exception com.uwyn.rife.engine.exceptions.EngineException if the
1861: * element information hasn't been provided yet (eg. you're using this
1862: * method inside the constructor instead of inside the {@link
1863: * #initialize()} method)
1864: * @exception com.uwyn.rife.engine.exceptions.PropertyIncompatibleTypeException
1865: * if the type of the property value wasn't compatible with the requested type
1866: * @return the property value, casted to the requested type; or
1867: * <p>the default value if no such property exists
1868: * @see #hasProperty(String)
1869: * @see #getProperty(String)
1870: * @see #getProperty(String, Object)
1871: * @see #getPropertyTyped(String, Class)
1872: * @see #getPropertyString(String)
1873: * @see #getPropertyString(String, String)
1874: * @see #isPropertyEmpty(String)
1875: * @since 1.3
1876: */
1877: public <T> T getPropertyTyped(String name, Class<T> type,
1878: T defaultValue) {
1879: if (null == mElementInfo)
1880: throw new ElementInfoMissingException();
1881:
1882: return (T) mElementInfo.getPropertyTyped(name, type,
1883: defaultValue);
1884: }
1885:
1886: /**
1887: * Retrieves the value of an injected named property and converts it to a
1888: * string.
1889: *
1890: * @param name the name of the property
1891: * @exception com.uwyn.rife.engine.exceptions.EngineException if the
1892: * element information hasn't been provided yet (eg. you're using this
1893: * method inside the constructor instead of inside the {@link
1894: * #initialize()} method)
1895: * @return the string representation of the property value; or
1896: * <p><code>null</code> if no such property exists
1897: * @see #hasProperty(String)
1898: * @see #getProperty(String)
1899: * @see #getProperty(String, Object)
1900: * @see #getPropertyTyped(String, Class)
1901: * @see #getPropertyTyped(String, Class, Object)
1902: * @see #getPropertyString(String, String)
1903: * @see #isPropertyEmpty(String)
1904: * @since 1.0
1905: */
1906: public String getPropertyString(String name) throws EngineException {
1907: if (null == mElementInfo)
1908: throw new ElementInfoMissingException();
1909:
1910: return mElementInfo.getPropertyString(name);
1911: }
1912:
1913: /**
1914: * Retrieves the value of an injected named property and converts it to a
1915: * string, using a default value as fallback.
1916: *
1917: * @param name the name of the property
1918: * @param defaultValue the string literal that should be used if the
1919: * property can't be found
1920: * @exception com.uwyn.rife.engine.exceptions.EngineException if the
1921: * element information hasn't been provided yet (eg. you're using this
1922: * method inside the constructor instead of inside the {@link
1923: * #initialize()} method)
1924: * @return the string representation of the property value; or
1925: * <p>the default value if no such property exists or when the resulting
1926: * string is empty
1927: * @see #hasProperty(String)
1928: * @see #getProperty(String)
1929: * @see #getProperty(String, Object)
1930: * @see #getPropertyTyped(String, Class)
1931: * @see #getPropertyTyped(String, Class, Object)
1932: * @see #getPropertyString(String)
1933: * @see #isPropertyEmpty(String)
1934: * @since 1.0
1935: */
1936: public String getPropertyString(String name, String defaultValue)
1937: throws EngineException {
1938: if (null == mElementInfo)
1939: throw new ElementInfoMissingException();
1940:
1941: return mElementInfo.getPropertyString(name, defaultValue);
1942: }
1943:
1944: /**
1945: * Checks if a property is not available or if the string presentation is
1946: * empty.
1947: *
1948: * @param name the name of the property
1949: * @exception com.uwyn.rife.engine.exceptions.EngineException if the
1950: * element information hasn't been provided yet (eg. you're using this
1951: * method inside the constructor instead of inside the {@link
1952: * #initialize()} method)
1953: * @return <code>true</code> if the property is empty; or
1954: * <p><code>false</code> otherwise
1955: * @see #hasProperty(String)
1956: * @see #getProperty(String)
1957: * @see #getProperty(String, Object)
1958: * @see #getPropertyTyped(String, Class)
1959: * @see #getPropertyTyped(String, Class, Object)
1960: * @see #getPropertyString(String)
1961: * @see #getPropertyString(String, String)
1962: * @since 1.0
1963: */
1964: public boolean isPropertyEmpty(String name) throws EngineException {
1965: if (null == mElementInfo)
1966: throw new ElementInfoMissingException();
1967:
1968: return mElementInfo.isPropertyEmpty(name);
1969: }
1970:
1971: /**
1972: * Retrieves an instance of a named input bean and populates the
1973: * properties with the input values. The class of the bean is looked up
1974: * through its name, as is the property prefix.
1975: * <p>This bean is not serialized or deserialized, each property
1976: * corresponds to an input and is individually sent by the client.
1977: *
1978: * @param name the name of the input bean
1979: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
1980: * bean is known with this name; or if an error occurred during the
1981: * instantiation of the bean; or if you don't have access to the request
1982: * data (eg. you're inside a child trigger); or if there's no active
1983: * element context (eg. you're using this method inside the constructor
1984: * instead of inside the {@link #initialize()} method)
1985: * @return the populated input bean instance
1986: * @see #hasInputValue(String)
1987: * @see #isInputEmpty(String)
1988: * @see #getInputBean(Class)
1989: * @see #getInputBean(Class, String)
1990: * @see #getInput(String)
1991: * @see #getInput(String, String)
1992: * @see #getInputValues(String)
1993: * @since 1.0
1994: */
1995: public <BeanType> BeanType getNamedInputBean(String name)
1996: throws EngineException {
1997: if (!mRequestAccessEnabled)
1998: throw new RequestAccessDeniedException();
1999: if (null == mElementContext)
2000: throw new ElementContextMissingException();
2001:
2002: if (null == name)
2003: throw new IllegalArgumentException("name can't be null.");
2004: if (0 == name.length())
2005: throw new IllegalArgumentException("name can't be empty.");
2006:
2007: return (BeanType) mElementContext.getNamedInputBean(name);
2008: }
2009:
2010: /**
2011: * Retrieves an instance of an input bean and populates the properties
2012: * with the input values.
2013: * <p>This bean is not serialized or de-serialized, each property
2014: * corresponds to an input and is individually sent by the client.
2015: *
2016: * @param beanClass the class of the input bean
2017: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
2018: * occurred during the instantiation of the bean; or if you don't have
2019: * access to the request data (eg. you're inside a child trigger); or if
2020: * there's no active element context (eg. you're using this method inside
2021: * the constructor instead of inside the {@link #initialize()} method)
2022: * @return the populated input bean instance
2023: * @see #hasInputValue(String)
2024: * @see #isInputEmpty(String)
2025: * @see #getNamedInputBean(String)
2026: * @see #getInputBean(Class, String)
2027: * @see #getInput(String)
2028: * @see #getInput(String, String)
2029: * @see #getInputValues(String)
2030: * @since 1.0
2031: */
2032: public <BeanType> BeanType getInputBean(Class<BeanType> beanClass)
2033: throws EngineException {
2034: return getInputBean(beanClass, null);
2035: }
2036:
2037: /**
2038: * Retrieves an instance of an input bean and populates the properties
2039: * with the input values, taking the provided prefix into account.
2040: * <p>This bean is not serialized or de-serialized, each property
2041: * corresponds to an input and is individually sent by the client.
2042: *
2043: * @param beanClass the class of the input bean
2044: * @param prefix the prefix that will be put in front of each property
2045: * name
2046: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
2047: * occurred during the instantiation of the bean; or if you don't have
2048: * access to the request data (eg. you're inside a child trigger); or if
2049: * there's no active element context (eg. you're using this method inside
2050: * the constructor instead of inside the {@link #initialize()} method)
2051: * @return the populated input bean instance
2052: * @see #hasInputValue(String)
2053: * @see #isInputEmpty(String)
2054: * @see #getNamedInputBean(String)
2055: * @see #getInputBean(Class)
2056: * @see #getInput(String)
2057: * @see #getInput(String, String)
2058: * @see #getInputValues(String)
2059: * @since 1.0
2060: */
2061: public <BeanType> BeanType getInputBean(Class<BeanType> beanClass,
2062: String prefix) throws EngineException {
2063: if (!mRequestAccessEnabled)
2064: throw new RequestAccessDeniedException();
2065: if (null == mElementContext)
2066: throw new ElementContextMissingException();
2067:
2068: if (null == beanClass)
2069: throw new IllegalArgumentException(
2070: "beanClass can't be null.");
2071:
2072: return mElementContext.getInputBean(beanClass, prefix);
2073: }
2074:
2075: /**
2076: * Checks whether a value has been provided to an input.
2077: *
2078: * @param name the name of the input
2079: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2080: * is known with this name; or if you don't have access to the request
2081: * data (eg. you're inside a child trigger); or if there's no active
2082: * element context (eg. you're using this method inside the constructor
2083: * instead of inside the {@link #initialize()} method)
2084: * @return <code>true</code> if the input has a value; or
2085: * <p><code>false</code> otherwise
2086: * @see #isInputEmpty(String)
2087: * @see #getNamedInputBean(String)
2088: * @see #getInputBean(Class, String)
2089: * @see #getInput(String)
2090: * @see #getInput(String, String)
2091: * @see #getInputValues(String)
2092: * @since 1.0
2093: */
2094: public boolean hasInputValue(String name) throws EngineException {
2095: if (!mRequestAccessEnabled)
2096: throw new RequestAccessDeniedException();
2097: if (null == mElementContext)
2098: throw new ElementContextMissingException();
2099:
2100: if (null == name)
2101: throw new IllegalArgumentException("name can't be null.");
2102: if (0 == name.length())
2103: throw new IllegalArgumentException("name can't be empty.");
2104:
2105: return mElementContext.hasInputValue(name);
2106: }
2107:
2108: /**
2109: * Checks whether an input has no value or whether the value is empty.
2110: *
2111: * @param name the name of the input
2112: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2113: * is known with this name; or if you don't have access to the request
2114: * data (eg. you're inside a child trigger); or if there's no active
2115: * element context (eg. you're using this method inside the constructor
2116: * instead of inside the {@link #initialize()} method)
2117: * @return <code>true</code> if the input has no value or when the value
2118: * is empty; or
2119: * <p><code>false</code> otherwise
2120: * @see #hasInputValue(String)
2121: * @see #getNamedInputBean(String)
2122: * @see #getInputBean(Class)
2123: * @see #getInputBean(Class, String)
2124: * @see #getInput(String)
2125: * @see #getInput(String, String)
2126: * @see #getInputValues(String)
2127: * @since 1.0
2128: */
2129: public boolean isInputEmpty(String name) throws EngineException {
2130: if (!mRequestAccessEnabled)
2131: throw new RequestAccessDeniedException();
2132: if (null == mElementContext)
2133: throw new ElementContextMissingException();
2134:
2135: if (null == name)
2136: throw new IllegalArgumentException("name can't be null.");
2137: if (0 == name.length())
2138: throw new IllegalArgumentException("name can't be empty.");
2139:
2140: return mElementContext.isInputEmpty(name);
2141: }
2142:
2143: /**
2144: * Retrieves the value of an input.
2145: *
2146: * @param name the name of the input
2147: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2148: * is known with this name; or if you don't have access to the request
2149: * data (eg. you're inside a child trigger); or if there's no active
2150: * element context (eg. you're using this method inside the constructor
2151: * instead of inside the {@link #initialize()} method)
2152: * @return the value of the input; or
2153: * <p><code>null</code> if no value is present for this input
2154: * @since 1.0
2155: * @see #hasInputValue(String)
2156: * @see #isInputEmpty(String)
2157: * @see #getNamedInputBean(String)
2158: * @see #getInputBean(Class)
2159: * @see #getInputBean(Class, String)
2160: * @see #getInput(String, String)
2161: * @see #getInputValues(String)
2162: */
2163: public String getInput(String name) throws EngineException {
2164: if (!mRequestAccessEnabled)
2165: throw new RequestAccessDeniedException();
2166: if (null == mElementContext)
2167: throw new ElementContextMissingException();
2168:
2169: if (null == name)
2170: throw new IllegalArgumentException("name can't be null.");
2171: if (0 == name.length())
2172: throw new IllegalArgumentException("name can't be empty.");
2173:
2174: return mElementContext.getInput(name);
2175: }
2176:
2177: /**
2178: * Retrieves the value of an input and returns a default value if no input
2179: * value is present
2180: *
2181: * @param name the name of the input
2182: * @param defaultValue the default value that will be used when no input
2183: * value is present
2184: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2185: * is known with this name; or if you don't have access to the request
2186: * data (eg. you're inside a child trigger); or if there's no active
2187: * element context (eg. you're using this method inside the constructor
2188: * instead of inside the {@link #initialize()} method)
2189: * @return the input value; or
2190: * <p>the default value if no input value is present
2191: * @see #hasInputValue(String)
2192: * @see #isInputEmpty(String)
2193: * @see #getNamedInputBean(String)
2194: * @see #getInputBean(Class)
2195: * @see #getInputBean(Class, String)
2196: * @see #getInput(String)
2197: * @see #getInputValues(String)
2198: * @since 1.0
2199: */
2200: public String getInput(String name, String defaultValue)
2201: throws EngineException {
2202: String input = getInput(name);
2203: if (input == null) {
2204: return defaultValue;
2205: }
2206: return input;
2207: }
2208:
2209: /**
2210: * Retrieves the value of a serialized input.
2211: *
2212: * @param name the name of the input
2213: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2214: * is known with this name; or if you don't have access to the request
2215: * data (eg. you're inside a child trigger); or if there's no active
2216: * element context (eg. you're using this method inside the constructor
2217: * instead of inside the {@link #initialize()} method)
2218: * @return the deserialized input
2219: * @see #hasInputValue(String)
2220: * @see #isInputEmpty(String)
2221: * @see #getNamedInputBean(String)
2222: * @see #getInputBean(Class)
2223: * @see #getInputBean(Class, String)
2224: * @see #getInput(String)
2225: * @see #getInputValues(String)
2226: * @since 1.3.1
2227: */
2228: public <TargetType extends Serializable> TargetType getInputSerializable(
2229: String name) throws EngineException {
2230: return (TargetType) getInputSerializable(name, null);
2231: }
2232:
2233: /**
2234: * Retrieves the value of a serialized input and returns a default value if no input
2235: * value is present
2236: *
2237: * @param name the name of the input
2238: * @param defaultValue the default value that will be used when no input
2239: * value is present
2240: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2241: * is known with this name; or if you don't have access to the request
2242: * data (eg. you're inside a child trigger); or if there's no active
2243: * element context (eg. you're using this method inside the constructor
2244: * instead of inside the {@link #initialize()} method)
2245: * @return the deserialized input; or
2246: * <p>the default value if no input value is present
2247: * @see #hasInputValue(String)
2248: * @see #isInputEmpty(String)
2249: * @see #getNamedInputBean(String)
2250: * @see #getInputBean(Class)
2251: * @see #getInputBean(Class, String)
2252: * @see #getInput(String)
2253: * @see #getInputValues(String)
2254: * @since 1.3.1
2255: */
2256: public <TargetType extends Serializable> TargetType getInputSerializable(
2257: String name, TargetType defaultValue)
2258: throws EngineException {
2259: String input = getInput(name);
2260: if (input == null) {
2261: return defaultValue;
2262: }
2263:
2264: try {
2265: return (TargetType) SerializationUtils
2266: .deserializeFromString(input);
2267: } catch (SerializationUtilsErrorException e) {
2268: throw new InputsDeserializationException(
2269: getDeclarationName(), name, e);
2270: }
2271: }
2272:
2273: /**
2274: * Retrieves the value of an input and converts it to a Date.
2275: *
2276: * @param name the name of the input
2277: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2278: * is known with this name; or if you don't have access to the request
2279: * data (eg. you're inside a child trigger); or if there's no active
2280: * element context (eg. you're using this method inside the constructor
2281: * instead of inside the {@link #initialize()} method)
2282: * @return the converted input value; or
2283: * <p>{@code null} if the input didn't have a value
2284: * @see #hasInputValue(String)
2285: * @see #isInputEmpty(String)
2286: * @see #getNamedInputBean(String)
2287: * @see #getInputBean(Class)
2288: * @see #getInputBean(Class, String)
2289: * @see #getInput(String)
2290: * @see #getInput(String, String)
2291: * @see #getInputValues(String)
2292: * @since 1.6.1
2293: */
2294: public Date getInputDate(String name) throws EngineException {
2295: return getInputDate(name, null);
2296: }
2297:
2298: /**
2299: * Retrieves the value of an input and converts it to a Date, using a
2300: * default value if no input value is present.
2301: *
2302: * @param name the name of the input
2303: * @param defaultValue the default value that will be used when no input
2304: * value is present
2305: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2306: * is known with this name; or if you don't have access to the request
2307: * data (eg. you're inside a child trigger); or if there's no active
2308: * element context (eg. you're using this method inside the constructor
2309: * instead of inside the {@link #initialize()} method)
2310: * @return the converted input value; or
2311: * <p>the default value if no input value is present
2312: * @see #hasInputValue(String)
2313: * @see #isInputEmpty(String)
2314: * @see #getNamedInputBean(String)
2315: * @see #getInputBean(Class)
2316: * @see #getInputBean(Class, String)
2317: * @see #getInput(String)
2318: * @see #getInput(String, String)
2319: * @see #getInputValues(String)
2320: * @since 1.6.1
2321: */
2322: public Date getInputDate(String name, Date defaultValue)
2323: throws EngineException {
2324: String input = getInput(name);
2325: if (input == null) {
2326: return defaultValue;
2327: }
2328:
2329: try {
2330: return (Date) Convert.toDate(input);
2331: } catch (ConversionException e) {
2332: throw new EngineException(e);
2333: }
2334: }
2335:
2336: /**
2337: * Retrieves the values of an input.
2338: *
2339: * @param name the name of the input
2340: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2341: * is known with this name; or if you don't have access to the request
2342: * data (eg. you're inside a child trigger); or if there's no active
2343: * element context (eg. you're using this method inside the constructor
2344: * instead of inside the {@link #initialize()} method)
2345: * @return a string array with all the input values; or
2346: * <p><code>null</code> if no input values are present
2347: * @see #hasInputValue(String)
2348: * @see #isInputEmpty(String)
2349: * @see #getNamedInputBean(String)
2350: * @see #getInputBean(Class)
2351: * @see #getInputBean(Class, String)
2352: * @see #getInput(String)
2353: * @see #getInput(String, String)
2354: * @since 1.0
2355: */
2356: public String[] getInputValues(String name) throws EngineException {
2357: if (!mRequestAccessEnabled)
2358: throw new RequestAccessDeniedException();
2359: if (null == mElementContext)
2360: throw new ElementContextMissingException();
2361:
2362: if (null == name)
2363: throw new IllegalArgumentException("name can't be null.");
2364: if (0 == name.length())
2365: throw new IllegalArgumentException("name can't be empty.");
2366:
2367: return mElementContext.getInputValues(name);
2368: }
2369:
2370: /**
2371: * Retrieves the value of an input and converts it to a boolean.
2372: *
2373: * @param name the name of the input
2374: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2375: * is known with this name; or if you don't have access to the request
2376: * data (eg. you're inside a child trigger); or if there's no active
2377: * element context (eg. you're using this method inside the constructor
2378: * instead of inside the {@link #initialize()} method)
2379: * @return the converted input value; or
2380: * <p><code>false</code> if no input value is present or if the input
2381: * value is not a valid boolean
2382: * @see #hasInputValue(String)
2383: * @see #isInputEmpty(String)
2384: * @see #getNamedInputBean(String)
2385: * @see #getInputBean(Class)
2386: * @see #getInputBean(Class, String)
2387: * @see #getInput(String)
2388: * @see #getInput(String, String)
2389: * @see #getInputValues(String)
2390: * @since 1.0
2391: */
2392: public boolean getInputBoolean(String name) throws EngineException {
2393: return getInputBoolean(name, ElementInfo.DEFAULT_BOOLEAN);
2394: }
2395:
2396: /**
2397: * Retrieves the value of an input and converts it to a boolean, using a
2398: * default value if no input value is present.
2399: *
2400: * @param name the name of the input
2401: * @param defaultValue the default value that will be used when no input
2402: * value is present
2403: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2404: * is known with this name; or if you don't have access to the request
2405: * data (eg. you're inside a child trigger); or if there's no active
2406: * element context (eg. you're using this method inside the constructor
2407: * instead of inside the {@link #initialize()} method)
2408: * @return the converted input value; or
2409: * <p>the default value if no input value is present
2410: * @see #hasInputValue(String)
2411: * @see #isInputEmpty(String)
2412: * @see #getNamedInputBean(String)
2413: * @see #getInputBean(Class)
2414: * @see #getInputBean(Class, String)
2415: * @see #getInput(String)
2416: * @see #getInput(String, String)
2417: * @see #getInputValues(String)
2418: * @since 1.0
2419: */
2420: public boolean getInputBoolean(String name, boolean defaultValue)
2421: throws EngineException {
2422: String value = getInput(name);
2423: if (value == null) {
2424: return defaultValue;
2425: }
2426:
2427: return StringUtils.convertToBoolean(value);
2428: }
2429:
2430: /**
2431: * Retrieves the value of an input and converts it to an integer.
2432: *
2433: * @param name the name of the input
2434: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2435: * is known with this name; or if you don't have access to the request
2436: * data (eg. you're inside a child trigger); or if there's no active
2437: * element context (eg. you're using this method inside the constructor
2438: * instead of inside the {@link #initialize()} method)
2439: * @return the converted input value; or
2440: * <p><code>0</code> if no input value is present or if the input value is
2441: * not a valid integer
2442: * @see #hasInputValue(String)
2443: * @see #isInputEmpty(String)
2444: * @see #getNamedInputBean(String)
2445: * @see #getInputBean(Class)
2446: * @see #getInputBean(Class, String)
2447: * @see #getInput(String)
2448: * @see #getInput(String, String)
2449: * @see #getInputValues(String)
2450: * @since 1.0
2451: */
2452: public int getInputInt(String name) throws EngineException {
2453: return getInputInt(name, ElementInfo.DEFAULT_INTEGER);
2454: }
2455:
2456: /**
2457: * Retrieves the value of an input and converts it to an integer, using a
2458: * default value if no input value is present.
2459: *
2460: * @param name the name of the input
2461: * @param defaultValue the default value that will be used when no input
2462: * value is present
2463: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2464: * is known with this name; or if you don't have access to the request
2465: * data (eg. you're inside a child trigger); or if there's no active
2466: * element context (eg. you're using this method inside the constructor
2467: * instead of inside the {@link #initialize()} method)
2468: * @return the converted input value; or
2469: * <p>the default value if no input value is present
2470: * @see #hasInputValue(String)
2471: * @see #isInputEmpty(String)
2472: * @see #getNamedInputBean(String)
2473: * @see #getInputBean(Class)
2474: * @see #getInputBean(Class, String)
2475: * @see #getInput(String)
2476: * @see #getInput(String, String)
2477: * @see #getInputValues(String)
2478: * @since 1.0
2479: */
2480: public int getInputInt(String name, int defaultValue)
2481: throws EngineException {
2482: String value = getInput(name);
2483: if (value == null) {
2484: return defaultValue;
2485: }
2486: try {
2487: return Integer.parseInt(value);
2488: } catch (NumberFormatException e) {
2489: return defaultValue;
2490: }
2491: }
2492:
2493: /**
2494: * Retrieves the value of an input and converts it to a long.
2495: *
2496: * @param name the name of the input
2497: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2498: * is known with this name; or if you don't have access to the request
2499: * data (eg. you're inside a child trigger); or if there's no active
2500: * element context (eg. you're using this method inside the constructor
2501: * instead of inside the {@link #initialize()} method)
2502: * @return the converted input value; or
2503: * <p><code>0L</code> if no input value is present or if the input value
2504: * is not a valid long
2505: * @see #hasInputValue(String)
2506: * @see #isInputEmpty(String)
2507: * @see #getNamedInputBean(String)
2508: * @see #getInputBean(Class)
2509: * @see #getInputBean(Class, String)
2510: * @see #getInput(String)
2511: * @see #getInput(String, String)
2512: * @see #getInputValues(String)
2513: * @since 1.0
2514: */
2515: public long getInputLong(String name) throws EngineException {
2516: return getInputLong(name, ElementInfo.DEFAULT_LONG);
2517: }
2518:
2519: /**
2520: * Retrieves the value of an input and converts it to a long, using a
2521: * default value if no input value is present.
2522: *
2523: * @param name the name of the input
2524: * @param defaultValue the default value that will be used when no input
2525: * value is present
2526: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2527: * is known with this name; or if you don't have access to the request
2528: * data (eg. you're inside a child trigger); or if there's no active
2529: * element context (eg. you're using this method inside the constructor
2530: * instead of inside the {@link #initialize()} method)
2531: * @return the converted input value; or
2532: * <p>the default value if no input value is present
2533: * @see #hasInputValue(String)
2534: * @see #isInputEmpty(String)
2535: * @see #getNamedInputBean(String)
2536: * @see #getInputBean(Class)
2537: * @see #getInputBean(Class, String)
2538: * @see #getInput(String)
2539: * @see #getInput(String, String)
2540: * @see #getInputValues(String)
2541: * @since 1.0
2542: */
2543: public long getInputLong(String name, long defaultValue)
2544: throws EngineException {
2545: String value = getInput(name);
2546: if (value == null) {
2547: return defaultValue;
2548: }
2549: try {
2550: return Long.parseLong(value);
2551: } catch (NumberFormatException e) {
2552: return defaultValue;
2553: }
2554: }
2555:
2556: /**
2557: * Retrieves the value of an input and converts it to a double.
2558: *
2559: * @param name the name of the input
2560: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2561: * is known with this name; or if you don't have access to the request
2562: * data (eg. you're inside a child trigger); or if there's no active
2563: * element context (eg. you're using this method inside the constructor
2564: * instead of inside the {@link #initialize()} method)
2565: * @return the converted input value; or
2566: * <p><code>0.0d</code> if no input value is present or if the input value
2567: * is not a valid double
2568: * @see #hasInputValue(String)
2569: * @see #isInputEmpty(String)
2570: * @see #getNamedInputBean(String)
2571: * @see #getInputBean(Class)
2572: * @see #getInputBean(Class, String)
2573: * @see #getInput(String)
2574: * @see #getInput(String, String)
2575: * @see #getInputValues(String)
2576: * @since 1.0
2577: */
2578: public double getInputDouble(String name) throws EngineException {
2579: return getInputDouble(name, ElementInfo.DEFAULT_DOUBLE);
2580: }
2581:
2582: /**
2583: * Retrieves the value of an input and converts it to a double, using a
2584: * default value if no input value is present.
2585: *
2586: * @param name the name of the input
2587: * @param defaultValue the default value that will be used when no input
2588: * value is present
2589: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2590: * is known with this name; or if you don't have access to the request
2591: * data (eg. you're inside a child trigger); or if there's no active
2592: * element context (eg. you're using this method inside the constructor
2593: * instead of inside the {@link #initialize()} method)
2594: * @return the converted input value; or
2595: * <p>the default value if no input value is present
2596: * @see #hasInputValue(String)
2597: * @see #isInputEmpty(String)
2598: * @see #getNamedInputBean(String)
2599: * @see #getInputBean(Class)
2600: * @see #getInputBean(Class, String)
2601: * @see #getInput(String)
2602: * @see #getInput(String, String)
2603: * @see #getInputValues(String)
2604: * @since 1.0
2605: */
2606: public double getInputDouble(String name, double defaultValue)
2607: throws EngineException {
2608: String value = getInput(name);
2609: if (value == null) {
2610: return defaultValue;
2611: }
2612: try {
2613: return Double.parseDouble(value);
2614: } catch (NumberFormatException e) {
2615: return defaultValue;
2616: }
2617: }
2618:
2619: /**
2620: * Retrieves the value of an input and converts it to a float.
2621: *
2622: * @param name the name of the input
2623: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2624: * is known with this name; or if you don't have access to the request
2625: * data (eg. you're inside a child trigger); or if there's no active
2626: * element context (eg. you're using this method inside the constructor
2627: * instead of inside the {@link #initialize()} method)
2628: * @return the converted input value; or
2629: * <p><code>0.0f</code> if no input value is present or if the input value
2630: * is not a valid float
2631: * @see #hasInputValue(String)
2632: * @see #isInputEmpty(String)
2633: * @see #getNamedInputBean(String)
2634: * @see #getInputBean(Class)
2635: * @see #getInputBean(Class, String)
2636: * @see #getInput(String)
2637: * @see #getInput(String, String)
2638: * @see #getInputValues(String)
2639: * @since 1.0
2640: */
2641: public float getInputFloat(String name) throws EngineException {
2642: return getInputFloat(name, ElementInfo.DEFAULT_FLOAT);
2643: }
2644:
2645: /**
2646: * Retrieves the value of an input and converts it to a float, using a
2647: * default value if no input value is present.
2648: *
2649: * @param name the name of the input
2650: * @param defaultValue the default value that will be used when no input
2651: * value is present
2652: * @exception com.uwyn.rife.engine.exceptions.EngineException if no input
2653: * is known with this name; or if you don't have access to the request
2654: * data (eg. you're inside a child trigger); or if there's no active
2655: * element context (eg. you're using this method inside the constructor
2656: * instead of inside the {@link #initialize()} method)
2657: * @return the converted input value; or
2658: * <p>the default value if no input value is present
2659: * @see #hasInputValue(String)
2660: * @see #isInputEmpty(String)
2661: * @see #getNamedInputBean(String)
2662: * @see #getInputBean(Class)
2663: * @see #getInputBean(Class, String)
2664: * @see #getInput(String)
2665: * @see #getInput(String, String)
2666: * @see #getInputValues(String)
2667: * @since 1.0
2668: */
2669: public float getInputFloat(String name, float defaultValue)
2670: throws EngineException {
2671: String value = getInput(name);
2672: if (value == null) {
2673: return defaultValue;
2674: }
2675: try {
2676: return Float.parseFloat(value);
2677: } catch (NumberFormatException e) {
2678: return defaultValue;
2679: }
2680: }
2681:
2682: /**
2683: * Sets a select box option, a radio button or a checkbox to selected or
2684: * checked according to input values.
2685: * <p>The actual logic is performed by the {@link
2686: * #selectParameter(Template, String, String[])} method. This method only
2687: * prefixes the parameter name with the <code>INPUT:</code> literal, which
2688: * is the syntax that is used to be able to handle automatic population
2689: * correctly for each value type (inputs or submission parameters).
2690: * <p>This method is automatically called during the {@link
2691: * #print(Template)} for all the inputs and values that this element
2692: * received. You should thus only call it explicitly if you need it to be
2693: * executed with custom values.
2694: *
2695: * @param template the template instance where the selection should happen
2696: * @param name the name of the input
2697: * @param values the values that should selected or checked
2698: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
2699: * no active element context (eg. you're using this method inside the
2700: * constructor instead of inside the {@link #initialize()} method)
2701: * @return a list with the identifiers of the template values that have
2702: * been set, this is never <code>null</code>, when no values are set an
2703: * empty list is returned
2704: * @see #selectParameter(Template, String, String[])
2705: * @see #selectSubmissionParameter(Template, String, String[])
2706: * @since 1.0
2707: */
2708: public Collection<String> selectInputParameter(Template template,
2709: String name, String[] values) throws EngineException {
2710: if (null == mElementContext)
2711: throw new ElementContextMissingException();
2712:
2713: if (null == template)
2714: throw new IllegalArgumentException(
2715: "template can't be null.");
2716: if (null == name)
2717: throw new IllegalArgumentException("name can't be null.");
2718: if (0 == name.length())
2719: throw new IllegalArgumentException("name can't be empty.");
2720:
2721: return mElementContext.selectInputParameter(template, name,
2722: values);
2723: }
2724:
2725: /**
2726: * Sets the value of an output.
2727: *
2728: * @param name the name of the output
2729: * @param value the value that has to be set
2730: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
2731: * is known with this name; if you don't have access to the request data
2732: * (eg. you're inside a child trigger); or if there's no active element
2733: * context (eg. you're using this method inside the constructor instead of
2734: * inside the {@link #initialize()} method)
2735: * @see #setNamedOutputBean(String, Object)
2736: * @see #setOutputBean(Object)
2737: * @see #setOutputBean(Object, String)
2738: * @see #setOutput(String, String[])
2739: * @see #addOutputValue(String, String)
2740: * @see #addOutputValues(String, String[])
2741: * @see #clearOutput(String)
2742: * @see #clearNamedOutputBean(String)
2743: * @see #clearOutputBean(Class)
2744: * @see #clearOutputBean(Class, String)
2745: * @see #getOutput(String)
2746: * @since 1.0
2747: */
2748: public void setOutput(String name, String value)
2749: throws EngineException {
2750: if (!mRequestAccessEnabled)
2751: throw new RequestAccessDeniedException();
2752: if (null == mElementContext)
2753: throw new ElementContextMissingException();
2754:
2755: if (null == name)
2756: throw new IllegalArgumentException("name can't be null.");
2757: if (0 == name.length())
2758: throw new IllegalArgumentException("name can't be empty.");
2759: if (null == value)
2760: throw new IllegalArgumentException("value can't be null.");
2761:
2762: mElementContext.setOutput(name, value);
2763: }
2764:
2765: /**
2766: * Set the values of an output.
2767: *
2768: * @param name the name of the output
2769: * @param values the values that have to be set
2770: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
2771: * is known with this name; if you don't have access to the request data
2772: * (eg. you're inside a child trigger); or if there's no active element
2773: * context (eg. you're using this method inside the constructor instead of
2774: * inside the {@link #initialize()} method)
2775: * @see #setNamedOutputBean(String, Object)
2776: * @see #setOutputBean(Object)
2777: * @see #setOutputBean(Object, String)
2778: * @see #setOutput(String, String)
2779: * @see #addOutputValue(String, String)
2780: * @see #addOutputValues(String, String[])
2781: * @see #clearOutput(String)
2782: * @see #clearNamedOutputBean(String)
2783: * @see #clearOutputBean(Class)
2784: * @see #clearOutputBean(Class, String)
2785: * @see #getOutput(String)
2786: * @since 1.0
2787: */
2788: public void setOutput(String name, String[] values)
2789: throws EngineException {
2790: if (!mRequestAccessEnabled)
2791: throw new RequestAccessDeniedException();
2792: if (null == mElementContext)
2793: throw new ElementContextMissingException();
2794:
2795: if (null == name)
2796: throw new IllegalArgumentException("name can't be null.");
2797: if (0 == name.length())
2798: throw new IllegalArgumentException("name can't be empty.");
2799: if (null == values)
2800: throw new IllegalArgumentException("values can't be null.");
2801: if (0 == values.length)
2802: throw new IllegalArgumentException("values can't be empty.");
2803:
2804: mElementContext.setOutput(name, values);
2805: }
2806:
2807: /**
2808: * Sets the value of an output from a <code>boolean</code>.
2809: *
2810: * @param name the name of the output
2811: * @param value the value that has to be set
2812: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
2813: * is known with this name; if you don't have access to the request data
2814: * (eg. you're inside a child trigger); or if there's no active element
2815: * context (eg. you're using this method inside the constructor instead of
2816: * inside the {@link #initialize()} method)
2817: * @see #setNamedOutputBean(String, Object)
2818: * @see #setOutputBean(Object)
2819: * @see #setOutputBean(Object, String)
2820: * @see #setOutput(String, String)
2821: * @see #setOutput(String, String[])
2822: * @see #addOutputValue(String, String)
2823: * @see #addOutputValues(String, String[])
2824: * @see #clearOutput(String)
2825: * @see #clearNamedOutputBean(String)
2826: * @see #clearOutputBean(Class)
2827: * @see #clearOutputBean(Class, String)
2828: * @see #getOutput(String)
2829: * @since 1.0
2830: */
2831: public void setOutput(String name, boolean value)
2832: throws EngineException {
2833: if (!mRequestAccessEnabled)
2834: throw new RequestAccessDeniedException();
2835: if (null == mElementContext)
2836: throw new ElementContextMissingException();
2837:
2838: if (null == name)
2839: throw new IllegalArgumentException("name can't be null.");
2840: if (0 == name.length())
2841: throw new IllegalArgumentException("name can't be empty.");
2842:
2843: mElementContext.setOutput(name, String.valueOf(value));
2844: }
2845:
2846: /**
2847: * Sets the value of an output from a <code>char</code>.
2848: *
2849: * @param name the name of the output
2850: * @param value the value that has to be set
2851: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
2852: * is known with this name; if you don't have access to the request data
2853: * (eg. you're inside a child trigger); or if there's no active element
2854: * context (eg. you're using this method inside the constructor instead of
2855: * inside the {@link #initialize()} method)
2856: * @see #setNamedOutputBean(String, Object)
2857: * @see #setOutputBean(Object)
2858: * @see #setOutputBean(Object, String)
2859: * @see #setOutput(String, String)
2860: * @see #setOutput(String, String[])
2861: * @see #addOutputValue(String, String)
2862: * @see #addOutputValues(String, String[])
2863: * @see #clearOutput(String)
2864: * @see #clearNamedOutputBean(String)
2865: * @see #clearOutputBean(Class)
2866: * @see #clearOutputBean(Class, String)
2867: * @see #getOutput(String)
2868: * @since 1.0
2869: */
2870: public void setOutput(String name, char value)
2871: throws EngineException {
2872: if (!mRequestAccessEnabled)
2873: throw new RequestAccessDeniedException();
2874: if (null == mElementContext)
2875: throw new ElementContextMissingException();
2876:
2877: if (null == name)
2878: throw new IllegalArgumentException("name can't be null.");
2879: if (0 == name.length())
2880: throw new IllegalArgumentException("name can't be empty.");
2881:
2882: mElementContext.setOutput(name, String.valueOf(value));
2883: }
2884:
2885: /**
2886: * Set the value of an output from an array of <code>char</code>s that
2887: * will be concatenated to a <code>String</code>.
2888: *
2889: * @param name the name of the output
2890: * @param value the value that has to be set
2891: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
2892: * is known with this name; if you don't have access to the request data
2893: * (eg. you're inside a child trigger); or if there's no active element
2894: * context (eg. you're using this method inside the constructor instead of
2895: * inside the {@link #initialize()} method)
2896: * @see #setNamedOutputBean(String, Object)
2897: * @see #setOutputBean(Object)
2898: * @see #setOutputBean(Object, String)
2899: * @see #setOutput(String, String)
2900: * @see #setOutput(String, String[])
2901: * @see #addOutputValue(String, String)
2902: * @see #addOutputValues(String, String[])
2903: * @see #clearOutput(String)
2904: * @see #clearNamedOutputBean(String)
2905: * @see #clearOutputBean(Class)
2906: * @see #clearOutputBean(Class, String)
2907: * @see #getOutput(String)
2908: * @since 1.0
2909: */
2910: public void setOutput(String name, char[] value)
2911: throws EngineException {
2912: if (!mRequestAccessEnabled)
2913: throw new RequestAccessDeniedException();
2914: if (null == mElementContext)
2915: throw new ElementContextMissingException();
2916:
2917: if (null == name)
2918: throw new IllegalArgumentException("name can't be null.");
2919: if (0 == name.length())
2920: throw new IllegalArgumentException("name can't be empty.");
2921:
2922: mElementContext.setOutput(name, String.valueOf(value));
2923: }
2924:
2925: /**
2926: * Sets the value of an output from a <code>double</code>.
2927: *
2928: * @param name the name of the output
2929: * @param value the value that has to be set
2930: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
2931: * is known with this name; if you don't have access to the request data
2932: * (eg. you're inside a child trigger); or if there's no active element
2933: * context (eg. you're using this method inside the constructor instead of
2934: * inside the {@link #initialize()} method)
2935: * @see #setNamedOutputBean(String, Object)
2936: * @see #setOutputBean(Object)
2937: * @see #setOutputBean(Object, String)
2938: * @see #setOutput(String, String)
2939: * @see #setOutput(String, String[])
2940: * @see #addOutputValue(String, String)
2941: * @see #addOutputValues(String, String[])
2942: * @see #clearOutput(String)
2943: * @see #clearNamedOutputBean(String)
2944: * @see #clearOutputBean(Class)
2945: * @see #clearOutputBean(Class, String)
2946: * @see #getOutput(String)
2947: * @since 1.0
2948: */
2949: public void setOutput(String name, double value)
2950: throws EngineException {
2951: if (!mRequestAccessEnabled)
2952: throw new RequestAccessDeniedException();
2953: if (null == mElementContext)
2954: throw new ElementContextMissingException();
2955:
2956: if (null == name)
2957: throw new IllegalArgumentException("name can't be null.");
2958: if (0 == name.length())
2959: throw new IllegalArgumentException("name can't be empty.");
2960:
2961: mElementContext.setOutput(name, String.valueOf(value));
2962: }
2963:
2964: /**
2965: * Sets the value of an output from a <code>float</code>.
2966: *
2967: * @param name the name of the output
2968: * @param value the value that has to be set
2969: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
2970: * is known with this name; if you don't have access to the request data
2971: * (eg. you're inside a child trigger); or if there's no active element
2972: * context (eg. you're using this method inside the constructor instead of
2973: * inside the {@link #initialize()} method)
2974: * @see #setNamedOutputBean(String, Object)
2975: * @see #setOutputBean(Object)
2976: * @see #setOutputBean(Object, String)
2977: * @see #setOutput(String, String)
2978: * @see #setOutput(String, String[])
2979: * @see #addOutputValue(String, String)
2980: * @see #addOutputValues(String, String[])
2981: * @see #clearOutput(String)
2982: * @see #clearNamedOutputBean(String)
2983: * @see #clearOutputBean(Class)
2984: * @see #clearOutputBean(Class, String)
2985: * @see #getOutput(String)
2986: * @since 1.0
2987: */
2988: public void setOutput(String name, float value)
2989: throws EngineException {
2990: if (!mRequestAccessEnabled)
2991: throw new RequestAccessDeniedException();
2992: if (null == mElementContext)
2993: throw new ElementContextMissingException();
2994:
2995: if (null == name)
2996: throw new IllegalArgumentException("name can't be null.");
2997: if (0 == name.length())
2998: throw new IllegalArgumentException("name can't be empty.");
2999:
3000: mElementContext.setOutput(name, String.valueOf(value));
3001: }
3002:
3003: /**
3004: * Sets the value of an output from an <code>int</code>.
3005: *
3006: * @param name the name of the output
3007: * @param value the value that has to be set
3008: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3009: * is known with this name; if you don't have access to the request data
3010: * (eg. you're inside a child trigger); or if there's no active element
3011: * context (eg. you're using this method inside the constructor instead of
3012: * inside the {@link #initialize()} method)
3013: * @see #setNamedOutputBean(String, Object)
3014: * @see #setOutputBean(Object)
3015: * @see #setOutputBean(Object, String)
3016: * @see #setOutput(String, String)
3017: * @see #setOutput(String, String[])
3018: * @see #addOutputValue(String, String)
3019: * @see #addOutputValues(String, String[])
3020: * @see #clearOutput(String)
3021: * @see #clearNamedOutputBean(String)
3022: * @see #clearOutputBean(Class)
3023: * @see #clearOutputBean(Class, String)
3024: * @see #getOutput(String)
3025: * @since 1.0
3026: */
3027: public void setOutput(String name, int value)
3028: throws EngineException {
3029: if (!mRequestAccessEnabled)
3030: throw new RequestAccessDeniedException();
3031: if (null == mElementContext)
3032: throw new ElementContextMissingException();
3033:
3034: if (null == name)
3035: throw new IllegalArgumentException("name can't be null.");
3036: if (0 == name.length())
3037: throw new IllegalArgumentException("name can't be empty.");
3038:
3039: mElementContext.setOutput(name, String.valueOf(value));
3040: }
3041:
3042: /**
3043: * Sets the value of an output from a <code>long</code>.
3044: *
3045: * @param name the name of the output
3046: * @param value the value that has to be set
3047: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3048: * is known with this name; if you don't have access to the request data
3049: * (eg. you're inside a child trigger); or if there's no active element
3050: * context (eg. you're using this method inside the constructor instead of
3051: * inside the {@link #initialize()} method)
3052: * @see #setNamedOutputBean(String, Object)
3053: * @see #setOutputBean(Object)
3054: * @see #setOutputBean(Object, String)
3055: * @see #setOutput(String, String)
3056: * @see #setOutput(String, String[])
3057: * @see #addOutputValue(String, String)
3058: * @see #addOutputValues(String, String[])
3059: * @see #clearOutput(String)
3060: * @see #clearNamedOutputBean(String)
3061: * @see #clearOutputBean(Class)
3062: * @see #clearOutputBean(Class, String)
3063: * @see #getOutput(String)
3064: * @since 1.0
3065: */
3066: public void setOutput(String name, long value)
3067: throws EngineException {
3068: if (!mRequestAccessEnabled)
3069: throw new RequestAccessDeniedException();
3070: if (null == mElementContext)
3071: throw new ElementContextMissingException();
3072:
3073: if (null == name)
3074: throw new IllegalArgumentException("name can't be null.");
3075: if (0 == name.length())
3076: throw new IllegalArgumentException("name can't be empty.");
3077:
3078: mElementContext.setOutput(name, String.valueOf(value));
3079: }
3080:
3081: /**
3082: * Sets the value of an output from a generic <code>object</code>. The object
3083: * will be converted to its <code>String</code> representation.
3084: *
3085: * @param name the name of the output
3086: * @param value the value that has to be set
3087: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3088: * is known with this name; if you don't have access to the request data
3089: * (eg. you're inside a child trigger); or if there's no active element
3090: * context (eg. you're using this method inside the constructor instead of
3091: * inside the {@link #initialize()} method)
3092: * @see #setNamedOutputBean(String, Object)
3093: * @see #setOutputBean(Object)
3094: * @see #setOutputBean(Object, String)
3095: * @see #setOutput(String, String)
3096: * @see #setOutput(String, String[])
3097: * @see #addOutputValue(String, String)
3098: * @see #addOutputValues(String, String[])
3099: * @see #clearOutput(String)
3100: * @see #clearNamedOutputBean(String)
3101: * @see #clearOutputBean(Class)
3102: * @see #clearOutputBean(Class, String)
3103: * @see #getOutput(String)
3104: * @since 1.0
3105: */
3106: public void setOutput(String name, Object value)
3107: throws EngineException {
3108: if (!mRequestAccessEnabled)
3109: throw new RequestAccessDeniedException();
3110: if (null == mElementContext)
3111: throw new ElementContextMissingException();
3112:
3113: if (null == name)
3114: throw new IllegalArgumentException("name can't be null.");
3115: if (0 == name.length())
3116: throw new IllegalArgumentException("name can't be empty.");
3117:
3118: mElementContext.setOutput(name, value, null);
3119: }
3120:
3121: /**
3122: * Adds a value to the current values of an output.
3123: *
3124: * @param name the name of the output
3125: * @param value the value that has to be added
3126: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3127: * is known with this name; if you don't have access to the request data
3128: * (eg. you're inside a child trigger); or if there's no active element
3129: * context (eg. you're using this method inside the constructor instead of
3130: * inside the {@link #initialize()} method)
3131: * @see #setNamedOutputBean(String, Object)
3132: * @see #setOutputBean(Object)
3133: * @see #setOutputBean(Object, String)
3134: * @see #setOutput(String, String)
3135: * @see #setOutput(String, String[])
3136: * @see #addOutputValues(String, String[])
3137: * @see #clearOutput(String)
3138: * @see #clearNamedOutputBean(String)
3139: * @see #clearOutputBean(Class)
3140: * @see #clearOutputBean(Class, String)
3141: * @see #getOutput(String)
3142: * @since 1.0
3143: */
3144: public void addOutputValue(String name, String value)
3145: throws EngineException {
3146: if (!mRequestAccessEnabled)
3147: throw new RequestAccessDeniedException();
3148: if (null == mElementContext)
3149: throw new ElementContextMissingException();
3150:
3151: if (null == name)
3152: throw new IllegalArgumentException("name can't be null.");
3153: if (0 == name.length())
3154: throw new IllegalArgumentException("name can't be empty.");
3155: if (null == value)
3156: throw new IllegalArgumentException("value can't be null.");
3157:
3158: mElementContext.addOutputValue(name, value);
3159: }
3160:
3161: /**
3162: * Adds values to the current values of an output.
3163: *
3164: * @param name the name of the output
3165: * @param values the values that have to be added
3166: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3167: * is known with this name; if you don't have access to the request data
3168: * (eg. you're inside a child trigger); or if there's no active element
3169: * context (eg. you're using this method inside the constructor instead of
3170: * inside the {@link #initialize()} method)
3171: * @see #setNamedOutputBean(String, Object)
3172: * @see #setOutputBean(Object)
3173: * @see #setOutputBean(Object, String)
3174: * @see #setOutput(String, String)
3175: * @see #setOutput(String, String[])
3176: * @see #addOutputValue(String, String)
3177: * @see #clearOutput(String)
3178: * @see #clearNamedOutputBean(String)
3179: * @see #clearOutputBean(Class)
3180: * @see #clearOutputBean(Class, String)
3181: * @see #getOutput(String)
3182: * @since 1.0
3183: */
3184: public void addOutputValues(String name, String[] values)
3185: throws EngineException {
3186: if (!mRequestAccessEnabled)
3187: throw new RequestAccessDeniedException();
3188: if (null == mElementContext)
3189: throw new ElementContextMissingException();
3190:
3191: if (null == name)
3192: throw new IllegalArgumentException("name can't be null.");
3193: if (0 == name.length())
3194: throw new IllegalArgumentException("name can't be empty.");
3195: if (null == values)
3196: throw new IllegalArgumentException("values can't be null.");
3197: if (0 == values.length)
3198: throw new IllegalArgumentException("values can't be empty.");
3199:
3200: mElementContext.addOutputValues(name, values);
3201: }
3202:
3203: /**
3204: * Adds a <code>boolean</code> value to the current values of an output.
3205: *
3206: * @param name the name of the output
3207: * @param value the value that has to be added
3208: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3209: * is known with this name; if you don't have access to the request data
3210: * (eg. you're inside a child trigger); or if there's no active element
3211: * context (eg. you're using this method inside the constructor instead of
3212: * inside the {@link #initialize()} method)
3213: * @see #setNamedOutputBean(String, Object)
3214: * @see #setOutputBean(Object)
3215: * @see #setOutputBean(Object, String)
3216: * @see #setOutput(String, String)
3217: * @see #setOutput(String, String[])
3218: * @see #addOutputValue(String, String)
3219: * @see #addOutputValues(String, String[])
3220: * @see #clearOutput(String)
3221: * @see #clearNamedOutputBean(String)
3222: * @see #clearOutputBean(Class)
3223: * @see #clearOutputBean(Class, String)
3224: * @see #getOutput(String)
3225: * @since 1.0
3226: */
3227: public void addOutputValue(String name, boolean value)
3228: throws EngineException {
3229: if (!mRequestAccessEnabled)
3230: throw new RequestAccessDeniedException();
3231: if (null == mElementContext)
3232: throw new ElementContextMissingException();
3233:
3234: if (null == name)
3235: throw new IllegalArgumentException("name can't be null.");
3236: if (0 == name.length())
3237: throw new IllegalArgumentException("name can't be empty.");
3238:
3239: mElementContext.addOutputValue(name, String.valueOf(value));
3240: }
3241:
3242: /**
3243: * Adds a <code>char</code> value to the current values of an output.
3244: *
3245: * @param name the name of the output
3246: * @param value the value that has to be added
3247: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3248: * is known with this name; if you don't have access to the request data
3249: * (eg. you're inside a child trigger); or if there's no active element
3250: * context (eg. you're using this method inside the constructor instead of
3251: * inside the {@link #initialize()} method)
3252: * @see #setNamedOutputBean(String, Object)
3253: * @see #setOutputBean(Object)
3254: * @see #setOutputBean(Object, String)
3255: * @see #setOutput(String, String)
3256: * @see #setOutput(String, String[])
3257: * @see #addOutputValue(String, String)
3258: * @see #addOutputValues(String, String[])
3259: * @see #clearOutput(String)
3260: * @see #clearNamedOutputBean(String)
3261: * @see #clearOutputBean(Class)
3262: * @see #clearOutputBean(Class, String)
3263: * @see #getOutput(String)
3264: * @since 1.0
3265: */
3266: public void addOutputValue(String name, char value)
3267: throws EngineException {
3268: if (!mRequestAccessEnabled)
3269: throw new RequestAccessDeniedException();
3270: if (null == mElementContext)
3271: throw new ElementContextMissingException();
3272:
3273: if (null == name)
3274: throw new IllegalArgumentException("name can't be null.");
3275: if (0 == name.length())
3276: throw new IllegalArgumentException("name can't be empty.");
3277:
3278: mElementContext.addOutputValue(name, String.valueOf(value));
3279: }
3280:
3281: /**
3282: * Adds values from an array of <code>char</code>s to the current values
3283: * of an output.
3284: *
3285: * @param name the name of the output
3286: * @param value the values that have to be added
3287: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3288: * is known with this name; if you don't have access to the request data
3289: * (eg. you're inside a child trigger); or if there's no active element
3290: * context (eg. you're using this method inside the constructor instead of
3291: * inside the {@link #initialize()} method)
3292: * @see #setNamedOutputBean(String, Object)
3293: * @see #setOutputBean(Object)
3294: * @see #setOutputBean(Object, String)
3295: * @see #setOutput(String, String)
3296: * @see #setOutput(String, String[])
3297: * @see #addOutputValue(String, String)
3298: * @see #addOutputValues(String, String[])
3299: * @see #clearOutput(String)
3300: * @see #clearNamedOutputBean(String)
3301: * @see #clearOutputBean(Class)
3302: * @see #clearOutputBean(Class, String)
3303: * @see #getOutput(String)
3304: * @since 1.0
3305: */
3306: public void addOutputValue(String name, char[] value)
3307: throws EngineException {
3308: if (!mRequestAccessEnabled)
3309: throw new RequestAccessDeniedException();
3310: if (null == mElementContext)
3311: throw new ElementContextMissingException();
3312:
3313: if (null == name)
3314: throw new IllegalArgumentException("name can't be null.");
3315: if (0 == name.length())
3316: throw new IllegalArgumentException("name can't be empty.");
3317:
3318: mElementContext.addOutputValue(name, String.valueOf(value));
3319: }
3320:
3321: /**
3322: * Adds a <code>double</code> value to the current values of an output.
3323: *
3324: * @param name the name of the output
3325: * @param value the value that has to be added
3326: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3327: * is known with this name; if you don't have access to the request data
3328: * (eg. you're inside a child trigger); or if there's no active element
3329: * context (eg. you're using this method inside the constructor instead of
3330: * inside the {@link #initialize()} method)
3331: * @see #setNamedOutputBean(String, Object)
3332: * @see #setOutputBean(Object)
3333: * @see #setOutputBean(Object, String)
3334: * @see #setOutput(String, String)
3335: * @see #setOutput(String, String[])
3336: * @see #addOutputValue(String, String)
3337: * @see #addOutputValues(String, String[])
3338: * @see #clearOutput(String)
3339: * @see #clearNamedOutputBean(String)
3340: * @see #clearOutputBean(Class)
3341: * @see #clearOutputBean(Class, String)
3342: * @see #getOutput(String)
3343: * @since 1.0
3344: */
3345: public void addOutputValue(String name, double value)
3346: throws EngineException {
3347: if (!mRequestAccessEnabled)
3348: throw new RequestAccessDeniedException();
3349: if (null == mElementContext)
3350: throw new ElementContextMissingException();
3351:
3352: if (null == name)
3353: throw new IllegalArgumentException("name can't be null.");
3354: if (0 == name.length())
3355: throw new IllegalArgumentException("name can't be empty.");
3356:
3357: mElementContext.addOutputValue(name, String.valueOf(value));
3358: }
3359:
3360: /**
3361: * Adds a <code>float</code> value to the current values of an output.
3362: *
3363: * @param name the name of the output
3364: * @param value the value that has to be added
3365: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3366: * is known with this name; if you don't have access to the request data
3367: * (eg. you're inside a child trigger); or if there's no active element
3368: * context (eg. you're using this method inside the constructor instead of
3369: * inside the {@link #initialize()} method)
3370: * @see #setNamedOutputBean(String, Object)
3371: * @see #setOutputBean(Object)
3372: * @see #setOutputBean(Object, String)
3373: * @see #setOutput(String, String)
3374: * @see #setOutput(String, String[])
3375: * @see #addOutputValue(String, String)
3376: * @see #addOutputValues(String, String[])
3377: * @see #clearOutput(String)
3378: * @see #clearNamedOutputBean(String)
3379: * @see #clearOutputBean(Class)
3380: * @see #clearOutputBean(Class, String)
3381: * @see #getOutput(String)
3382: * @since 1.0
3383: */
3384: public void addOutputValue(String name, float value)
3385: throws EngineException {
3386: if (!mRequestAccessEnabled)
3387: throw new RequestAccessDeniedException();
3388: if (null == mElementContext)
3389: throw new ElementContextMissingException();
3390:
3391: if (null == name)
3392: throw new IllegalArgumentException("name can't be null.");
3393: if (0 == name.length())
3394: throw new IllegalArgumentException("name can't be empty.");
3395:
3396: mElementContext.addOutputValue(name, String.valueOf(value));
3397: }
3398:
3399: /**
3400: * Adds a <code>int</code> value to the current values of an output.
3401: *
3402: * @param name the name of the output
3403: * @param value the value that has to be added
3404: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3405: * is known with this name; if you don't have access to the request data
3406: * (eg. you're inside a child trigger); or if there's no active element
3407: * context (eg. you're using this method inside the constructor instead of
3408: * inside the {@link #initialize()} method)
3409: * @see #setNamedOutputBean(String, Object)
3410: * @see #setOutputBean(Object)
3411: * @see #setOutputBean(Object, String)
3412: * @see #setOutput(String, String)
3413: * @see #setOutput(String, String[])
3414: * @see #addOutputValue(String, String)
3415: * @see #addOutputValues(String, String[])
3416: * @see #clearOutput(String)
3417: * @see #clearNamedOutputBean(String)
3418: * @see #clearOutputBean(Class)
3419: * @see #clearOutputBean(Class, String)
3420: * @see #getOutput(String)
3421: * @since 1.0
3422: */
3423: public void addOutputValue(String name, int value)
3424: throws EngineException {
3425: if (!mRequestAccessEnabled)
3426: throw new RequestAccessDeniedException();
3427: if (null == mElementContext)
3428: throw new ElementContextMissingException();
3429:
3430: if (null == name)
3431: throw new IllegalArgumentException("name can't be null.");
3432: if (0 == name.length())
3433: throw new IllegalArgumentException("name can't be empty.");
3434:
3435: mElementContext.addOutputValue(name, String.valueOf(value));
3436: }
3437:
3438: /**
3439: * Adds a <code>long</code> value to the current values of an output.
3440: *
3441: * @param name the name of the output
3442: * @param value the value that has to be added
3443: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3444: * is known with this name; if you don't have access to the request data
3445: * (eg. you're inside a child trigger); or if there's no active element
3446: * context (eg. you're using this method inside the constructor instead of
3447: * inside the {@link #initialize()} method)
3448: * @see #setNamedOutputBean(String, Object)
3449: * @see #setOutputBean(Object)
3450: * @see #setOutputBean(Object, String)
3451: * @see #setOutput(String, String)
3452: * @see #setOutput(String, String[])
3453: * @see #addOutputValue(String, String)
3454: * @see #addOutputValues(String, String[])
3455: * @see #clearOutput(String)
3456: * @see #clearNamedOutputBean(String)
3457: * @see #clearOutputBean(Class)
3458: * @see #clearOutputBean(Class, String)
3459: * @see #getOutput(String)
3460: * @since 1.0
3461: */
3462: public void addOutputValue(String name, long value)
3463: throws EngineException {
3464: if (!mRequestAccessEnabled)
3465: throw new RequestAccessDeniedException();
3466: if (null == mElementContext)
3467: throw new ElementContextMissingException();
3468:
3469: if (null == name)
3470: throw new IllegalArgumentException("name can't be null.");
3471: if (0 == name.length())
3472: throw new IllegalArgumentException("name can't be empty.");
3473:
3474: mElementContext.addOutputValue(name, String.valueOf(value));
3475: }
3476:
3477: /**
3478: * Adds a generic <code>object</code> value to the current values of an
3479: * output.
3480: *
3481: * @param name the name of the output
3482: * @param value the value that has to be added
3483: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3484: * is known with this name; if you don't have access to the request data
3485: * (eg. you're inside a child trigger); or if there's no active element
3486: * context (eg. you're using this method inside the constructor instead of
3487: * inside the {@link #initialize()} method)
3488: * @see #setNamedOutputBean(String, Object)
3489: * @see #setOutputBean(Object)
3490: * @see #setOutputBean(Object, String)
3491: * @see #setOutput(String, String)
3492: * @see #setOutput(String, String[])
3493: * @see #addOutputValue(String, String)
3494: * @see #addOutputValues(String, String[])
3495: * @see #clearOutput(String)
3496: * @see #clearNamedOutputBean(String)
3497: * @see #clearOutputBean(Class)
3498: * @see #clearOutputBean(Class, String)
3499: * @see #getOutput(String)
3500: * @since 1.0
3501: */
3502: public void addOutputValue(String name, Object value)
3503: throws EngineException {
3504: if (!mRequestAccessEnabled)
3505: throw new RequestAccessDeniedException();
3506: if (null == mElementContext)
3507: throw new ElementContextMissingException();
3508:
3509: if (null == name)
3510: throw new IllegalArgumentException("name can't be null.");
3511: if (0 == name.length())
3512: throw new IllegalArgumentException("name can't be empty.");
3513:
3514: mElementContext.addOutputValue(name, value);
3515: }
3516:
3517: /**
3518: * Sets an instance of a named output bean and populates the output values
3519: * from the property values. The class of the bean is looked up through
3520: * its name, as is the property prefix.
3521: * <p>This bean is not serialized or deserialized, each output corresponds
3522: * to a property and is individually sent to the client.
3523: *
3524: * @param name the name of the output bean
3525: * @param bean the bean instance that should be used to set the outputs
3526: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3527: * bean is known with this name; or if you don't have access to the
3528: * request data (eg. you're inside a child trigger); or if there's no
3529: * active element context (eg. you're using this method inside the
3530: * constructor instead of inside the {@link #initialize()} method)
3531: * @see #setOutputBean(Object)
3532: * @see #setOutputBean(Object, String)
3533: * @see #setOutput(String, String)
3534: * @see #setOutput(String, String[])
3535: * @see #addOutputValue(String, String)
3536: * @see #addOutputValues(String, String[])
3537: * @see #clearOutput(String)
3538: * @see #clearNamedOutputBean(String)
3539: * @see #clearOutputBean(Class)
3540: * @see #clearOutputBean(Class, String)
3541: * @see #getOutput(String)
3542: * @since 1.0
3543: */
3544: public void setNamedOutputBean(String name, Object bean)
3545: throws EngineException {
3546: if (!mRequestAccessEnabled)
3547: throw new RequestAccessDeniedException();
3548: if (null == mElementContext)
3549: throw new ElementContextMissingException();
3550:
3551: if (null == name)
3552: throw new IllegalArgumentException("name can't be null.");
3553: if (0 == name.length())
3554: throw new IllegalArgumentException("name can't be empty.");
3555: if (null == bean)
3556: throw new IllegalArgumentException("bean can't be null.");
3557:
3558: mElementContext.setNamedOutputBean(name, bean);
3559: }
3560:
3561: /**
3562: * Sets an instance of a named input bean and populates the output values
3563: * from the property values.
3564: * <p>This bean is not serialized or deserialized, each output corresponds
3565: * to a property and is individually sent to the client.
3566: *
3567: * @param bean the bean instance that should be used to set the outputs
3568: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
3569: * have access to the request data (eg. you're inside a child trigger); or
3570: * if there's no active element context (eg. you're using this method
3571: * inside the constructor instead of inside the {@link #initialize()}
3572: * method)
3573: * @see #setNamedOutputBean(String, Object)
3574: * @see #setOutputBean(Object, String)
3575: * @see #setOutput(String, String)
3576: * @see #setOutput(String, String[])
3577: * @see #addOutputValue(String, String)
3578: * @see #addOutputValues(String, String[])
3579: * @see #clearOutput(String)
3580: * @see #clearNamedOutputBean(String)
3581: * @see #clearOutputBean(Class)
3582: * @see #clearOutputBean(Class, String)
3583: * @see #getOutput(String)
3584: * @since 1.0
3585: */
3586: public void setOutputBean(Object bean) throws EngineException {
3587: if (!mRequestAccessEnabled)
3588: throw new RequestAccessDeniedException();
3589: if (null == mElementContext)
3590: throw new ElementContextMissingException();
3591:
3592: if (null == bean)
3593: throw new IllegalArgumentException("bean can't be null.");
3594:
3595: mElementContext.setOutputBean(bean, null);
3596: }
3597:
3598: /**
3599: * Sets an instance of a named input bean and populates the output values
3600: * from the property values.
3601: * <p>This bean is not serialized or deserialized, each output corresponds
3602: * to a property and is individually sent to the client.
3603: *
3604: * @param bean the bean instance that should be used to set the outputs
3605: * @param prefix the prefix that will be put in front of each property
3606: * name
3607: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
3608: * have access to the request data (eg. you're inside a child trigger); or
3609: * if there's no active element context (eg. you're using this method
3610: * inside the constructor instead of inside the {@link #initialize()}
3611: * method)
3612: * @see #setNamedOutputBean(String, Object)
3613: * @see #setOutputBean(Object)
3614: * @see #setOutput(String, String)
3615: * @see #setOutput(String, String[])
3616: * @see #addOutputValue(String, String)
3617: * @see #addOutputValues(String, String[])
3618: * @see #clearOutput(String)
3619: * @see #clearNamedOutputBean(String)
3620: * @see #clearOutputBean(Class)
3621: * @see #clearOutputBean(Class, String)
3622: * @see #getOutput(String)
3623: * @since 1.0
3624: */
3625: public void setOutputBean(Object bean, String prefix)
3626: throws EngineException {
3627: if (!mRequestAccessEnabled)
3628: throw new RequestAccessDeniedException();
3629: if (null == mElementContext)
3630: throw new ElementContextMissingException();
3631:
3632: if (null == bean)
3633: throw new IllegalArgumentException("bean can't be null.");
3634:
3635: mElementContext.setOutputBean(bean, prefix);
3636: }
3637:
3638: /**
3639: * Clears the output value of an output.
3640: *
3641: * @param name the name of the output
3642: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3643: * is known with this name; if no output is known with this name; or if
3644: * you don't have access to the request data (eg. you're inside a child
3645: * trigger); or if there's no active element context (eg. you're using
3646: * this method inside the constructor instead of inside the {@link
3647: * #initialize()} method)
3648: * @see #setNamedOutputBean(String, Object)
3649: * @see #setOutputBean(Object)
3650: * @see #setOutputBean(Object, String)
3651: * @see #setOutput(String, String)
3652: * @see #setOutput(String, String[])
3653: * @see #addOutputValue(String, String)
3654: * @see #addOutputValues(String, String[])
3655: * @see #clearNamedOutputBean(String)
3656: * @see #clearOutputBean(Class)
3657: * @see #clearOutputBean(Class, String)
3658: * @see #getOutput(String)
3659: * @since 1.0
3660: */
3661: public void clearOutput(String name) throws EngineException {
3662: if (!mRequestAccessEnabled)
3663: throw new RequestAccessDeniedException();
3664: if (null == mElementContext)
3665: throw new ElementContextMissingException();
3666:
3667: if (null == name)
3668: throw new IllegalArgumentException("name can't be null.");
3669: if (0 == name.length())
3670: throw new IllegalArgumentException("name can't be empty.");
3671:
3672: mElementContext.clearOutput(name);
3673: }
3674:
3675: /**
3676: * Clears the outputs that correspond to the properties of a named output
3677: * bean. The class of the bean is looked up through its name, as is the
3678: * property prefix.
3679: *
3680: * @param name the name of the output bean
3681: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3682: * bean is known with this name; or if you don't have access to the
3683: * request data (eg. you're inside a child trigger); or if there's no
3684: * active element context (eg. you're using this method inside the
3685: * constructor instead of inside the {@link #initialize()} method)
3686: * @see #setNamedOutputBean(String, Object)
3687: * @see #setOutputBean(Object)
3688: * @see #setOutputBean(Object, String)
3689: * @see #setOutput(String, String)
3690: * @see #setOutput(String, String[])
3691: * @see #addOutputValue(String, String)
3692: * @see #addOutputValues(String, String[])
3693: * @see #clearOutput(String)
3694: * @see #clearOutputBean(Class)
3695: * @see #clearOutputBean(Class, String)
3696: * @see #getOutput(String)
3697: * @since 1.0
3698: */
3699: public void clearNamedOutputBean(String name)
3700: throws EngineException {
3701: if (!mRequestAccessEnabled)
3702: throw new RequestAccessDeniedException();
3703: if (null == mElementContext)
3704: throw new ElementContextMissingException();
3705:
3706: if (null == name)
3707: throw new IllegalArgumentException("name can't be null.");
3708: if (0 == name.length())
3709: throw new IllegalArgumentException("name can't be empty.");
3710:
3711: mElementContext.clearNamedOutputBean(name);
3712: }
3713:
3714: /**
3715: * Clears the outputs that correspond to the properties of an output bean.
3716: *
3717: * @param beanClass the class of the output bean
3718: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3719: * bean is known with this name; if you don't have access to the request
3720: * data (eg. you're inside a child trigger); or if there's no active
3721: * element context (eg. you're using this method inside the constructor
3722: * instead of inside the {@link #initialize()} method)
3723: * @see #setNamedOutputBean(String, Object)
3724: * @see #setOutputBean(Object)
3725: * @see #setOutputBean(Object, String)
3726: * @see #setOutput(String, String)
3727: * @see #setOutput(String, String[])
3728: * @see #addOutputValue(String, String)
3729: * @see #addOutputValues(String, String[])
3730: * @see #clearOutput(String)
3731: * @see #clearNamedOutputBean(String)
3732: * @see #clearOutputBean(Class, String)
3733: * @see #getOutput(String)
3734: * @since 1.0
3735: */
3736: public void clearOutputBean(Class beanClass) throws EngineException {
3737: clearOutputBean(beanClass, null);
3738: }
3739:
3740: /**
3741: * Clears the outputs that correspond to the properties of an output bean,
3742: * taking the provided prefix into account.
3743: *
3744: * @param beanClass the class of the output bean
3745: * @param prefix the prefix that will be put in front of each property
3746: * name
3747: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
3748: * have access to the request data (eg. you're inside a child trigger); or
3749: * if there's no active element context (eg. you're using this method
3750: * inside the constructor instead of inside the {@link #initialize()}
3751: * method)
3752: * @see #setNamedOutputBean(String, Object)
3753: * @see #setOutputBean(Object)
3754: * @see #setOutputBean(Object, String)
3755: * @see #setOutput(String, String)
3756: * @see #setOutput(String, String[])
3757: * @see #addOutputValue(String, String)
3758: * @see #addOutputValues(String, String[])
3759: * @see #clearOutput(String)
3760: * @see #clearNamedOutputBean(String)
3761: * @see #clearOutputBean(Class)
3762: * @see #getOutput(String)
3763: * @since 1.0
3764: */
3765: public void clearOutputBean(Class beanClass, String prefix)
3766: throws EngineException {
3767: if (!mRequestAccessEnabled)
3768: throw new RequestAccessDeniedException();
3769: if (null == mElementContext)
3770: throw new ElementContextMissingException();
3771:
3772: if (null == beanClass)
3773: throw new IllegalArgumentException(
3774: "beanClass can't be null.");
3775:
3776: mElementContext.clearOutputBean(beanClass, prefix);
3777: }
3778:
3779: /**
3780: * Retrieves the value of the ouput.
3781: *
3782: * @param name the name of the output
3783: * @return the textual value of the output as it's used by framework; or
3784: * {@code null} if the output couldn't be found.
3785: * @exception com.uwyn.rife.engine.exceptions.EngineException if no output
3786: * is known with this name; if you don't have access to the request data
3787: * (eg. you're inside a child trigger); or if there's no active element
3788: * context (eg. you're using this method inside the constructor instead of
3789: * inside the {@link #initialize()} method)
3790: * @see #setNamedOutputBean(String, Object)
3791: * @see #setOutputBean(Object)
3792: * @see #setOutputBean(Object, String)
3793: * @see #setOutput(String, String)
3794: * @see #setOutput(String, String[])
3795: * @see #addOutputValue(String, String)
3796: * @see #addOutputValues(String, String[])
3797: * @see #clearOutput(String)
3798: * @see #clearNamedOutputBean(String)
3799: * @see #clearOutputBean(Class)
3800: * @see #clearOutputBean(Class, String)
3801: * @since 1.6
3802: */
3803: public String[] getOutput(String name) throws EngineException {
3804: if (!mRequestAccessEnabled)
3805: throw new RequestAccessDeniedException();
3806: if (null == mElementContext)
3807: throw new ElementContextMissingException();
3808:
3809: if (null == name)
3810: throw new IllegalArgumentException("name can't be null.");
3811: if (0 == name.length())
3812: throw new IllegalArgumentException("name can't be empty.");
3813:
3814: return mElementContext.getOutput(name);
3815: }
3816:
3817: /**
3818: * Checks whether a cookie is present.
3819: *
3820: * @param name the name of the cookie
3821: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
3822: * incookie is known with this name; if you don't have access to the
3823: * request data (eg. you're inside a child trigger); or if there's no
3824: * active element context (eg. you're using this method inside the
3825: * constructor instead of inside the {@link #initialize()} method)
3826: * @return <code>true</code> if the cookie was present; or
3827: * <p><code>false</code> otherwise
3828: * @see #getCookie(String)
3829: * @see #getCookieValue(String)
3830: * @see #getCookieValue(String, String)
3831: * @see #getCookieValues()
3832: * @see #setCookie(Cookie)
3833: * @since 1.0
3834: */
3835: public boolean hasCookie(String name) throws EngineException {
3836: if (!mRequestAccessEnabled)
3837: throw new RequestAccessDeniedException();
3838: if (null == mElementContext)
3839: throw new ElementContextMissingException();
3840:
3841: if (null == name)
3842: throw new IllegalArgumentException("name can't be null.");
3843: if (0 == name.length())
3844: throw new IllegalArgumentException("name can't be empty.");
3845:
3846: return mElementContext.hasCookie(name);
3847: }
3848:
3849: /**
3850: * Retrieves a cookie.
3851: *
3852: * @param name the name of the cookie.
3853: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
3854: * incookie is known with this name; if you don't have access to the
3855: * request data (eg. you're inside a child trigger); or if there's no
3856: * active element context (eg. you're using this method inside the
3857: * constructor instead of inside the {@link #initialize()} method)
3858: * @return the instance of the cookie; or
3859: * <p><code>null</code> if no such cookie is present
3860: * @see #hasCookie(String)
3861: * @see #getCookieValue(String)
3862: * @see #getCookieValue(String, String)
3863: * @see #getCookieValues()
3864: * @see #setCookie(Cookie)
3865: * @since 1.0
3866: */
3867: public Cookie getCookie(String name) throws EngineException {
3868: if (!mRequestAccessEnabled)
3869: throw new RequestAccessDeniedException();
3870: if (null == mElementContext)
3871: throw new ElementContextMissingException();
3872:
3873: if (null == name)
3874: throw new IllegalArgumentException("name can't be null.");
3875: if (0 == name.length())
3876: throw new IllegalArgumentException("name can't be empty.");
3877:
3878: return mElementContext.getCookie(name);
3879: }
3880:
3881: /**
3882: * Retrieves the value of a cookie.
3883: *
3884: * @param name the name of the cookie
3885: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
3886: * incookie is known with this name; if you don't have access to the
3887: * request data (eg. you're inside a child trigger); or if there's no
3888: * active element context (eg. you're using this method inside the
3889: * constructor instead of inside the {@link #initialize()} method)
3890: * @return the value of the cookie; or
3891: * <p><code>null</code> if no such cookie is present
3892: * @see #hasCookie(String)
3893: * @see #getCookie(String)
3894: * @see #getCookieValue(String, String)
3895: * @see #getCookieValues()
3896: * @see #setCookie(Cookie)
3897: * @since 1.0
3898: */
3899: public String getCookieValue(String name) throws EngineException {
3900: if (!mRequestAccessEnabled)
3901: throw new RequestAccessDeniedException();
3902: if (null == mElementContext)
3903: throw new ElementContextMissingException();
3904:
3905: if (null == name)
3906: throw new IllegalArgumentException("name can't be null.");
3907: if (0 == name.length())
3908: throw new IllegalArgumentException("name can't be empty.");
3909:
3910: return mElementContext.getCookieValue(name);
3911: }
3912:
3913: /**
3914: * Retrieves all current cookies names with their values.
3915: *
3916: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
3917: * have access to the request data (eg. you're inside a child trigger); or
3918: * if there's no active element context (eg. you're using this method
3919: * inside the constructor instead of inside the {@link #initialize()}
3920: * method)
3921: * @return a new map of all the current cookies names with their values
3922: * @see #hasCookie(String)
3923: * @see #getCookie(String)
3924: * @see #getCookieValue(String)
3925: * @see #getCookieValue(String, String)
3926: * @see #setCookie(Cookie)
3927: * @since 1.0
3928: */
3929: public Map<String, String> getCookieValues() throws EngineException {
3930: if (!mRequestAccessEnabled)
3931: throw new RequestAccessDeniedException();
3932: if (null == mElementContext)
3933: throw new ElementContextMissingException();
3934:
3935: return mElementContext.getCookieValues();
3936: }
3937:
3938: /**
3939: * Retrieves the value of a named cookie, using a default value as
3940: * fallback.
3941: *
3942: * @param name the name of the cookie
3943: * @param defaultValue the default value that will be used when no cookie
3944: * value is present
3945: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
3946: * incookie is known with this name; if you don't have access to the
3947: * request data (eg. you're inside a child trigger); or if there's no
3948: * active element context (eg. you're using this method inside the
3949: * constructor instead of inside the {@link #initialize()} method)
3950: * @return the cookie value; or
3951: * <p>the default value if no cookie value is present
3952: * @see #hasCookie(String)
3953: * @see #getCookie(String)
3954: * @see #getCookieValue(String)
3955: * @see #getCookieValue(String, String)
3956: * @see #getCookieValues()
3957: * @see #setCookie(Cookie)
3958: * @since 1.0
3959: */
3960: public String getCookieValue(String name, String defaultValue)
3961: throws EngineException {
3962: String value = getCookieValue(name);
3963: if (value == null) {
3964: return defaultValue;
3965: }
3966: return value;
3967: }
3968:
3969: /**
3970: * Retrieves the value of a named cookie and converts it to a boolean.
3971: *
3972: * @param name the name of the cookie
3973: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
3974: * incookie is known with this name; if you don't have access to the
3975: * request data (eg. you're inside a child trigger); or if there's no
3976: * active element context (eg. you're using this method inside the
3977: * constructor instead of inside the {@link #initialize()} method)
3978: * @return the converted cookie value; or
3979: * <p><code>false</code> if no cookie value is present or if the cookie
3980: * value is not a valid boolean
3981: * @see #hasCookie(String)
3982: * @see #getCookie(String)
3983: * @see #getCookieValue(String)
3984: * @see #getCookieValue(String, String)
3985: * @see #getCookieValues()
3986: * @see #setCookie(Cookie)
3987: * @since 1.0
3988: */
3989: public boolean getCookieValueBoolean(String name)
3990: throws EngineException {
3991: return getCookieValueBoolean(name, ElementInfo.DEFAULT_BOOLEAN);
3992: }
3993:
3994: /**
3995: * Retrieves the value of a named cookie and converts it to a boolean,
3996: * using a default value if no input value is present.
3997: *
3998: * @param name the name of the cookie
3999: * @param defaultValue the default value that will be used when no cookie
4000: * value is present
4001: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
4002: * incookie is known with this name; if you don't have access to the
4003: * request data (eg. you're inside a child trigger); or if there's no
4004: * active element context (eg. you're using this method inside the
4005: * constructor instead of inside the {@link #initialize()} method)
4006: * @return the converted cookie value; or
4007: * <p>the default value if no cookie value is present
4008: * @see #hasCookie(String)
4009: * @see #getCookie(String)
4010: * @see #getCookieValue(String)
4011: * @see #getCookieValue(String, String)
4012: * @see #getCookieValues()
4013: * @see #setCookie(Cookie)
4014: * @since 1.0
4015: */
4016: public boolean getCookieValueBoolean(String name,
4017: boolean defaultValue) throws EngineException {
4018: String value = getCookieValue(name);
4019: if (value == null) {
4020: return defaultValue;
4021: }
4022:
4023: return StringUtils.convertToBoolean(value);
4024: }
4025:
4026: /**
4027: * Retrieves the value of a named cookie and converts it to an integer.
4028: *
4029: * @param name the name of the cookie
4030: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
4031: * incookie is known with this name; if you don't have access to the
4032: * request data (eg. you're inside a child trigger); or if there's no
4033: * active element context (eg. you're using this method inside the
4034: * constructor instead of inside the {@link #initialize()} method)
4035: * @return the converted cookie value; or
4036: * <p><code>0</code> if no cookie value is present or if the cookie value
4037: * is not a valid integer
4038: * @see #hasCookie(String)
4039: * @see #getCookie(String)
4040: * @see #getCookieValue(String)
4041: * @see #getCookieValue(String, String)
4042: * @see #getCookieValues()
4043: * @see #setCookie(Cookie)
4044: * @since 1.0
4045: */
4046: public int getCookieValueInt(String name) throws EngineException {
4047: return getCookieValueInt(name, ElementInfo.DEFAULT_INTEGER);
4048: }
4049:
4050: /**
4051: * Retrieves the value of a named cookie and converts it to an integer,
4052: * using a default value if no input value is present.
4053: *
4054: * @param name the name of the cookie
4055: * @param defaultValue the default value that will be used when no cookie
4056: * value is present
4057: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
4058: * incookie is known with this name; if you don't have access to the
4059: * request data (eg. you're inside a child trigger); or if there's no
4060: * active element context (eg. you're using this method inside the
4061: * constructor instead of inside the {@link #initialize()} method)
4062: * @return the converted cookie value; or
4063: * <p>the default value if no cookie value is present
4064: * @see #hasCookie(String)
4065: * @see #getCookie(String)
4066: * @see #getCookieValue(String)
4067: * @see #getCookieValue(String, String)
4068: * @see #getCookieValues()
4069: * @see #setCookie(Cookie)
4070: * @since 1.0
4071: */
4072: public int getCookieValueInt(String name, int defaultValue)
4073: throws EngineException {
4074: String value = getCookieValue(name);
4075: if (value == null) {
4076: return defaultValue;
4077: }
4078: try {
4079: return Integer.parseInt(value);
4080: } catch (NumberFormatException e) {
4081: return defaultValue;
4082: }
4083: }
4084:
4085: /**
4086: * Retrieves the value of a named cookie and converts it to a long.
4087: *
4088: * @param name the name of the cookie
4089: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
4090: * incookie is known with this name; if you don't have access to the
4091: * request data (eg. you're inside a child trigger); or if there's no
4092: * active element context (eg. you're using this method inside the
4093: * constructor instead of inside the {@link #initialize()} method)
4094: * @return the converted cookie value; or
4095: * <p><code>0L</code> if no cookie value is present or if the cookie value
4096: * is not a valid long
4097: * @see #hasCookie(String)
4098: * @see #getCookie(String)
4099: * @see #getCookieValue(String)
4100: * @see #getCookieValue(String, String)
4101: * @see #getCookieValues()
4102: * @see #setCookie(Cookie)
4103: * @since 1.0
4104: */
4105: public long getCookieValueLong(String name) throws EngineException {
4106: return getCookieValueLong(name, ElementInfo.DEFAULT_LONG);
4107: }
4108:
4109: /**
4110: * Retrieves the value of a named cookie and converts it to a long, using
4111: * a default value if no input value is present.
4112: *
4113: * @param name the name of the cookie
4114: * @param defaultValue the default value that will be used when no cookie
4115: * value is present
4116: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
4117: * incookie is known with this name; if you don't have access to the
4118: * request data (eg. you're inside a child trigger); or if there's no
4119: * active element context (eg. you're using this method inside the
4120: * constructor instead of inside the {@link #initialize()} method)
4121: * @return the converted cookie value; or
4122: * <p>the default value if no cookie value is present
4123: * @see #hasCookie(String)
4124: * @see #getCookie(String)
4125: * @see #getCookieValue(String)
4126: * @see #getCookieValue(String, String)
4127: * @see #getCookieValues()
4128: * @see #setCookie(Cookie)
4129: * @since 1.0
4130: */
4131: public long getCookieValueLong(String name, long defaultValue)
4132: throws EngineException {
4133: String value = getCookieValue(name);
4134: if (value == null) {
4135: return defaultValue;
4136: }
4137: try {
4138: return Long.parseLong(value);
4139: } catch (NumberFormatException e) {
4140: return defaultValue;
4141: }
4142: }
4143:
4144: /**
4145: * Retrieves the value of a named cookie and converts it to a double.
4146: *
4147: * @param name the name of the cookie
4148: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
4149: * incookie is known with this name; if you don't have access to the
4150: * request data (eg. you're inside a child trigger); or if there's no
4151: * active element context (eg. you're using this method inside the
4152: * constructor instead of inside the {@link #initialize()} method)
4153: * @return the converted cookie value; or
4154: * <p><code>0.0d</code> if no cookie value is present or if the cookie
4155: * value is not a valid double
4156: * @see #hasCookie(String)
4157: * @see #getCookie(String)
4158: * @see #getCookieValue(String)
4159: * @see #getCookieValue(String, String)
4160: * @see #getCookieValues()
4161: * @see #setCookie(Cookie)
4162: * @since 1.0
4163: */
4164: public double getCookieValueDouble(String name)
4165: throws EngineException {
4166: return getCookieValueDouble(name, ElementInfo.DEFAULT_DOUBLE);
4167: }
4168:
4169: /**
4170: * Retrieves the value of a named cookie and converts it to a double,
4171: * using a default value if no input value is present.
4172: *
4173: * @param name the name of the cookie
4174: * @param defaultValue the default value that will be used when no cookie
4175: * value is present
4176: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
4177: * incookie is known with this name; if you don't have access to the
4178: * request data (eg. you're inside a child trigger); or if there's no
4179: * active element context (eg. you're using this method inside the
4180: * constructor instead of inside the {@link #initialize()} method)
4181: * @return the converted cookie value; or
4182: * <p>the default value if no cookie value is present
4183: * @see #hasCookie(String)
4184: * @see #getCookie(String)
4185: * @see #getCookieValue(String)
4186: * @see #getCookieValue(String, String)
4187: * @see #getCookieValues()
4188: * @see #setCookie(Cookie)
4189: * @since 1.0
4190: */
4191: public double getCookieValueDouble(String name, double defaultValue)
4192: throws EngineException {
4193: String value = getCookieValue(name);
4194: if (value == null) {
4195: return defaultValue;
4196: }
4197: try {
4198: return Double.parseDouble(value);
4199: } catch (NumberFormatException e) {
4200: return defaultValue;
4201: }
4202: }
4203:
4204: /**
4205: * Retrieves the value of a named cookie and converts it to a float.
4206: *
4207: * @param name the name of the cookie
4208: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
4209: * incookie is known with this name; if you don't have access to the
4210: * request data (eg. you're inside a child trigger); or if there's no
4211: * active element context (eg. you're using this method inside the
4212: * constructor instead of inside the {@link #initialize()} method)
4213: * @return the converted cookie value; or
4214: * <p><code>0.0</code>f if no cookie value is present or if the cookie
4215: * value is not a valid float
4216: * @see #hasCookie(String)
4217: * @see #getCookie(String)
4218: * @see #getCookieValue(String)
4219: * @see #getCookieValue(String, String)
4220: * @see #getCookieValues()
4221: * @see #setCookie(Cookie)
4222: * @since 1.0
4223: */
4224: public float getCookieValueFloat(String name)
4225: throws EngineException {
4226: return getCookieValueFloat(name, ElementInfo.DEFAULT_FLOAT);
4227: }
4228:
4229: /**
4230: * Retrieves the value of a named cookie and converts it to a float, using
4231: * a default value if no input value is present.
4232: *
4233: * @param name the name of the cookie
4234: * @param defaultValue the default value that will be used when no cookie
4235: * value is present
4236: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
4237: * incookie is known with this name; if you don't have access to the
4238: * request data (eg. you're inside a child trigger); or if there's no
4239: * active element context (eg. you're using this method inside the
4240: * constructor instead of inside the {@link #initialize()} method)
4241: * @return the converted cookie value; or
4242: * <p>the default value if no cookie value is present
4243: * @see #hasCookie(String)
4244: * @see #getCookie(String)
4245: * @see #getCookieValue(String)
4246: * @see #getCookieValue(String, String)
4247: * @see #getCookieValues()
4248: * @see #setCookie(Cookie)
4249: * @since 1.0
4250: */
4251: public float getCookieValueFloat(String name, float defaultValue)
4252: throws EngineException {
4253: String value = getCookieValue(name);
4254: if (value == null) {
4255: return defaultValue;
4256: }
4257: try {
4258: return Float.parseFloat(value);
4259: } catch (NumberFormatException e) {
4260: return defaultValue;
4261: }
4262: }
4263:
4264: /**
4265: * Sets a cookie which will be sent to the browser.
4266: * <p>Cookies are handles outside of the web engine's data flow
4267: * management. They are preserved by the browser and are automatically
4268: * provided at each request.
4269: *
4270: * @param cookie the cookie instance that will be set
4271: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
4272: * outcookie is known with this name; if you don't have access to the
4273: * request data (eg. you're inside a child trigger); or if there's no
4274: * active element context (eg. you're using this method inside the
4275: * constructor instead of inside the {@link #initialize()} method)
4276: * @see #hasCookie(String)
4277: * @see #getCookie(String)
4278: * @see #getCookieValue(String)
4279: * @see #getCookieValue(String, String)
4280: * @see #getCookieValues()
4281: * @see #setCookie(Cookie)
4282: * @since 1.0
4283: */
4284: public void setCookie(Cookie cookie) throws EngineException {
4285: if (!mRequestAccessEnabled)
4286: throw new RequestAccessDeniedException();
4287: if (null == mElementContext)
4288: throw new ElementContextMissingException();
4289:
4290: if (null == cookie)
4291: throw new IllegalArgumentException("cookie can't be null.");
4292: if (null == cookie.getName())
4293: throw new IllegalArgumentException(
4294: "cookie name can't be empty.");
4295:
4296: mElementContext.setCookie(cookie);
4297: }
4298:
4299: /**
4300: * Returns the unique identifier of the current continuation.
4301: *
4302: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
4303: * have access to the request data (eg. you're inside a child trigger)
4304: * @return the unique identifier of the current continuations; or
4305: * <p><code>null</code> if no continuation is active
4306: * @since 1.0
4307: */
4308: public String getContinuationId() throws EngineException {
4309: if (!mRequestAccessEnabled)
4310: throw new RequestAccessDeniedException();
4311:
4312: return ContinuationContext.getActiveContextId();
4313: }
4314:
4315: /**
4316: * Generates a query URL for an exit.
4317: *
4318: * @param name the name of the exit
4319: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4320: * is known with this name; if the exit hasn't got a destination element;
4321: * if you don't have access to the request data (eg. you're inside a child
4322: * trigger); or if there's no active element context (eg. you're using
4323: * this method inside the constructor instead of inside the {@link
4324: * #initialize()} method)
4325: * @return the generated URL as a character sequence
4326: * @see #getExitQueryUrl(String, String, String[])
4327: * @see #getExitFormUrl(String, String)
4328: * @see #getExitFormParameters(String, String[])
4329: * @see #setExitQuery(Template, String, String, String[])
4330: * @see #setExitForm(Template, String, String)
4331: * @since 1.0
4332: */
4333: public CharSequence getExitQueryUrl(String name)
4334: throws EngineException {
4335: return getExitQueryUrl(name, null, null);
4336: }
4337:
4338: /**
4339: * Generates a query URL for an exit and appends a pathinfo to the URL of
4340: * the destination element.
4341: *
4342: * @param name the name of the exit
4343: * @param pathinfo the pathinfo that will be appended; or
4344: * <code>null</code> if no pathinfo should be appended
4345: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4346: * is known with this name; if the exit hasn't got a destination element;
4347: * if you don't have access to the request data (eg. you're inside a child
4348: * trigger); or if there's no active element context (eg. you're using
4349: * this method inside the constructor instead of inside the {@link
4350: * #initialize()} method)
4351: * @return the generated URL as a character sequence
4352: * @see #getExitQueryUrl(String, String, String[])
4353: * @see #getExitFormUrl(String, String)
4354: * @see #getExitFormParameters(String, String[])
4355: * @see #setExitQuery(Template, String, String, String[])
4356: * @see #setExitForm(Template, String, String)
4357: * @since 1.0
4358: */
4359: public CharSequence getExitQueryUrl(String name, String pathinfo)
4360: throws EngineException {
4361: return getExitQueryUrl(name, pathinfo, null);
4362: }
4363:
4364: /**
4365: * Generates a query URL for an exit and overrides the current output
4366: * values only for this method.
4367: *
4368: * @param name the name of the exit
4369: * @param outputValues an array of string pairs that will be used to
4370: * override the current output values; or <code>null</code> if no output
4371: * values should be overridden
4372: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4373: * is known with this name; if the exit hasn't got a destination element;
4374: * if you don't have access to the request data (eg. you're inside a child
4375: * trigger); or if there's no active element context (eg. you're using
4376: * this method inside the constructor instead of inside the {@link
4377: * #initialize()} method)
4378: * @return the generated URL as a character sequence
4379: * @see #getExitQueryUrl(String, String, String[])
4380: * @see #getExitFormUrl(String, String)
4381: * @see #getExitFormParameters(String, String[])
4382: * @see #setExitQuery(Template, String, String, String[])
4383: * @see #setExitForm(Template, String, String)
4384: * @since 1.0
4385: */
4386: public CharSequence getExitQueryUrl(String name,
4387: String[] outputValues) throws EngineException {
4388: return getExitQueryUrl(name, null, outputValues);
4389: }
4390:
4391: /**
4392: * Generates a query URL for an exit and appends a pathinfo to the URL of
4393: * the destination element. The current output values can be overridden
4394: * for this method alone.
4395: * <p>This will take the current element context into account with the
4396: * available outputs, global variables, ... and generate an URL that
4397: * persists the data state according to the declared site structure.
4398: * <p>The output values are provided as an array of strings that should be
4399: * structured in pairs. For example, if these output values should be
4400: * used: <code>output1</code>:<code>value1</code> and <code>output2</code>:<code>value2</code>,
4401: * you should define the following string array:
4402: * <pre>new String[] {"output1", "value1", "output2", "value2"}</pre>
4403: * <p>The generated URL with not contain a scheme, host or port. It will
4404: * begin with the path part and be absolute, starting with the web
4405: * application's root URL.
4406: *
4407: * @param name the name of the exit
4408: * @param pathinfo the pathinfo that will be appended; or
4409: * <code>null</code> if no pathinfo should be appended
4410: * @param outputValues an array of string pairs that will be used to
4411: * override the current output values; or <code>null</code> if no output
4412: * values should be overridden
4413: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4414: * is known with this name; if the exit hasn't got a destination element;
4415: * if you don't have access to the request data (eg. you're inside a child
4416: * trigger); or if there's no active element context (eg. you're using
4417: * this method inside the constructor instead of inside the {@link
4418: * #initialize()} method)
4419: * @return the generated URL as a character sequence
4420: * @see #getExitFormUrl(String, String)
4421: * @see #getExitFormParameters(String, String[])
4422: * @see #setExitQuery(Template, String, String, String[])
4423: * @see #setExitForm(Template, String, String)
4424: * @since 1.0
4425: */
4426: public CharSequence getExitQueryUrl(String name, String pathinfo,
4427: String[] outputValues) throws EngineException {
4428: if (!mRequestAccessEnabled)
4429: throw new RequestAccessDeniedException();
4430: if (null == mElementContext)
4431: throw new ElementContextMissingException();
4432:
4433: if (null == name)
4434: throw new IllegalArgumentException("name can't be null.");
4435: if (0 == name.length())
4436: throw new IllegalArgumentException("name can't be empty.");
4437: if (null != outputValues && outputValues.length % 2 > 0)
4438: throw new IllegalArgumentException(
4439: "outputValues should be a series of key/value pairs.");
4440:
4441: return mElementContext.getExitQueryUrl(name, pathinfo,
4442: outputValues);
4443: }
4444:
4445: /**
4446: * Generates a form action URL for an exit.
4447: *
4448: * @param name the name of the exit
4449: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4450: * is known with this name; if the exit hasn't got a destination element;
4451: * if you don't have access to the request data (eg. you're inside a child
4452: * trigger); or if there's no active element context (eg. you're using
4453: * this method inside the constructor instead of inside the {@link
4454: * #initialize()} method)
4455: * @return the generated URL as a character sequence
4456: * @see #getExitQueryUrl(String, String, String[])
4457: * @see #getExitFormUrl(String, String)
4458: * @see #getExitFormParameters(String, String[])
4459: * @see #setExitQuery(Template, String, String, String[])
4460: * @see #setExitForm(Template, String, String)
4461: * @since 1.0
4462: */
4463: public CharSequence getExitFormUrl(String name)
4464: throws EngineException {
4465: return getExitFormUrl(name, null);
4466: }
4467:
4468: /**
4469: * Generates a form action URL for an exit and appends a pathinfo to the
4470: * URL of the destination element.
4471: * <p>This will take the current element context into account with the
4472: * available outputs, global variables, ... and generate an URL that
4473: * persists the data state according to the declared site structure.
4474: * <p>The generated URL with not contain a scheme, host or port. It will
4475: * begin with the path part and be absolute, starting with the web
4476: * application's root URL.
4477: * <p>This method goes together with the {@link
4478: * #getExitFormParameters(String, String[])} method since the state is
4479: * tranferred as hidden form parameters that are part of the form.
4480: *
4481: * @param name the name of the exit
4482: * @param pathinfo the pathinfo that will be appended; or
4483: * <code>null</code> if no pathinfo should be appended
4484: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4485: * is known with this name; if the exit hasn't got a destination element;
4486: * if you don't have access to the request data (eg. you're inside a child
4487: * trigger); or if there's no active element context (eg. you're using
4488: * this method inside the constructor instead of inside the {@link
4489: * #initialize()} method)
4490: * @return the generated URL as a character sequence
4491: * @see #getExitQueryUrl(String, String, String[])
4492: * @see #getExitFormParameters(String, String[])
4493: * @see #setExitQuery(Template, String, String, String[])
4494: * @see #setExitForm(Template, String, String)
4495: * @since 1.0
4496: */
4497: public CharSequence getExitFormUrl(String name, String pathinfo)
4498: throws EngineException {
4499: if (!mRequestAccessEnabled)
4500: throw new RequestAccessDeniedException();
4501: if (null == mElementContext)
4502: throw new ElementContextMissingException();
4503:
4504: if (null == name)
4505: throw new IllegalArgumentException("name can't be null.");
4506: if (0 == name.length())
4507: throw new IllegalArgumentException("name can't be empty.");
4508:
4509: return mElementContext.getExitFormUrl(name, pathinfo);
4510: }
4511:
4512: /**
4513: * Generates the XHTML hidden form parameters for an exit.
4514: *
4515: * @param name the name of the exit
4516: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4517: * is known with this name; if the exit hasn't got a destination element;
4518: * if you don't have access to the request data (eg. you're inside a child
4519: * trigger); or if there's no active element context (eg. you're using
4520: * this method inside the constructor instead of inside the {@link
4521: * #initialize()} method)
4522: * @return the generated parameters as a character sequence
4523: * @see #getExitQueryUrl(String, String, String[])
4524: * @see #getExitFormUrl(String, String)
4525: * @see #getExitFormParameters(String, String[])
4526: * @see #setExitQuery(Template, String, String, String[])
4527: * @see #setExitForm(Template, String, String)
4528: * @since 1.0
4529: */
4530: public CharSequence getExitFormParameters(String name)
4531: throws EngineException {
4532: return getExitFormParameters(name, null);
4533: }
4534:
4535: /**
4536: * Generates the hidden XHTML form parameters for an exit and overrides
4537: * the current output values only for this method.
4538: * <p>This will take the current element context into account with the
4539: * available outputs, global variables, ... and generate hidden XHTML form
4540: * parameters that persist the data state according to the declared site
4541: * structure.
4542: * <p>The output values are provided as an array of strings that should be
4543: * structured in pairs. For example, if these output values should be
4544: * used: <code>output1</code>:<code>value1</code> and <code>output2</code>:<code>value2</code>,
4545: * you should define the following string array:
4546: * <pre>new String[] {"output1", "value1", "output2", "value2"}</pre>
4547: * <p>This method goes together with the {@link
4548: * #getExitFormUrl(String, String)} method since the URL needs to be
4549: * provided in the action attribute of the form.
4550: *
4551: * @param name the name of the exit
4552: * @param outputValues an array of string pairs that will be used to
4553: * override the current output values; or <code>null</code> if no output
4554: * values should be overridden
4555: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4556: * is known with this name; if the exit hasn't got a destination element;
4557: * if you don't have access to the request data (eg. you're inside a child
4558: * trigger); or if there's no active element context (eg. you're using
4559: * this method inside the constructor instead of inside the {@link
4560: * #initialize()} method)
4561: * @return the generated parameters as a character sequence
4562: * @see #getExitQueryUrl(String, String, String[])
4563: * @see #getExitFormUrl(String, String)
4564: * @see #getExitFormParametersJavascript(String, String[])
4565: * @see #setExitQuery(Template, String, String, String[])
4566: * @see #setExitForm(Template, String, String)
4567: * @since 1.0
4568: */
4569: public CharSequence getExitFormParameters(String name,
4570: String[] outputValues) throws EngineException {
4571: if (!mRequestAccessEnabled)
4572: throw new RequestAccessDeniedException();
4573: if (null == mElementContext)
4574: throw new ElementContextMissingException();
4575:
4576: if (null == name)
4577: throw new IllegalArgumentException("name can't be null.");
4578: if (0 == name.length())
4579: throw new IllegalArgumentException("name can't be empty.");
4580: if (null != outputValues && outputValues.length % 2 > 0)
4581: throw new IllegalArgumentException(
4582: "outputValues should be a series of key/value pairs.");
4583:
4584: return mElementContext
4585: .getExitFormParameters(name, outputValues);
4586: }
4587:
4588: /**
4589: * Generates Javascript that will generate hidden XHTML form parameters for
4590: * an exit and overrides the current output values only for this method.
4591: * <p>This will take the current element context into account with the
4592: * available outputs, global variables, ... and generate hidden XHTML form
4593: * parameters that persist the data state according to the declared site
4594: * structure.
4595: * <p>The output values are provided as an array of strings that should be
4596: * structured in pairs. For example, if these output values should be
4597: * used: <code>output1</code>:<code>value1</code> and <code>output2</code>:<code>value2</code>,
4598: * you should define the following string array:
4599: * <pre>new String[] {"output1", "value1", "output2", "value2"}</pre>
4600: * <p>This method goes together with the {@link
4601: * #getExitFormUrl(String, String)} method since the URL needs to be
4602: * provided in the action attribute of the form.
4603: *
4604: * @param name the name of the exit
4605: * @param outputValues an array of string pairs that will be used to
4606: * override the current output values; or <code>null</code> if no output
4607: * values should be overridden
4608: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4609: * is known with this name; if the exit hasn't got a destination element;
4610: * if you don't have access to the request data (eg. you're inside a child
4611: * trigger); or if there's no active element context (eg. you're using
4612: * this method inside the constructor instead of inside the {@link
4613: * #initialize()} method)
4614: * @return the generated parameters as a character sequence
4615: * @see #getExitQueryUrl(String, String, String[])
4616: * @see #getExitFormUrl(String, String)
4617: * @see #getExitFormParameters(String, String[])
4618: * @see #setExitQuery(Template, String, String, String[])
4619: * @see #setExitForm(Template, String, String)
4620: * @since 1.6
4621: */
4622: public CharSequence getExitFormParametersJavascript(String name,
4623: String[] outputValues) throws EngineException {
4624: if (!mRequestAccessEnabled)
4625: throw new RequestAccessDeniedException();
4626: if (null == mElementContext)
4627: throw new ElementContextMissingException();
4628:
4629: if (null == name)
4630: throw new IllegalArgumentException("name can't be null.");
4631: if (0 == name.length())
4632: throw new IllegalArgumentException("name can't be empty.");
4633: if (null != outputValues && outputValues.length % 2 > 0)
4634: throw new IllegalArgumentException(
4635: "outputValues should be a series of key/value pairs.");
4636:
4637: return mElementContext.getExitFormParametersJavascript(name,
4638: outputValues);
4639: }
4640:
4641: /**
4642: * Generates a query URL for an exit and sets it as the content of a
4643: * template value.
4644: *
4645: * @param template the template that will be used to set the value
4646: * @param name the name of the exit
4647: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
4648: * template doesn't contain the value identifier
4649: * <code>EXIT:QUERY:exitname</code>
4650: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4651: * is known with this name; if the exit hasn't got a destination element;
4652: * if you don't have access to the request data (eg. you're inside a child
4653: * trigger); or if there's no active element context (eg. you're using
4654: * this method inside the constructor instead of inside the {@link
4655: * #initialize()} method)
4656: * @see #getExitQueryUrl(String, String, String[])
4657: * @see #getExitFormUrl(String, String)
4658: * @see #getExitFormParameters(String, String[])
4659: * @see #setExitQuery(Template, String, String, String[])
4660: * @see #setExitForm(Template, String, String)
4661: * @since 1.0
4662: */
4663: public void setExitQuery(Template template, String name)
4664: throws TemplateException, EngineException {
4665: setExitQuery(template, name, null, null);
4666: }
4667:
4668: /**
4669: * Generates a query URL with a pathinfo for an exit and sets it as the
4670: * content of a template value.
4671: *
4672: * @param template the template that will be used to set the value
4673: * @param name the name of the exit
4674: * @param pathinfo the pathinfo that will be appended; or
4675: * <code>null</code> if no pathinfo should be appended
4676: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
4677: * template doesn't contain the value identifier
4678: * <code>EXIT:QUERY:exitname</code>
4679: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4680: * is known with this name; if the exit hasn't got a destination element;
4681: * if you don't have access to the request data (eg. you're inside a child
4682: * trigger); or if there's no active element context (eg. you're using
4683: * this method inside the constructor instead of inside the {@link
4684: * #initialize()} method)
4685: * @see #getExitQueryUrl(String, String, String[])
4686: * @see #getExitFormUrl(String, String)
4687: * @see #getExitFormParameters(String, String[])
4688: * @see #setExitQuery(Template, String, String, String[])
4689: * @see #setExitForm(Template, String, String)
4690: * @since 1.0
4691: */
4692: public void setExitQuery(Template template, String name,
4693: String pathinfo) throws TemplateException, EngineException {
4694: setExitQuery(template, name, pathinfo, null);
4695: }
4696:
4697: /**
4698: * Generates a query URL for an exit with overridden outputs and sets it
4699: * as the content of a template value.
4700: *
4701: * @param template the template that will be used to set the value
4702: * @param name the name of the exit
4703: * @param outputValues an array of string pairs that will be used to
4704: * override the current output values; or <code>null</code> if no output
4705: * values should be overridden
4706: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
4707: * template doesn't contain the value identifier
4708: * <code>EXIT:QUERY:exitname</code>
4709: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4710: * is known with this name; if the exit hasn't got a destination element;
4711: * if you don't have access to the request data (eg. you're inside a child
4712: * trigger); or if there's no active element context (eg. you're using
4713: * this method inside the constructor instead of inside the {@link
4714: * #initialize()} method)
4715: * @see #getExitQueryUrl(String, String, String[])
4716: * @see #getExitFormUrl(String, String)
4717: * @see #getExitFormParameters(String, String[])
4718: * @see #setExitQuery(Template, String, String, String[])
4719: * @see #setExitForm(Template, String, String)
4720: * @since 1.0
4721: */
4722: public void setExitQuery(Template template, String name,
4723: String[] outputValues) throws TemplateException,
4724: EngineException {
4725: setExitQuery(template, name, null, outputValues);
4726: }
4727:
4728: /**
4729: * Generates a query URL for an exit with a pathinfo and overridden
4730: * outputs and sets it as the content of a template value.
4731: * <p>The URL will be generated by calling the {@link
4732: * #getExitQueryUrl(String, String, String[])} method and it will be set
4733: * to the value identifier with the syntax
4734: * <code>EXIT:QUERY:exitname</code>.
4735: * <p>Template content that is outputted with the
4736: * <code>#print(Template)</code> method will automatically be scanned for
4737: * value identifiers with this syntax and the exit query URLs will
4738: * generated. You should only use this method if you need a query URL to
4739: * be generated in a certain context.
4740: *
4741: * @param template the template that will be used to set the value
4742: * @param name the name of the exit
4743: * @param pathinfo the pathinfo that will be appended; or
4744: * <code>null</code> if no pathinfo should be appended
4745: * @param outputValues an array of string pairs that will be used to
4746: * override the current output values; or <code>null</code> if no output
4747: * values should be overridden
4748: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
4749: * template doesn't contain the value identifier
4750: * <code>EXIT:QUERY:exitname</code>
4751: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4752: * is known with this name; if the exit hasn't got a destination element;
4753: * if you don't have access to the request data (eg. you're inside a child
4754: * trigger); or if there's no active element context (eg. you're using
4755: * this method inside the constructor instead of inside the {@link
4756: * #initialize()} method)
4757: * @see #getExitQueryUrl(String, String, String[])
4758: * @see #getExitFormUrl(String, String)
4759: * @see #getExitFormParameters(String, String[])
4760: * @see #setExitForm(Template, String, String)
4761: * @since 1.0
4762: */
4763: public void setExitQuery(Template template, String name,
4764: String pathinfo, String[] outputValues)
4765: throws TemplateException, EngineException {
4766: if (!mRequestAccessEnabled)
4767: throw new RequestAccessDeniedException();
4768: if (null == mElementContext)
4769: throw new ElementContextMissingException();
4770:
4771: if (null == template)
4772: throw new IllegalArgumentException(
4773: "template can't be null.");
4774: if (null == name)
4775: throw new IllegalArgumentException("name can't be null.");
4776: if (0 == name.length())
4777: throw new IllegalArgumentException("name can't be empty.");
4778: if (null != outputValues && outputValues.length % 2 > 0)
4779: throw new IllegalArgumentException(
4780: "outputValues should be a series of key/value pairs.");
4781:
4782: mElementContext.setExitQuery(template, name, pathinfo,
4783: outputValues);
4784: }
4785:
4786: /**
4787: * Generates a form action URL for an exit and sets it as the content of a
4788: * template value.
4789: *
4790: * @param template the template that will be used to set the value
4791: * @param name the name of the exit
4792: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
4793: * template doesn't contain the value identifiers
4794: * <code>EXIT:FORM:exitname</code> and <code>EXIT:PARAMS:exitname</code>
4795: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4796: * is known with this name; if the exit hasn't got a destination element;
4797: * if you don't have access to the request data (eg. you're inside a child
4798: * trigger); or if there's no active element context (eg. you're using
4799: * this method inside the constructor instead of inside the {@link
4800: * #initialize()} method)
4801: * @see #getExitQueryUrl(String, String, String[])
4802: * @see #getExitFormUrl(String, String)
4803: * @see #getExitFormParameters(String, String[])
4804: * @see #setExitQuery(Template, String, String, String[])
4805: * @see #setExitForm(Template, String, String)
4806: * @since 1.0
4807: */
4808: public void setExitForm(Template template, String name)
4809: throws TemplateException, EngineException {
4810: setExitForm(template, name, null, null);
4811: }
4812:
4813: /**
4814: * Generates a form action URL for an exit with a pathinfo and sets it as
4815: * the content of a template value.
4816: *
4817: * @param template the template that will be used to set the value
4818: * @param name the name of the exit
4819: * @param pathinfo the pathinfo that will be appended; or
4820: * <code>null</code> if no pathinfo should be appended
4821: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
4822: * template doesn't contain the value identifiers
4823: * <code>EXIT:FORM:exitname</code> and <code>EXIT:PARAMS:exitname</code>
4824: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4825: * is known with this name; if the exit hasn't got a destination element;
4826: * if you don't have access to the request data (eg. you're inside a child
4827: * trigger); or if there's no active element context (eg. you're using
4828: * this method inside the constructor instead of inside the {@link
4829: * #initialize()} method)
4830: * @see #getExitQueryUrl(String, String, String[])
4831: * @see #getExitFormUrl(String, String)
4832: * @see #getExitFormParameters(String, String[])
4833: * @see #setExitQuery(Template, String, String, String[])
4834: * @see #setExitForm(Template, String, String)
4835: * @since 1.0
4836: */
4837: public void setExitForm(Template template, String name,
4838: String pathinfo) throws TemplateException, EngineException {
4839: setExitForm(template, name, pathinfo, null);
4840: }
4841:
4842: /**
4843: * Generates a form action URL for an exit with overridden outputs and
4844: * sets it as the content of a template value.
4845: *
4846: * @param template the template that will be used to set the value
4847: * @param name the name of the exit
4848: * @param outputValues an array of string pairs that will be used to
4849: * override the current output values; or <code>null</code> if no output
4850: * values should be overridden
4851: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
4852: * template doesn't contain the value identifiers
4853: * <code>EXIT:FORM:exitname</code> and <code>EXIT:PARAMS:exitname</code>
4854: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4855: * is known with this name; if the exit hasn't got a destination element;
4856: * if you don't have access to the request data (eg. you're inside a child
4857: * trigger); or if there's no active element context (eg. you're using
4858: * this method inside the constructor instead of inside the {@link
4859: * #initialize()} method)
4860: * @see #getExitQueryUrl(String, String, String[])
4861: * @see #getExitFormUrl(String, String)
4862: * @see #getExitFormParameters(String, String[])
4863: * @see #setExitQuery(Template, String, String, String[])
4864: * @see #setExitForm(Template, String, String)
4865: * @since 1.0
4866: */
4867: public void setExitForm(Template template, String name,
4868: String[] outputValues) throws TemplateException,
4869: EngineException {
4870: setExitForm(template, name, null, outputValues);
4871: }
4872:
4873: /**
4874: * Generates a form action URL for an exit with a pathinfo and overridden
4875: * outputs and sets it as the content of a template value.
4876: * <p>The URL will be generated by calling the {@link
4877: * #getExitFormUrl(String, String)} and {@link
4878: * #getExitFormParameters(String, String[])} methods and it will be set
4879: * the results to the value identifiers with the syntax
4880: * <code>EXIT:FORM:exitname</code> and <code>EXIT:PARAMS:exitname</code>.
4881: * <p>Template content that is outputted with the
4882: * <code>#print(Template)</code> method will automatically be scanned for
4883: * value identifiers with this syntax and the exit forms URLs and
4884: * parameters will generated. You should only use this method if you need
4885: * these to be generated in a certain context.
4886: *
4887: * @param template the template that will be used to set the value
4888: * @param name the name of the exit
4889: * @param pathinfo the pathinfo that will be appended; or
4890: * <code>null</code> if no pathinfo should be appended
4891: * @param outputValues an array of string pairs that will be used to
4892: * override the current output values; or <code>null</code> if no output
4893: * values should be overridden
4894: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
4895: * template doesn't contain the value identifiers
4896: * <code>EXIT:FORM:exitname</code> and <code>EXIT:PARAMS:exitname</code>
4897: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
4898: * is known with this name; if the exit hasn't got a destination element;
4899: * if you don't have access to the request data (eg. you're inside a child
4900: * trigger); or if there's no active element context (eg. you're using
4901: * this method inside the constructor instead of inside the {@link
4902: * #initialize()} method)
4903: * @see #getExitQueryUrl(String, String, String[])
4904: * @see #getExitFormUrl(String, String)
4905: * @see #getExitFormParameters(String, String[])
4906: * @see #setExitQuery(Template, String, String, String[])
4907: * @since 1.0
4908: */
4909: public void setExitForm(Template template, String name,
4910: String pathinfo, String[] outputValues)
4911: throws TemplateException, EngineException {
4912: if (!mRequestAccessEnabled)
4913: throw new RequestAccessDeniedException();
4914: if (null == mElementContext)
4915: throw new ElementContextMissingException();
4916:
4917: if (null == template)
4918: throw new IllegalArgumentException(
4919: "template can't be null.");
4920: if (null == name)
4921: throw new IllegalArgumentException("name can't be null.");
4922: if (0 == name.length())
4923: throw new IllegalArgumentException("name can't be empty.");
4924: if (null != outputValues && outputValues.length % 2 > 0)
4925: throw new IllegalArgumentException(
4926: "outputValues should be a series of key/value pairs.");
4927:
4928: mElementContext.setExitForm(template, name, pathinfo,
4929: outputValues);
4930: }
4931:
4932: /**
4933: * Sets a select box option, a radio button or a checkbox to selected or
4934: * checked.
4935: * <p>This method will check the template for certain value tags and set
4936: * them to the correct attributes according to the name and the provided
4937: * values in this method. This is dependent on the template type and
4938: * currently only makes sense for <code>enginehtml</code>,
4939: * <code>enginexhtml</code>, <code>html</code> and <code>xhtml</code>
4940: * templates.
4941: * <p>For example for select boxes, consider the name '<code>colors</code>',
4942: * the values '<code>blue</code>' and '<code>red</code>', and the
4943: * following XHTML template excerpt:
4944: * <pre><select name="colors">
4945: *<option value="blue"[!V 'colors:blue:SELECTED'][!/V]>Blue</option>
4946: *<option value="orange"[!V 'colors:orange:SELECTED'][!/V]>Orange</option>
4947: *<option value="red"[!V 'colors:red:SELECTED'][!/V]>Red</option>
4948: *<option value="green"[!V colors:green:SELECTED''][!/V]>Green</option>
4949: *</select></pre>
4950: * <p>the result will then be:
4951: * <pre><select name="colors">
4952: *<option value="blue" selected="selected">Blue</option>
4953: *<option value="orange">Orange</option>
4954: *<option value="red" selected="selected">Red</option>
4955: *<option value="green">Green</option>
4956: *</select></pre>
4957: * <p>For example for radio buttons, consider the name '<code>sex</code>',
4958: * the value '<code>male</code>' and the following XHTML template excerpt:
4959: * <pre><input type="radio" name="sex" value="male"[!V 'sex:male:CHECKED'][!/V] />
4960: *<input type="radio" name="sex" value="female"[!V 'sex:female:CHECKED'][!/V] /></pre>
4961: * <p>the result will then be:
4962: * <pre><input type="radio" name="sex" value="male" checked="checked" />
4963: *<input type="radio" name="sex" value="female" /></pre>
4964: * <p>For example for checkboxes, consider the name '<code>active</code>',
4965: * the value '<code>true</code>' and the following XHTML template excerpt:
4966: * <pre><input type="checkbox" name="active"[!V 'active:CHECKED'][!/V] />
4967: *<input type="checkbox" name="senditnow"[!V 'senditnow:CHECKED'][!/V] /></pre>
4968: * <p>the result will then be:
4969: * <pre><input type="checkbox" name="active" checked="checked" />
4970: *<input type="checkbox" name="senditnow" /></pre>
4971: *
4972: * @param template the template instance where the selection should happen
4973: * @param name the name of the parameter
4974: * @param values the values that should selected or checked
4975: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
4976: * no active element context (eg. you're using this method inside the
4977: * constructor instead of inside the {@link #initialize()} method)
4978: * @return a list with the identifiers of the template values that have
4979: * been set, this is never <code>null</code>, when no values are set an
4980: * empty list is returned
4981: * @see #selectInputParameter(Template, String, String[])
4982: * @see #selectSubmissionParameter(Template, String, String[])
4983: * @since 1.0
4984: */
4985: public Collection<String> selectParameter(Template template,
4986: String name, String[] values) {
4987: if (null == mElementContext)
4988: throw new ElementContextMissingException();
4989:
4990: if (null == template)
4991: throw new IllegalArgumentException(
4992: "template can't be null.");
4993: if (null == name)
4994: throw new IllegalArgumentException("name can't be null.");
4995: if (0 == name.length())
4996: throw new IllegalArgumentException("name can't be empty.");
4997:
4998: return mElementContext.selectParameter(template, name, values);
4999: }
5000:
5001: /**
5002: * Generates a form that corresponds to a bean instance.
5003: *
5004: * @param template the template instance where the generation should
5005: * happen
5006: * @param beanInstance the instance of the bean that should be used to
5007: * generate the form
5008: * @exception com.uwyn.rife.engine.exceptions.EngineException if errors
5009: * occurred during the introspection of the bean instance; or if there's
5010: * no active element context (eg. you're using this method inside the
5011: * constructor instead of inside the {@link #initialize()} method)
5012: * @see com.uwyn.rife.site.FormBuilder
5013: * @see #generateForm(Template, Object, String)
5014: * @see #generateEmptyForm(Template, Class, String)
5015: * @see #removeForm(Template, Class)
5016: * @since 1.0
5017: */
5018: public void generateForm(Template template, Object beanInstance)
5019: throws EngineException {
5020: generateForm(template, beanInstance, null);
5021: }
5022:
5023: /**
5024: * Generates a form that corresponds to a bean instance.
5025: * <p>This method delegates all logic to the {@link
5026: * com.uwyn.rife.site.FormBuilder#generateForm(Template, Object, Map, String)}
5027: * method of the provided template instance.
5028: *
5029: * @param template the template instance where the generation should
5030: * happen
5031: * @param beanInstance the instance of the bean that should be used to
5032: * generate the form
5033: * @param prefix the prefix that will be prepended to all bean property
5034: * names
5035: * @exception com.uwyn.rife.engine.exceptions.EngineException if errors
5036: * occurred during the introspection of the bean instance; or if there's
5037: * no active element context (eg. you're using this method inside the
5038: * constructor instead of inside the {@link #initialize()} method)
5039: * @see com.uwyn.rife.site.FormBuilder
5040: * @see #generateEmptyForm(Template, Class, String)
5041: * @see #removeForm(Template, Class)
5042: * @since 1.0
5043: */
5044: public void generateForm(Template template, Object beanInstance,
5045: String prefix) throws EngineException {
5046: if (null == mElementContext)
5047: throw new ElementContextMissingException();
5048:
5049: if (null == template)
5050: throw new IllegalArgumentException(
5051: "template can't be null.");
5052: if (null == beanInstance)
5053: throw new IllegalArgumentException(
5054: "beanInstance can't be null.");
5055:
5056: mElementContext.generateForm(template, beanInstance, prefix);
5057: }
5058:
5059: /**
5060: * Generates a form that corresponds to an empty instance of a bean class.
5061: *
5062: * @param template the template instance where the generation should
5063: * happen
5064: * @param beanClass the class of the bean that should be used to generate
5065: * the form
5066: * @exception com.uwyn.rife.engine.exceptions.EngineException if errors
5067: * occurred during the introspection of the bean; or if there's no active
5068: * element context (eg. you're using this method inside the constructor
5069: * instead of inside the {@link #initialize()} method)
5070: * @see com.uwyn.rife.site.FormBuilder
5071: * @see #generateForm(Template, Object, String)
5072: * @see #generateEmptyForm(Template, Class, String)
5073: * @see #removeForm(Template, Class)
5074: * @since 1.0
5075: */
5076: public void generateEmptyForm(Template template, Class beanClass)
5077: throws EngineException {
5078: generateEmptyForm(template, beanClass, null);
5079: }
5080:
5081: /**
5082: * Generates a form that corresponds to an empty instance of a bean class.
5083: * <p>An '<em>empty</em>' instance is an object that has been created by
5084: * calling the default constructor of the bean class, without making any
5085: * additional changes to it afterwards.
5086: * <p>This method delegates all logic to the {@link
5087: * com.uwyn.rife.site.FormBuilder#generateForm(Template, Class, Map, String)}
5088: * method of the provided template instance.
5089: *
5090: * @param template the template instance where the generation should
5091: * happen
5092: * @param beanClass the class of the bean that should be used to generate
5093: * the form
5094: * @param prefix the prefix that will be prepended to all bean property
5095: * names
5096: * @exception com.uwyn.rife.engine.exceptions.EngineException if errors
5097: * occurred during the introspection of the bean; or if there's no active
5098: * element context (eg. you're using this method inside the constructor
5099: * instead of inside the {@link #initialize()} method)
5100: * @see com.uwyn.rife.site.FormBuilder
5101: * @see #generateForm(Template, Object, String)
5102: * @see #removeForm(Template, Class)
5103: * @since 1.0
5104: */
5105: public void generateEmptyForm(Template template, Class beanClass,
5106: String prefix) throws EngineException {
5107: if (null == mElementContext)
5108: throw new ElementContextMissingException();
5109:
5110: if (null == template)
5111: throw new IllegalArgumentException(
5112: "template can't be null.");
5113: if (null == beanClass)
5114: throw new IllegalArgumentException(
5115: "beanClass can't be null.");
5116:
5117: mElementContext.generateEmptyForm(template, beanClass, prefix);
5118: }
5119:
5120: /**
5121: * Removes a generated form, leaving the builder value tags empty again as
5122: * if this form never had been generated.
5123: *
5124: * @param template the template instance where the form should be removed
5125: * from
5126: * @param beanClass the class of the bean that should be used to remove
5127: * the form
5128: * @exception com.uwyn.rife.engine.exceptions.EngineException if errors
5129: * occurred during the introspection of the bean; or if there's no active
5130: * element context (eg. you're using this method inside the constructor
5131: * instead of inside the {@link #initialize()} method)
5132: * @see com.uwyn.rife.site.FormBuilder
5133: * @see #generateForm(Template, Object, String)
5134: * @see #generateEmptyForm(Template, Class, String)
5135: * @see #removeForm(Template, Class)
5136: * @since 1.0
5137: */
5138: public void removeForm(Template template, Class beanClass)
5139: throws EngineException {
5140: removeForm(template, beanClass, null);
5141: }
5142:
5143: /**
5144: * Removes a generated form, leaving the builder value tags empty again as
5145: * if this form never had been generated.
5146: * <p>This method delegates all logic to the {@link
5147: * com.uwyn.rife.site.FormBuilder#removeForm(Template, Class, String)}
5148: * method of the provided template instance.
5149: *
5150: * @param template the template instance where the form should be removed
5151: * from
5152: * @param beanClass the class of the bean that should be used to remove
5153: * the form
5154: * @param prefix the prefix that will be prepended to all bean property
5155: * names
5156: * @exception com.uwyn.rife.engine.exceptions.EngineException if errors
5157: * occurred during the introspection of the bean; or if there's no active
5158: * element context (eg. you're using this method inside the constructor
5159: * instead of inside the {@link #initialize()} method)
5160: * @see com.uwyn.rife.site.FormBuilder
5161: * @see #generateForm(Template, Object, String)
5162: * @see #generateEmptyForm(Template, Class, String)
5163: * @since 1.0
5164: */
5165: public void removeForm(Template template, Class beanClass,
5166: String prefix) throws EngineException {
5167: if (null == mElementContext)
5168: throw new ElementContextMissingException();
5169:
5170: if (null == template)
5171: throw new IllegalArgumentException(
5172: "template can't be null.");
5173: if (null == beanClass)
5174: throw new IllegalArgumentException(
5175: "beanClass can't be null.");
5176:
5177: mElementContext.removeForm(template, beanClass, prefix);
5178: }
5179:
5180: /**
5181: * Sets a select box option, a radio button or a checkbox to selected or
5182: * checked according to submission parameter values.
5183: * <p>The actual logic is performed by the {@link
5184: * #selectParameter(Template, String, String[])} method. This method only
5185: * prefixes the parameter name with the <code>PARAM:</code> literal, which
5186: * is the syntax that is used to be able to handle automatic population
5187: * correctly for each value type (inputs or submission parameters).
5188: * <p>This method is automatically called during the {@link
5189: * #print(Template)} for all the inputs and values that this element
5190: * received. You should thus only call it explicitly if you need it to be
5191: * executed with custom values.
5192: *
5193: * @param template the template instance where the selection should happen
5194: * @param name the name of the parameter
5195: * @param values the values that should selected or checked
5196: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
5197: * no active element context (eg. you're using this method inside the
5198: * constructor instead of inside the {@link #initialize()} method)
5199: * @return a list with the identifiers of the template values that have
5200: * been set, this is never <code>null</code>, when no values are set an
5201: * empty list is returned
5202: * @see #selectParameter(Template, String, String[])
5203: * @see #selectInputParameter(Template, String, String[])
5204: * @since 1.0
5205: */
5206: public Collection<String> selectSubmissionParameter(
5207: Template template, String name, String[] values) {
5208: if (null == mElementContext)
5209: throw new ElementContextMissingException();
5210:
5211: if (null == template)
5212: throw new IllegalArgumentException(
5213: "template can't be null.");
5214: if (null == name)
5215: throw new IllegalArgumentException("name can't be null.");
5216: if (0 == name.length())
5217: throw new IllegalArgumentException("name can't be empty.");
5218:
5219: return mElementContext.selectSubmissionParameter(template,
5220: name, values);
5221: }
5222:
5223: /**
5224: * Sets a select box option, a radio button or a checkbox to selected or
5225: * checked according to a submission parameter value.
5226: * <p>This is simply a convenience method that calls <code>#selectSubmissionParameter(Template,
5227: * String, String[])</code> with a single value string array.
5228: *
5229: * @param template the template instance where the selection should happen
5230: * @param name the name of the parameter
5231: * @param value the value that should selected or checked
5232: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
5233: * no active element context (eg. you're using this method inside the
5234: * constructor instead of inside the {@link #initialize()} method)
5235: * @return a list with the identifiers of the template values that have
5236: * been set, this is never <code>null</code>, when no values are set an
5237: * empty list is returned
5238: * @see #selectParameter(Template, String, String[])
5239: * @see #selectInputParameter(Template, String, String[])
5240: * @see #selectSubmissionParameter(Template, String, String[])
5241: * @since 1.0
5242: */
5243: public Collection selectSubmissionParameter(Template template,
5244: String name, String value) {
5245: if (null == mElementContext)
5246: throw new ElementContextMissingException();
5247:
5248: if (null == template)
5249: throw new IllegalArgumentException(
5250: "template can't be null.");
5251: if (null == name)
5252: throw new IllegalArgumentException("name can't be null.");
5253: if (0 == name.length())
5254: throw new IllegalArgumentException("name can't be empty.");
5255:
5256: return mElementContext.selectSubmissionParameter(template,
5257: name, new String[] { value });
5258: }
5259:
5260: /**
5261: * Sets the content of all values that correspond to bean property names
5262: * to the data of the bean properties.
5263: * <p>The data will be converted to strings and the template's encoder
5264: * will be used to encode the string representations (for example, for
5265: * HTML non-ascii characters will be replaced with HTML entities).
5266: * <p>The identifiers of the values that will be filled in should have the
5267: * following syntax:
5268: * <pre>PARAM:propertyName</pre>
5269: *
5270: * @param template the template instance that contains the values that
5271: * will be filled in
5272: * @param beanInstance the bean instance whose property values will be set
5273: * @exception com.uwyn.rife.template.exceptions.TemplateException when
5274: * errors occurred during the introspection of the bean instance
5275: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
5276: * no active element context (eg. you're using this method inside the
5277: * constructor instead of inside the {@link #initialize()} method)
5278: * @see #setSubmissionBean(Template, Object, boolean)
5279: * @since 1.0
5280: */
5281: public void setSubmissionBean(Template template, Object beanInstance)
5282: throws TemplateException, EngineException {
5283: setSubmissionBean(template, beanInstance, true);
5284: }
5285:
5286: /**
5287: * Sets the content of all values that correspond to bean property names
5288: * to the data of the bean properties.
5289: * <p>The identifiers of the values that will be filled in should have the
5290: * following syntax:
5291: * <pre>PARAM:propertyName</pre>
5292: *
5293: * @param template the template instance that contains the values that
5294: * will be filled in
5295: * @param beanInstance the bean instance whose property values will be set
5296: * @param encode <code>true</code> when the property values should be
5297: * encoded according to the template type; or
5298: * <p><code>false</code> otherwise
5299: * @exception com.uwyn.rife.template.exceptions.TemplateException when
5300: * errors occurred during the introspection of the bean instance
5301: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
5302: * no active element context (eg. you're using this method inside the
5303: * constructor instead of inside the {@link #initialize()} method)
5304: * @since 1.0
5305: */
5306: public void setSubmissionBean(Template template,
5307: Object beanInstance, boolean encode)
5308: throws TemplateException, EngineException {
5309: if (null == mElementContext)
5310: throw new ElementContextMissingException();
5311:
5312: if (null == template)
5313: throw new IllegalArgumentException(
5314: "template can't be null.");
5315: if (null == beanInstance)
5316: throw new IllegalArgumentException(
5317: "beanInstance can't be null.");
5318:
5319: mElementContext.setSubmissionBean(template, beanInstance,
5320: encode);
5321: }
5322:
5323: /**
5324: * Retrieves an instance of a named submission bean for the current
5325: * submission and populates the properties with the parameter values. The
5326: * class of the bean is looked up through its name, as is the property
5327: * prefix.
5328: * <p>This bean is not serialized or deserialized, each property
5329: * corresponds to a parameter and is individually sent by the client.
5330: *
5331: * @param beanName the name of the submission bean
5332: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
5333: * submission bean is known with this name; or if an error occurred during
5334: * the instantiation of the bean; or if you don't have access to the
5335: * request data (eg. you're inside a child trigger); or if there's no
5336: * active element context (eg. you're using this method inside the
5337: * constructor instead of inside the {@link #initialize()} method)
5338: * @return the populated submission bean instance; or
5339: * <p><code>null</code> if no submission has been sent
5340: * @see #getNamedSubmissionBean(String, String)
5341: * @see #getSubmissionBean(String, Class, String)
5342: * @see #fillSubmissionBean(String, Object, String)
5343: * @see #hasParameterValue(String)
5344: * @see #isParameterEmpty(String)
5345: * @see #getParameter(String)
5346: * @see #getParameter(String, String)
5347: * @see #getParameterValues(String)
5348: * @see #getParameterNames()
5349: * @see #getParameterNames(String)
5350: * @since 1.0
5351: */
5352: public <BeanType> BeanType getNamedSubmissionBean(String beanName)
5353: throws EngineException {
5354: if (!mRequestAccessEnabled)
5355: throw new RequestAccessDeniedException();
5356: if (null == mElementContext)
5357: throw new ElementContextMissingException();
5358:
5359: if (null == beanName)
5360: throw new IllegalArgumentException(
5361: "beanName can't be null.");
5362: if (0 == beanName.length())
5363: throw new IllegalArgumentException(
5364: "beanName can't be empty.");
5365:
5366: String submission_name = mElementContext.getSubmission();
5367: if (null == submission_name) {
5368: return null;
5369: }
5370:
5371: return (BeanType) mElementContext.getNamedSubmissionBean(
5372: submission_name, beanName);
5373: }
5374:
5375: /**
5376: * Retrieves an instance of a named submission bean and populates the
5377: * properties with the parameter values. The class of the bean is looked
5378: * up through its name, as is the property prefix.
5379: * <p>This bean is not serialized or deserialized, each property
5380: * corresponds to a parameter and is individually sent by the client.
5381: *
5382: * @param submissionName the name of the submission bean
5383: * @param beanName the name of the submission that contains the bean
5384: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
5385: * submission bean is known with this name; or if no submission is know
5386: * with the name; or if an error occurred during the instantiation or the
5387: * population of the bean; or if you don't have access to the request data
5388: * (eg. you're inside a child trigger); or if there's no active element
5389: * context (eg. you're using this method inside the constructor instead of
5390: * inside the {@link #initialize()} method)
5391: * @return the populated submission bean instance; or
5392: * <p><code>null</code> if the submission name doesn't correspond to the
5393: * sent submission
5394: * @see #getSubmissionBean(String, Class, String)
5395: * @see #fillSubmissionBean(String, Object, String)
5396: * @see #hasParameterValue(String)
5397: * @see #isParameterEmpty(String)
5398: * @see #getParameter(String)
5399: * @see #getParameter(String, String)
5400: * @see #getParameterValues(String)
5401: * @see #getParameterNames()
5402: * @see #getParameterNames(String)
5403: * @since 1.0
5404: */
5405: public <BeanType> BeanType getNamedSubmissionBean(
5406: String submissionName, String beanName)
5407: throws EngineException {
5408: if (!mRequestAccessEnabled)
5409: throw new RequestAccessDeniedException();
5410: if (null == mElementContext)
5411: throw new ElementContextMissingException();
5412:
5413: if (null == submissionName)
5414: throw new IllegalArgumentException(
5415: "submissionName can't be null.");
5416: if (0 == submissionName.length())
5417: throw new IllegalArgumentException(
5418: "submissionName can't be empty.");
5419: if (null == beanName)
5420: throw new IllegalArgumentException(
5421: "beanName can't be null.");
5422: if (0 == beanName.length())
5423: throw new IllegalArgumentException(
5424: "beanName can't be empty.");
5425:
5426: return (BeanType) mElementContext.getNamedSubmissionBean(
5427: submissionName, beanName);
5428: }
5429:
5430: /**
5431: * Retrieves an instance of a submission bean and populates the properties
5432: * with the parameter values.
5433: * <p>This bean is not serialized or de-serialized, each property
5434: * corresponds to a parameter and is individually sent by the client.
5435: *
5436: * @param beanClass the class of the submission bean
5437: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
5438: * occurred during the instantiation or the population of the bean; or if
5439: * you don't have access to the request data (eg. you're inside a child
5440: * trigger); or if there's no active element context (eg. you're using
5441: * this method inside the constructor instead of inside the {@link
5442: * #initialize()} method)
5443: * @return the populated submission bean instance; or
5444: * <p><code>null</code> if no submission has been sent
5445: * @see #getNamedSubmissionBean(String, String)
5446: * @see #getSubmissionBean(String, Class, String)
5447: * @see #fillSubmissionBean(String, Object, String)
5448: * @see #hasParameterValue(String)
5449: * @see #isParameterEmpty(String)
5450: * @see #getParameter(String)
5451: * @see #getParameter(String, String)
5452: * @see #getParameterValues(String)
5453: * @see #getParameterNames()
5454: * @see #getParameterNames(String)
5455: * @since 1.0
5456: */
5457: public <BeanType> BeanType getSubmissionBean(
5458: Class<BeanType> beanClass) throws EngineException {
5459: String submission_name = mElementContext.getSubmission();
5460: if (null == submission_name) {
5461: return null;
5462: }
5463:
5464: return getSubmissionBean(submission_name, beanClass, null);
5465: }
5466:
5467: /**
5468: * Retrieves an instance of a submission bean and populates the properties
5469: * with the parameter values, taking the provided prefix into account.
5470: * <p>This bean is not serialized or de-serialized, each property
5471: * corresponds to a parameter and is individually sent by the client.
5472: *
5473: * @param beanClass the class of the submission bean
5474: * @param prefix the prefix that will be put in front of each property
5475: * name
5476: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
5477: * occurred during the instantiation or the population of the bean; or if
5478: * you don't have access to the request data (eg. you're inside a child
5479: * trigger); or if there's no active element context (eg. you're using
5480: * this method inside the constructor instead of inside the {@link
5481: * #initialize()} method)
5482: * @return the populated submission bean instance; or
5483: * <p><code>null</code> if no submission has been sent
5484: * @see #getNamedSubmissionBean(String, String)
5485: * @see #getSubmissionBean(String, Class, String)
5486: * @see #fillSubmissionBean(String, Object, String)
5487: * @see #hasParameterValue(String)
5488: * @see #isParameterEmpty(String)
5489: * @see #getParameter(String)
5490: * @see #getParameter(String, String)
5491: * @see #getParameterValues(String)
5492: * @see #getParameterNames()
5493: * @see #getParameterNames(String)
5494: * @since 1.0
5495: */
5496: public <BeanType> BeanType getSubmissionBean(
5497: Class<BeanType> beanClass, String prefix)
5498: throws EngineException {
5499: String submission_name = mElementContext.getSubmission();
5500: if (null == submission_name) {
5501: return null;
5502: }
5503:
5504: return getSubmissionBean(submission_name, beanClass, prefix);
5505: }
5506:
5507: /**
5508: * Retrieves an instance of a submission bean and populates the properties
5509: * with the parameter values.
5510: * <p>This bean is not serialized or de-serialized, each property
5511: * corresponds to a parameter and is individually sent by the client.
5512: *
5513: * @param submissionName the name of the submission
5514: * @param beanClass the class of the submission bean
5515: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
5516: * occurred during the instantiation or the population of the bean; or if
5517: * you don't have access to the request data (eg. you're inside a child
5518: * trigger); or if there's no active element context (eg. you're using
5519: * this method inside the constructor instead of inside the {@link
5520: * #initialize()} method)
5521: * @return the populated submission bean instance; or
5522: * <p><code>null</code> if the submission name doesn't correspond to the
5523: * sent submission
5524: * @see #getNamedSubmissionBean(String, String)
5525: * @see #getSubmissionBean(String, Class, String)
5526: * @see #fillSubmissionBean(String, Object, String)
5527: * @see #hasParameterValue(String)
5528: * @see #isParameterEmpty(String)
5529: * @see #getParameter(String)
5530: * @see #getParameter(String, String)
5531: * @see #getParameterValues(String)
5532: * @see #getParameterNames()
5533: * @see #getParameterNames(String)
5534: * @since 1.0
5535: */
5536: public <BeanType> BeanType getSubmissionBean(String submissionName,
5537: Class<BeanType> beanClass) throws EngineException {
5538: return getSubmissionBean(submissionName, beanClass, null);
5539: }
5540:
5541: /**
5542: * Retrieves an instance of a submission bean and populates the properties
5543: * with the parameter values, taking the provided prefix into account.
5544: * <p>This bean is not serialized or de-serialized, each property
5545: * corresponds to a parameter and is individually sent by the client.
5546: *
5547: * @param submissionName the name of the submission
5548: * @param beanClass the class of the submission bean
5549: * @param prefix the prefix that will be put in front of each property
5550: * name
5551: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
5552: * occurred during the instantiation or the population of the bean; or if
5553: * you don't have access to the request data (eg. you're inside a child
5554: * trigger); or if there's no active element context (eg. you're using
5555: * this method inside the constructor instead of inside the {@link
5556: * #initialize()} method)
5557: * @return the populated submission bean instance; or
5558: * <p><code>null</code> if the submission name doesn't correspond to the
5559: * sent submission
5560: * @see #getNamedSubmissionBean(String, String)
5561: * @see #fillSubmissionBean(String, Object, String)
5562: * @see #hasParameterValue(String)
5563: * @see #isParameterEmpty(String)
5564: * @see #getParameter(String)
5565: * @see #getParameter(String, String)
5566: * @see #getParameterValues(String)
5567: * @see #getParameterNames()
5568: * @see #getParameterNames(String)
5569: * @since 1.0
5570: */
5571: public <BeanType> BeanType getSubmissionBean(String submissionName,
5572: Class<BeanType> beanClass, String prefix)
5573: throws EngineException {
5574: if (!mRequestAccessEnabled)
5575: throw new RequestAccessDeniedException();
5576: if (null == mElementContext)
5577: throw new ElementContextMissingException();
5578:
5579: if (null == submissionName)
5580: throw new IllegalArgumentException(
5581: "submissionName can't be null.");
5582: if (0 == submissionName.length())
5583: throw new IllegalArgumentException(
5584: "submissionName can't be empty.");
5585: if (null == beanClass)
5586: throw new IllegalArgumentException(
5587: "beanClass can't be null.");
5588:
5589: return mElementContext.getSubmissionBean(submissionName,
5590: beanClass, prefix);
5591: }
5592:
5593: /**
5594: * Fills the properties of an existing bean with the parameter values of
5595: * the submission that was sent.
5596: *
5597: * @param bean the submission bean instance that will be filled
5598: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
5599: * occurred during the population of the bean; or if you don't have access
5600: * to the request data (eg. you're inside a child trigger); or if there's
5601: * no active element context (eg. you're using this method inside the
5602: * constructor instead of inside the {@link #initialize()} method)
5603: * @see #getNamedSubmissionBean(String, String)
5604: * @see #getSubmissionBean(String, Class, String)
5605: * @see #fillSubmissionBean(String, Object, String)
5606: * @see #hasParameterValue(String)
5607: * @see #isParameterEmpty(String)
5608: * @see #getParameter(String)
5609: * @see #getParameter(String, String)
5610: * @see #getParameterValues(String)
5611: * @see #getParameterNames()
5612: * @see #getParameterNames(String)
5613: * @since 1.0
5614: */
5615: public void fillSubmissionBean(Object bean) throws EngineException {
5616: String submission_name = mElementContext.getSubmission();
5617: if (null == submission_name) {
5618: return;
5619: }
5620:
5621: fillSubmissionBean(submission_name, bean, null);
5622: }
5623:
5624: /**
5625: * Fills the properties of an existing bean with the parameter values of a
5626: * submission.
5627: *
5628: * @param submissionName the name of the submission
5629: * @param bean the submission bean instance that will be filled
5630: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
5631: * occurred during the population of the bean; or if you don't have access
5632: * to the request data (eg. you're inside a child trigger); or if there's
5633: * no active element context (eg. you're using this method inside the
5634: * constructor instead of inside the {@link #initialize()} method)
5635: * @see #getNamedSubmissionBean(String, String)
5636: * @see #getSubmissionBean(String, Class, String)
5637: * @see #fillSubmissionBean(String, Object, String)
5638: * @see #hasParameterValue(String)
5639: * @see #isParameterEmpty(String)
5640: * @see #getParameter(String)
5641: * @see #getParameter(String, String)
5642: * @see #getParameterValues(String)
5643: * @see #getParameterNames()
5644: * @see #getParameterNames(String)
5645: * @since 1.0
5646: */
5647: public void fillSubmissionBean(String submissionName, Object bean)
5648: throws EngineException {
5649: fillSubmissionBean(submissionName, bean, null);
5650: }
5651:
5652: /**
5653: * Fills the properties of an existing bean with the parameter values of
5654: * the submission that was sent, taking the provided prefix into account.
5655: *
5656: * @param bean the submission bean instance that will be filled
5657: * @param prefix the prefix that will be put in front of each property
5658: * name
5659: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
5660: * occurred during the population of the bean; or if you don't have access
5661: * to the request data (eg. you're inside a child trigger); or if there's
5662: * no active element context (eg. you're using this method inside the
5663: * constructor instead of inside the {@link #initialize()} method)
5664: * @see #getNamedSubmissionBean(String, String)
5665: * @see #getSubmissionBean(String, Class, String)
5666: * @see #fillSubmissionBean(String, Object, String)
5667: * @see #hasParameterValue(String)
5668: * @see #isParameterEmpty(String)
5669: * @see #getParameter(String)
5670: * @see #getParameter(String, String)
5671: * @see #getParameterValues(String)
5672: * @see #getParameterNames()
5673: * @see #getParameterNames(String)
5674: * @since 1.0
5675: */
5676: public void fillSubmissionBean(Object bean, String prefix)
5677: throws EngineException {
5678: String submission_name = mElementContext.getSubmission();
5679: if (null == submission_name) {
5680: return;
5681: }
5682:
5683: fillSubmissionBean(submission_name, bean, prefix);
5684: }
5685:
5686: /**
5687: * Fills the properties of an existing bean with the parameter values of a
5688: * submission, taking the provided prefix into account.
5689: *
5690: * @param submissionName the name of the submission
5691: * @param bean the submission bean instance that will be filled
5692: * @param prefix the prefix that will be put in front of each property
5693: * name
5694: * @exception com.uwyn.rife.engine.exceptions.EngineException if an error
5695: * occurred during the population of the bean; or if you don't have access
5696: * to the request data (eg. you're inside a child trigger); or if there's
5697: * no active element context (eg. you're using this method inside the
5698: * constructor instead of inside the {@link #initialize()} method)
5699: * @see #getNamedSubmissionBean(String, String)
5700: * @see #getSubmissionBean(String, Class, String)
5701: * @see #hasParameterValue(String)
5702: * @see #isParameterEmpty(String)
5703: * @see #getParameter(String)
5704: * @see #getParameter(String, String)
5705: * @see #getParameterValues(String)
5706: * @see #getParameterNames()
5707: * @see #getParameterNames(String)
5708: * @since 1.0
5709: */
5710: public void fillSubmissionBean(String submissionName, Object bean,
5711: String prefix) throws EngineException {
5712: if (!mRequestAccessEnabled)
5713: throw new RequestAccessDeniedException();
5714: if (null == mElementContext)
5715: throw new ElementContextMissingException();
5716:
5717: if (null == submissionName)
5718: throw new IllegalArgumentException(
5719: "submissionName can't be null.");
5720: if (0 == submissionName.length())
5721: throw new IllegalArgumentException(
5722: "submissionName can't be empty.");
5723:
5724: mElementContext
5725: .fillSubmissionBean(submissionName, bean, prefix);
5726: }
5727:
5728: /**
5729: * Indicates whether this element received a submission.
5730: *
5731: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
5732: * have access to the request data (eg. you're inside a child trigger); or
5733: * if there's no active element context (eg. you're using this method
5734: * inside the constructor instead of inside the {@link #initialize()}
5735: * method)
5736: * @return <code>true</code> if a submission was sent to this element; and
5737: * <p><code>false</code> otherwise
5738: * @see #hasSubmission(String)
5739: * @see #getSubmission()
5740: * @since 1.0
5741: */
5742: public boolean hasSubmission() throws EngineException {
5743: if (!mRequestAccessEnabled)
5744: throw new RequestAccessDeniedException();
5745: if (null == mElementContext)
5746: throw new ElementContextMissingException();
5747:
5748: return mElementContext.hasSubmission();
5749: }
5750:
5751: /**
5752: * Indicates whether this element received a certain submission.
5753: *
5754: * @param submissionName the name of the submission
5755: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
5756: * have access to the request data (eg. you're inside a child trigger); or
5757: * if there's no active element context (eg. you're using this method
5758: * inside the constructor instead of inside the {@link #initialize()}
5759: * method)
5760: * @return <code>true</code> if the submission was sent to this element;
5761: * and
5762: * <p><code>false</code> otherwise
5763: * @see #hasSubmission()
5764: * @see #getSubmission()
5765: * @since 1.0
5766: */
5767: public boolean hasSubmission(String submissionName)
5768: throws EngineException {
5769: if (!mRequestAccessEnabled)
5770: throw new RequestAccessDeniedException();
5771: if (null == mElementContext)
5772: throw new ElementContextMissingException();
5773:
5774: if (null == submissionName)
5775: throw new IllegalArgumentException(
5776: "submissionName can't be null.");
5777: if (0 == submissionName.length())
5778: throw new IllegalArgumentException(
5779: "submissionName can't be empty.");
5780:
5781: return mElementContext.hasSubmission(submissionName);
5782: }
5783:
5784: /**
5785: * Retrieves the name of the submission that was sent to this element
5786: *
5787: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
5788: * have access to the request data (eg. you're inside a child trigger); or
5789: * if there's no active element context (eg. you're using this method
5790: * inside the constructor instead of inside the {@link #initialize()}
5791: * method)
5792: * @return the name of the submission; or
5793: * <p><code>null</code> if no submission was sent
5794: * @see #hasSubmission()
5795: * @see #hasSubmission(String)
5796: * @since 1.0
5797: */
5798: public String getSubmission() throws EngineException {
5799: if (!mRequestAccessEnabled)
5800: throw new RequestAccessDeniedException();
5801: if (null == mElementContext)
5802: throw new ElementContextMissingException();
5803:
5804: return mElementContext.getSubmission();
5805: }
5806:
5807: /**
5808: * Checks whether a value has been provided to an parameter.
5809: *
5810: * @param name the name of the parameter
5811: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
5812: * parameter is known with this name; or if you don't have access to the
5813: * request data (eg. you're inside a child trigger); or if there's no
5814: * active element context (eg. you're using this method inside the
5815: * constructor instead of inside the {@link #initialize()} method)
5816: * @return <code>true</code> if the parameter has a value; or
5817: * <p><code>false</code> otherwise
5818: * @see #getNamedSubmissionBean(String, String)
5819: * @see #getSubmissionBean(String, Class, String)
5820: * @see #fillSubmissionBean(String, Object, String)
5821: * @see #isParameterEmpty(String)
5822: * @see #getParameter(String)
5823: * @see #getParameter(String, String)
5824: * @see #getParameterValues(String)
5825: * @see #getParameterNames()
5826: * @see #getParameterNames(String)
5827: * @since 1.0
5828: */
5829: public boolean hasParameterValue(String name)
5830: throws EngineException {
5831: if (!mRequestAccessEnabled)
5832: throw new RequestAccessDeniedException();
5833: if (null == mElementContext)
5834: throw new ElementContextMissingException();
5835:
5836: if (null == name)
5837: throw new IllegalArgumentException("name can't be null.");
5838: if (0 == name.length())
5839: throw new IllegalArgumentException("name can't be empty.");
5840:
5841: return mElementContext.hasParameterValue(name);
5842: }
5843:
5844: /**
5845: * Checks whether a parameter is empty.
5846: *
5847: * @param name the name of the parameter
5848: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
5849: * parameter is known with this name; or if you don't have access to the
5850: * request data (eg. you're inside a child trigger); or if there's no
5851: * active element context (eg. you're using this method inside the
5852: * constructor instead of inside the {@link #initialize()} method)
5853: * @return <code>true</code> if the parameter is empty; or
5854: * <p><code>false</code> otherwise
5855: * @see #getNamedSubmissionBean(String, String)
5856: * @see #getSubmissionBean(String, Class, String)
5857: * @see #fillSubmissionBean(String, Object, String)
5858: * @see #hasParameterValue(String)
5859: * @see #isParameterEmpty(String)
5860: * @see #getParameter(String)
5861: * @see #getParameter(String, String)
5862: * @see #getParameterValues(String)
5863: * @see #getParameterNames()
5864: * @see #getParameterNames(String)
5865: * @since 1.0
5866: */
5867: public boolean isParameterEmpty(String name) throws EngineException {
5868: if (!mRequestAccessEnabled)
5869: throw new RequestAccessDeniedException();
5870: if (null == mElementContext)
5871: throw new ElementContextMissingException();
5872:
5873: if (null == name)
5874: throw new IllegalArgumentException("name can't be null.");
5875: if (0 == name.length())
5876: throw new IllegalArgumentException("name can't be empty.");
5877:
5878: return mElementContext.isParameterEmpty(name);
5879: }
5880:
5881: /**
5882: * Retrieves the value of a parameter.
5883: *
5884: * @param name the name of the parameter
5885: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
5886: * parameter is known with this name; or if you don't have access to the
5887: * request data (eg. you're inside a child trigger); or if there's no
5888: * active element context (eg. you're using this method inside the
5889: * constructor instead of inside the {@link #initialize()} method)
5890: * @return the value of the parameter; or
5891: * <p><code>null</code> if no value is present for this parameter
5892: * @see #getNamedSubmissionBean(String, String)
5893: * @see #getSubmissionBean(String, Class, String)
5894: * @see #fillSubmissionBean(String, Object, String)
5895: * @see #hasParameterValue(String)
5896: * @see #isParameterEmpty(String)
5897: * @see #getParameter(String, String)
5898: * @see #getParameterValues(String)
5899: * @see #getParameterNames()
5900: * @see #getParameterNames(String)
5901: * @since 1.0
5902: */
5903: public String getParameter(String name) throws EngineException {
5904: if (!mRequestAccessEnabled)
5905: throw new RequestAccessDeniedException();
5906: if (null == mElementContext)
5907: throw new ElementContextMissingException();
5908:
5909: if (null == name)
5910: throw new IllegalArgumentException("name can't be null.");
5911: if (0 == name.length())
5912: throw new IllegalArgumentException("name can't be empty.");
5913:
5914: return mElementContext.getParameter(name);
5915: }
5916:
5917: /**
5918: * Retrieves the value of a parameter and returns a default value if no
5919: * parameter value is present
5920: *
5921: * @param name the name of the parameter
5922: * @param defaultValue the default value that will be used when no
5923: * parameter value is present
5924: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
5925: * parameter is known with this name; or if you don't have access to the
5926: * request data (eg. you're inside a child trigger); or if there's no
5927: * active element context (eg. you're using this method inside the
5928: * constructor instead of inside the {@link #initialize()} method)
5929: * @return the parameter value; or
5930: * <p>the default value if no parameter value is present
5931: * @see #getNamedSubmissionBean(String, String)
5932: * @see #getSubmissionBean(String, Class, String)
5933: * @see #fillSubmissionBean(String, Object, String)
5934: * @see #hasParameterValue(String)
5935: * @see #isParameterEmpty(String)
5936: * @see #getParameter(String)
5937: * @see #getParameterValues(String)
5938: * @see #getParameterNames()
5939: * @see #getParameterNames(String)
5940: * @since 1.0
5941: */
5942: public String getParameter(String name, String defaultValue)
5943: throws EngineException {
5944: String value = getParameter(name);
5945: if (value == null) {
5946: return defaultValue;
5947: }
5948:
5949: return value;
5950: }
5951:
5952: /**
5953: * Retrieves the names of all the parameters that are present.
5954: *
5955: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
5956: * have access to the request data (eg. you're inside a child trigger); or
5957: * if there's no active element context (eg. you're using this method
5958: * inside the constructor instead of inside the {@link #initialize()}
5959: * method)
5960: * @return the list with the parameter names
5961: * @see #getNamedSubmissionBean(String, String)
5962: * @see #getSubmissionBean(String, Class, String)
5963: * @see #fillSubmissionBean(String, Object, String)
5964: * @see #hasParameterValue(String)
5965: * @see #isParameterEmpty(String)
5966: * @see #getParameter(String)
5967: * @see #getParameter(String, String)
5968: * @see #getParameterNames(String)
5969: * @since 1.0
5970: */
5971: public ArrayList<String> getParameterNames() throws EngineException {
5972: if (!mRequestAccessEnabled)
5973: throw new RequestAccessDeniedException();
5974: if (null == mElementContext)
5975: throw new ElementContextMissingException();
5976:
5977: return mElementContext.getParameterNames(null);
5978: }
5979:
5980: /**
5981: * Retrieves the names of all the parameters that are present and that
5982: * match a regular expression.
5983: *
5984: * @param regexp the regular expression that will be used to filter the
5985: * parameter names
5986: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
5987: * have access to the request data (eg. you're inside a child trigger); or
5988: * if there's no active element context (eg. you're using this method
5989: * inside the constructor instead of inside the {@link #initialize()}
5990: * method)
5991: * @return the list with the parameter names
5992: * @see #getNamedSubmissionBean(String, String)
5993: * @see #getSubmissionBean(String, Class, String)
5994: * @see #fillSubmissionBean(String, Object, String)
5995: * @see #hasParameterValue(String)
5996: * @see #isParameterEmpty(String)
5997: * @see #getParameter(String)
5998: * @see #getParameter(String, String)
5999: * @see #getParameterNames()
6000: * @since 1.0
6001: */
6002: public ArrayList<String> getParameterNames(String regexp)
6003: throws EngineException {
6004: if (!mRequestAccessEnabled)
6005: throw new RequestAccessDeniedException();
6006: if (null == mElementContext)
6007: throw new ElementContextMissingException();
6008:
6009: return mElementContext.getParameterNames(regexp);
6010: }
6011:
6012: /**
6013: * Retrieves the values of a parameter.
6014: *
6015: * @param name the name of the parameter
6016: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6017: * parameter is known with this name; or if you don't have access to the
6018: * request data (eg. you're inside a child trigger); or if there's no
6019: * active element context (eg. you're using this method inside the
6020: * constructor instead of inside the {@link #initialize()} method)
6021: * @return a string array with all the parameter values; or
6022: * <p><code>null</code> if no parameter values are present
6023: * @see #getNamedSubmissionBean(String, String)
6024: * @see #getSubmissionBean(String, Class, String)
6025: * @see #fillSubmissionBean(String, Object, String)
6026: * @see #hasParameterValue(String)
6027: * @see #isParameterEmpty(String)
6028: * @see #getParameter(String)
6029: * @see #getParameter(String, String)
6030: * @see #getParameterNames()
6031: * @see #getParameterNames(String)
6032: * @since 1.0
6033: */
6034: public String[] getParameterValues(String name)
6035: throws EngineException {
6036: if (!mRequestAccessEnabled)
6037: throw new RequestAccessDeniedException();
6038: if (null == mElementContext)
6039: throw new ElementContextMissingException();
6040:
6041: if (null == name)
6042: throw new IllegalArgumentException("name can't be null.");
6043: if (0 == name.length())
6044: throw new IllegalArgumentException("name can't be empty.");
6045:
6046: return mElementContext.getParameterValues(name);
6047: }
6048:
6049: /**
6050: * Retrieves the value of a parameter and converts it to a boolean.
6051: *
6052: * @param name the name of the parameter
6053: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6054: * parameter is known with this name; or if you don't have access to the
6055: * request data (eg. you're inside a child trigger); or if there's no
6056: * active element context (eg. you're using this method inside the
6057: * constructor instead of inside the {@link #initialize()} method)
6058: * @return the converted parameter value; or
6059: * <p><code>false</code> if no parameter value is present or if the
6060: * parameter value is not a valid boolean
6061: * @see #getNamedSubmissionBean(String, String)
6062: * @see #getSubmissionBean(String, Class, String)
6063: * @see #fillSubmissionBean(String, Object, String)
6064: * @see #hasParameterValue(String)
6065: * @see #isParameterEmpty(String)
6066: * @see #getParameter(String)
6067: * @see #getParameter(String, String)
6068: * @see #getParameterValues(String)
6069: * @see #getParameterNames()
6070: * @see #getParameterNames(String)
6071: * @since 1.0
6072: */
6073: public boolean getParameterBoolean(String name)
6074: throws EngineException {
6075: return getParameterBoolean(name, ElementInfo.DEFAULT_BOOLEAN);
6076: }
6077:
6078: /**
6079: * Retrieves the value of a parameter and converts it to a boolean, using
6080: * a default value if no parameter value is present.
6081: *
6082: * @param name the name of the parameter
6083: * @param defaultValue the default value that will be used when no
6084: * parameter value is present
6085: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6086: * parameter is known with this name; or if you don't have access to the
6087: * request data (eg. you're inside a child trigger); or if there's no
6088: * active element context (eg. you're using this method inside the
6089: * constructor instead of inside the {@link #initialize()} method)
6090: * @return the converted parameter value; or
6091: * <p>the default value if no parameter value is present
6092: * @see #getNamedSubmissionBean(String, String)
6093: * @see #getSubmissionBean(String, Class, String)
6094: * @see #fillSubmissionBean(String, Object, String)
6095: * @see #hasParameterValue(String)
6096: * @see #isParameterEmpty(String)
6097: * @see #getParameter(String)
6098: * @see #getParameter(String, String)
6099: * @see #getParameterValues(String)
6100: * @see #getParameterNames()
6101: * @see #getParameterNames(String)
6102: * @since 1.0
6103: */
6104: public boolean getParameterBoolean(String name, boolean defaultValue)
6105: throws EngineException {
6106: String value = getParameter(name);
6107: if (value == null) {
6108: return defaultValue;
6109: }
6110:
6111: return StringUtils.convertToBoolean(value);
6112: }
6113:
6114: /**
6115: * Retrieves the value of a parameter and converts it to an integer.
6116: *
6117: * @param name the name of the parameter
6118: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6119: * parameter is known with this name; or if you don't have access to the
6120: * request data (eg. you're inside a child trigger); or if there's no
6121: * active element context (eg. you're using this method inside the
6122: * constructor instead of inside the {@link #initialize()} method)
6123: * @return the converted parameter value; or
6124: * <p><code>0</code> if no parameter value is present or if the parameter
6125: * value is not a valid integer
6126: * @see #getNamedSubmissionBean(String, String)
6127: * @see #getSubmissionBean(String, Class, String)
6128: * @see #fillSubmissionBean(String, Object, String)
6129: * @see #hasParameterValue(String)
6130: * @see #isParameterEmpty(String)
6131: * @see #getParameter(String)
6132: * @see #getParameter(String, String)
6133: * @see #getParameterValues(String)
6134: * @see #getParameterNames()
6135: * @see #getParameterNames(String)
6136: * @since 1.0
6137: */
6138: public int getParameterInt(String name) throws EngineException {
6139: return getParameterInt(name, ElementInfo.DEFAULT_INTEGER);
6140: }
6141:
6142: /**
6143: * Retrieves the value of a parameter and converts it to an integer, using
6144: * a default value if no parameter value is present.
6145: *
6146: * @param name the name of the parameter
6147: * @param defaultValue the default value that will be used when no
6148: * parameter value is present
6149: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6150: * parameter is known with this name; or if you don't have access to the
6151: * request data (eg. you're inside a child trigger); or if there's no
6152: * active element context (eg. you're using this method inside the
6153: * constructor instead of inside the {@link #initialize()} method)
6154: * @return the converted parameter value; or
6155: * <p>the default value if no parameter value is present
6156: * @see #getNamedSubmissionBean(String, String)
6157: * @see #getSubmissionBean(String, Class, String)
6158: * @see #fillSubmissionBean(String, Object, String)
6159: * @see #hasParameterValue(String)
6160: * @see #isParameterEmpty(String)
6161: * @see #getParameter(String)
6162: * @see #getParameter(String, String)
6163: * @see #getParameterValues(String)
6164: * @see #getParameterNames()
6165: * @see #getParameterNames(String)
6166: * @since 1.0
6167: */
6168: public int getParameterInt(String name, int defaultValue)
6169: throws EngineException {
6170: String value = getParameter(name);
6171: if (value == null) {
6172: return defaultValue;
6173: }
6174: try {
6175: return Integer.parseInt(value);
6176: } catch (NumberFormatException e) {
6177: return defaultValue;
6178: }
6179: }
6180:
6181: /**
6182: * Retrieves the value of a parameter and converts it to a long.
6183: *
6184: * @param name the name of the parameter
6185: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6186: * parameter is known with this name; or if you don't have access to the
6187: * request data (eg. you're inside a child trigger); or if there's no
6188: * active element context (eg. you're using this method inside the
6189: * constructor instead of inside the {@link #initialize()} method)
6190: * @return the converted parameter value; or
6191: * <p><code>0L</code> if no parameter value is present or if the parameter
6192: * value is not a valid long
6193: * @see #getNamedSubmissionBean(String, String)
6194: * @see #getSubmissionBean(String, Class, String)
6195: * @see #fillSubmissionBean(String, Object, String)
6196: * @see #hasParameterValue(String)
6197: * @see #isParameterEmpty(String)
6198: * @see #getParameter(String)
6199: * @see #getParameter(String, String)
6200: * @see #getParameterValues(String)
6201: * @see #getParameterNames()
6202: * @see #getParameterNames(String)
6203: * @since 1.0
6204: */
6205: public long getParameterLong(String name) throws EngineException {
6206: return getParameterLong(name, ElementInfo.DEFAULT_LONG);
6207: }
6208:
6209: /**
6210: * Retrieves the value of a parameter and converts it to a long, using a
6211: * default value if no parameter value is present.
6212: *
6213: * @param name the name of the parameter
6214: * @param defaultValue the default value that will be used when no
6215: * parameter value is present
6216: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6217: * parameter is known with this name; or if you don't have access to the
6218: * request data (eg. you're inside a child trigger); or if there's no
6219: * active element context (eg. you're using this method inside the
6220: * constructor instead of inside the {@link #initialize()} method)
6221: * @return the converted parameter value; or
6222: * <p>the default value if no parameter value is present
6223: * @see #getNamedSubmissionBean(String, String)
6224: * @see #getSubmissionBean(String, Class, String)
6225: * @see #fillSubmissionBean(String, Object, String)
6226: * @see #hasParameterValue(String)
6227: * @see #isParameterEmpty(String)
6228: * @see #getParameter(String)
6229: * @see #getParameter(String, String)
6230: * @see #getParameterValues(String)
6231: * @see #getParameterNames()
6232: * @see #getParameterNames(String)
6233: * @since 1.0
6234: */
6235: public long getParameterLong(String name, long defaultValue)
6236: throws EngineException {
6237: String value = getParameter(name);
6238: if (value == null) {
6239: return defaultValue;
6240: }
6241: try {
6242: return Long.parseLong(value);
6243: } catch (NumberFormatException e) {
6244: return defaultValue;
6245: }
6246: }
6247:
6248: /**
6249: * Retrieves the value of a parameter and converts it to a double.
6250: *
6251: * @param name the name of the parameter
6252: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6253: * parameter is known with this name; or if you don't have access to the
6254: * request data (eg. you're inside a child trigger); or if there's no
6255: * active element context (eg. you're using this method inside the
6256: * constructor instead of inside the {@link #initialize()} method)
6257: * @return the converted parameter value; or
6258: * <p><code>0.0d</code> if no parameter value is present or if the
6259: * parameter value is not a valid double
6260: * @see #getNamedSubmissionBean(String, String)
6261: * @see #getSubmissionBean(String, Class, String)
6262: * @see #fillSubmissionBean(String, Object, String)
6263: * @see #hasParameterValue(String)
6264: * @see #isParameterEmpty(String)
6265: * @see #getParameter(String)
6266: * @see #getParameter(String, String)
6267: * @see #getParameterValues(String)
6268: * @see #getParameterNames()
6269: * @see #getParameterNames(String)
6270: * @since 1.0
6271: */
6272: public double getParameterDouble(String name)
6273: throws EngineException {
6274: return getParameterDouble(name, ElementInfo.DEFAULT_DOUBLE);
6275: }
6276:
6277: /**
6278: * Retrieves the value of a parameter and converts it to a double, using a
6279: * default value if no parameter value is present.
6280: *
6281: * @param name the name of the parameter
6282: * @param defaultValue the default value that will be used when no
6283: * parameter value is present
6284: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6285: * parameter is known with this name; or if you don't have access to the
6286: * request data (eg. you're inside a child trigger); or if there's no
6287: * active element context (eg. you're using this method inside the
6288: * constructor instead of inside the {@link #initialize()} method)
6289: * @return the converted parameter value; or
6290: * <p>the default value if no parameter value is present
6291: * @see #getNamedSubmissionBean(String, String)
6292: * @see #getSubmissionBean(String, Class, String)
6293: * @see #fillSubmissionBean(String, Object, String)
6294: * @see #hasParameterValue(String)
6295: * @see #isParameterEmpty(String)
6296: * @see #getParameter(String)
6297: * @see #getParameter(String, String)
6298: * @see #getParameterValues(String)
6299: * @see #getParameterNames()
6300: * @see #getParameterNames(String)
6301: * @since 1.0
6302: */
6303: public double getParameterDouble(String name, double defaultValue)
6304: throws EngineException {
6305: String value = getParameter(name);
6306: if (value == null) {
6307: return defaultValue;
6308: }
6309: try {
6310: return Double.parseDouble(value);
6311: } catch (NumberFormatException e) {
6312: return defaultValue;
6313: }
6314: }
6315:
6316: /**
6317: * Retrieves the value of a parameter and converts it to a float.
6318: *
6319: * @param name the name of the parameter
6320: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6321: * parameter is known with this name; or if you don't have access to the
6322: * request data (eg. you're inside a child trigger); or if there's no
6323: * active element context (eg. you're using this method inside the
6324: * constructor instead of inside the {@link #initialize()} method)
6325: * @return the converted parameter value; or
6326: * <p><code>0.0f</code> if no parameter value is present or if the
6327: * parameter value is not a valid float
6328: * @see #getNamedSubmissionBean(String, String)
6329: * @see #getSubmissionBean(String, Class, String)
6330: * @see #fillSubmissionBean(String, Object, String)
6331: * @see #hasParameterValue(String)
6332: * @see #isParameterEmpty(String)
6333: * @see #getParameter(String)
6334: * @see #getParameter(String, String)
6335: * @see #getParameterValues(String)
6336: * @see #getParameterNames()
6337: * @see #getParameterNames(String)
6338: * @since 1.0
6339: */
6340: public float getParameterFloat(String name) throws EngineException {
6341: return getParameterFloat(name, ElementInfo.DEFAULT_FLOAT);
6342: }
6343:
6344: /**
6345: * Retrieves the value of a parameter and converts it to a float, using a
6346: * default value if no parameter value is present.
6347: *
6348: * @param name the name of the parameter
6349: * @param defaultValue the default value that will be used when no
6350: * parameter value is present
6351: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6352: * parameter is known with this name; or if you don't have access to the
6353: * request data (eg. you're inside a child trigger); or if there's no
6354: * active element context (eg. you're using this method inside the
6355: * constructor instead of inside the {@link #initialize()} method)
6356: * @return the converted parameter value; or
6357: * <p>the default value if no parameter value is present
6358: * @see #getNamedSubmissionBean(String, String)
6359: * @see #getSubmissionBean(String, Class, String)
6360: * @see #fillSubmissionBean(String, Object, String)
6361: * @see #hasParameterValue(String)
6362: * @see #isParameterEmpty(String)
6363: * @see #getParameter(String)
6364: * @see #getParameter(String, String)
6365: * @see #getParameterValues(String)
6366: * @see #getParameterNames()
6367: * @see #getParameterNames(String)
6368: * @since 1.0
6369: */
6370: public float getParameterFloat(String name, float defaultValue)
6371: throws EngineException {
6372: String value = getParameter(name);
6373: if (value == null) {
6374: return defaultValue;
6375: }
6376: try {
6377: return Float.parseFloat(value);
6378: } catch (NumberFormatException e) {
6379: return defaultValue;
6380: }
6381: }
6382:
6383: /**
6384: * Retrieves the values of a parameter as an array of integers.
6385: *
6386: * @param name the name of the parameter
6387: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6388: * parameter is known with this name; or if you don't have access to the
6389: * request data (eg. you're inside a child trigger); or if there's no
6390: * active element context (eg. you're using this method inside the
6391: * constructor instead of inside the {@link #initialize()} method)
6392: * @return a integer array with all the parameter values; or
6393: * <p><code>null</code> if no parameter values are present
6394: * @see #getNamedSubmissionBean(String, String)
6395: * @see #getSubmissionBean(String, Class, String)
6396: * @see #fillSubmissionBean(String, Object, String)
6397: * @see #hasParameterValue(String)
6398: * @see #isParameterEmpty(String)
6399: * @see #getParameter(String)
6400: * @see #getParameter(String, String)
6401: * @see #getParameterValues(String)
6402: * @see #getParameterNames()
6403: * @see #getParameterNames(String)
6404: * @since 1.0
6405: */
6406: public int[] getParameterIntValues(String name)
6407: throws EngineException {
6408: if (!mRequestAccessEnabled)
6409: throw new RequestAccessDeniedException();
6410: if (null == mElementContext)
6411: throw new ElementContextMissingException();
6412:
6413: if (null == name)
6414: throw new IllegalArgumentException("name can't be null.");
6415: if (0 == name.length())
6416: throw new IllegalArgumentException("name can't be empty.");
6417:
6418: return ArrayUtils.createIntArray(mElementContext
6419: .getParameterValues(name));
6420: }
6421:
6422: /**
6423: * Retrieves the values of a parameter as an array of longs.
6424: *
6425: * @param name the name of the parameter
6426: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6427: * parameter is known with this name; or if you don't have access to the
6428: * request data (eg. you're inside a child trigger); or if there's no
6429: * active element context (eg. you're using this method inside the
6430: * constructor instead of inside the {@link #initialize()} method)
6431: * @return a long array with all the parameter values; or
6432: * <p><code>null</code> if no parameter values are present
6433: * @see #getNamedSubmissionBean(String, String)
6434: * @see #getSubmissionBean(String, Class, String)
6435: * @see #fillSubmissionBean(String, Object, String)
6436: * @see #hasParameterValue(String)
6437: * @see #isParameterEmpty(String)
6438: * @see #getParameter(String)
6439: * @see #getParameter(String, String)
6440: * @see #getParameterValues(String)
6441: * @see #getParameterNames()
6442: * @see #getParameterNames(String)
6443: * @since 1.0
6444: */
6445: public long[] getParameterLongValues(String name)
6446: throws EngineException {
6447: if (!mRequestAccessEnabled)
6448: throw new RequestAccessDeniedException();
6449: if (null == mElementContext)
6450: throw new ElementContextMissingException();
6451:
6452: if (null == name)
6453: throw new IllegalArgumentException("name can't be null.");
6454: if (0 == name.length())
6455: throw new IllegalArgumentException("name can't be empty.");
6456:
6457: return ArrayUtils.createLongArray(mElementContext
6458: .getParameterValues(name));
6459: }
6460:
6461: /**
6462: * Retrieves the values of a parameter as an array of floats.
6463: *
6464: * @param name the name of the parameter
6465: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6466: * parameter is known with this name; or if you don't have access to the
6467: * request data (eg. you're inside a child trigger); or if there's no
6468: * active element context (eg. you're using this method inside the
6469: * constructor instead of inside the {@link #initialize()} method)
6470: * @return a float array with all the parameter values; or
6471: * <p><code>null</code> if no parameter values are present
6472: * @see #getNamedSubmissionBean(String, String)
6473: * @see #getSubmissionBean(String, Class, String)
6474: * @see #fillSubmissionBean(String, Object, String)
6475: * @see #hasParameterValue(String)
6476: * @see #isParameterEmpty(String)
6477: * @see #getParameter(String)
6478: * @see #getParameter(String, String)
6479: * @see #getParameterValues(String)
6480: * @see #getParameterNames()
6481: * @see #getParameterNames(String)
6482: * @since 1.0
6483: */
6484: public float[] getParameterFloatValues(String name)
6485: throws EngineException {
6486: if (!mRequestAccessEnabled)
6487: throw new RequestAccessDeniedException();
6488: if (null == mElementContext)
6489: throw new ElementContextMissingException();
6490:
6491: if (null == name)
6492: throw new IllegalArgumentException("name can't be null.");
6493: if (0 == name.length())
6494: throw new IllegalArgumentException("name can't be empty.");
6495:
6496: return ArrayUtils.createFloatArray(mElementContext
6497: .getParameterValues(name));
6498: }
6499:
6500: /**
6501: * Retrieves the values of a parameter as an array of doubles.
6502: *
6503: * @param name the name of the parameter
6504: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6505: * parameter is known with this name; or if you don't have access to the
6506: * request data (eg. you're inside a child trigger); or if there's no
6507: * active element context (eg. you're using this method inside the
6508: * constructor instead of inside the {@link #initialize()} method)
6509: * @return a double array with all the parameter values; or
6510: * <p><code>null</code> if no parameter values are present
6511: * @see #getNamedSubmissionBean(String, String)
6512: * @see #getSubmissionBean(String, Class, String)
6513: * @see #fillSubmissionBean(String, Object, String)
6514: * @see #hasParameterValue(String)
6515: * @see #isParameterEmpty(String)
6516: * @see #getParameter(String)
6517: * @see #getParameter(String, String)
6518: * @see #getParameterValues(String)
6519: * @see #getParameterNames()
6520: * @see #getParameterNames(String)
6521: * @since 1.0
6522: */
6523: public double[] getParameterDoubleValues(String name)
6524: throws EngineException {
6525: if (!mRequestAccessEnabled)
6526: throw new RequestAccessDeniedException();
6527: if (null == mElementContext)
6528: throw new ElementContextMissingException();
6529:
6530: if (null == name)
6531: throw new IllegalArgumentException("name can't be null.");
6532: if (0 == name.length())
6533: throw new IllegalArgumentException("name can't be empty.");
6534:
6535: return ArrayUtils.createDoubleArray(mElementContext
6536: .getParameterValues(name));
6537: }
6538:
6539: /**
6540: * Retrieves the names of all the files that are present and that
6541: * match a regular expression.
6542: *
6543: * @param regexp the regular expression that will be used to filter the
6544: * file names
6545: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
6546: * have access to the request data (eg. you're inside a child trigger); or
6547: * if there's no active element context (eg. you're using this method
6548: * inside the constructor instead of inside the {@link #initialize()}
6549: * method)
6550: * @return the list with the file names
6551: * @see #getUploadedFileNames()
6552: * @see #hasUploadedFile(String)
6553: * @see #isFileEmpty(String)
6554: * @see #getUploadedFile(String)
6555: * @see #getUploadedFiles(String)
6556: * @since 1.1
6557: */
6558: public ArrayList<String> getUploadedFileNames(String regexp)
6559: throws EngineException {
6560: if (!mRequestAccessEnabled)
6561: throw new RequestAccessDeniedException();
6562: if (null == mElementContext)
6563: throw new ElementContextMissingException();
6564:
6565: return mElementContext.getUploadedFileNames(regexp);
6566: }
6567:
6568: /**
6569: * Retrieves the list of uploaded file names.
6570: *
6571: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
6572: * have access to the request data (eg. you're inside a child trigger); or
6573: * if there's no active element context (eg. you're using this method
6574: * inside the constructor instead of inside the {@link #initialize()}
6575: * method)
6576: * @return the list of uploaded file names
6577: * @see #getUploadedFileNames(String)
6578: * @see #hasUploadedFile(String)
6579: * @see #isFileEmpty(String)
6580: * @see #getUploadedFile(String)
6581: * @see #getUploadedFiles(String)
6582: * @since 1.0
6583: */
6584: public ArrayList<String> getUploadedFileNames()
6585: throws EngineException {
6586: if (!mRequestAccessEnabled)
6587: throw new RequestAccessDeniedException();
6588: if (null == mElementContext)
6589: throw new ElementContextMissingException();
6590:
6591: return mElementContext.getUploadedFileNames();
6592: }
6593:
6594: /**
6595: * Checks if a particular file has been uploaded during the last
6596: * submission.
6597: *
6598: * @param name the name of the file, as declared in the submission
6599: * @exception com.uwyn.rife.engine.exceptions.EngineException if no file
6600: * is known with this name; or if you don't have access to the request
6601: * data (eg. you're inside a child trigger); or if there's no active
6602: * element context (eg. you're using this method inside the constructor
6603: * instead of inside the {@link #initialize()} method)
6604: * @return <code>true</code> if the file was uploaded; or
6605: * <p><code>false</code> otherwise
6606: * @see #getUploadedFileNames(String)
6607: * @see #getUploadedFileNames()
6608: * @see #isFileEmpty(String)
6609: * @see #getUploadedFile(String)
6610: * @see #getUploadedFiles(String)
6611: * @since 1.0
6612: */
6613: public boolean hasUploadedFile(String name) throws EngineException {
6614: if (!mRequestAccessEnabled)
6615: throw new RequestAccessDeniedException();
6616: if (null == mElementContext)
6617: throw new ElementContextMissingException();
6618:
6619: if (null == name)
6620: throw new IllegalArgumentException("name can't be null.");
6621: if (0 == name.length())
6622: throw new IllegalArgumentException("name can't be empty.");
6623:
6624: return mElementContext.hasUploadedFile(name);
6625: }
6626:
6627: /**
6628: * Checks if an uploaded file wasn't sent or if it is empty.
6629: *
6630: * @param name the name of the file, as declared in the submission
6631: * @exception com.uwyn.rife.engine.exceptions.EngineException if no file
6632: * is known with this name; or if you don't have access to the request
6633: * data (eg. you're inside a child trigger); or if there's no active
6634: * element context (eg. you're using this method inside the constructor
6635: * instead of inside the {@link #initialize()} method)
6636: * @return <code>true</code> if the file wasn't uploaded or empty; or
6637: * <p>false otherwise
6638: * @see #getUploadedFileNames(String)
6639: * @see #getUploadedFileNames()
6640: * @see #hasUploadedFile(String)
6641: * @see #getUploadedFile(String)
6642: * @see #getUploadedFiles(String)
6643: * @since 1.0
6644: */
6645: public boolean isFileEmpty(String name) throws EngineException {
6646: if (!mRequestAccessEnabled)
6647: throw new RequestAccessDeniedException();
6648: if (null == mElementContext)
6649: throw new ElementContextMissingException();
6650:
6651: if (null == name)
6652: throw new IllegalArgumentException("name can't be null.");
6653: if (0 == name.length())
6654: throw new IllegalArgumentException("name can't be empty.");
6655:
6656: return mElementContext.isFileEmpty(name);
6657: }
6658:
6659: /**
6660: * Retrieves an uploaded file.
6661: *
6662: * @param name the name of the file, as declared in the submission
6663: * @exception com.uwyn.rife.engine.exceptions.EngineException if no file
6664: * is known with this name; or if you don't have access to the request
6665: * data (eg. you're inside a child trigger); or if there's no active
6666: * element context (eg. you're using this method inside the constructor
6667: * instead of inside the {@link #initialize()} method)
6668: * @return the uploaded file; or
6669: * <p><code>null</code> if no file was uploaded
6670: * @see #getUploadedFileNames(String)
6671: * @see #getUploadedFileNames()
6672: * @see #hasUploadedFile(String)
6673: * @see #isFileEmpty(String)
6674: * @see #getUploadedFiles(String)
6675: * @since 1.0
6676: */
6677: public UploadedFile getUploadedFile(String name)
6678: throws EngineException {
6679: if (!mRequestAccessEnabled)
6680: throw new RequestAccessDeniedException();
6681: if (null == mElementContext)
6682: throw new ElementContextMissingException();
6683:
6684: if (null == name)
6685: throw new IllegalArgumentException("name can't be null.");
6686: if (0 == name.length())
6687: throw new IllegalArgumentException("name can't be empty.");
6688:
6689: return mElementContext.getUploadedFile(name);
6690: }
6691:
6692: /**
6693: * Retrieves all files that have been uploaded for a particular name.
6694: *
6695: * @param name the name of the file, as declared in the submission
6696: * @exception com.uwyn.rife.engine.exceptions.EngineException if no file
6697: * is known with this name; or if you don't have access to the request
6698: * data (eg. you're inside a child trigger); or if there's no active
6699: * element context (eg. you're using this method inside the constructor
6700: * instead of inside the {@link #initialize()} method)
6701: * @return the uploaded files; or
6702: * <p><code>null</code> if no files were uploaded for that name
6703: * @see #getUploadedFileNames(String)
6704: * @see #getUploadedFileNames()
6705: * @see #hasUploadedFile(String)
6706: * @see #isFileEmpty(String)
6707: * @see #getUploadedFile(String)
6708: * @since 1.0
6709: */
6710: public UploadedFile[] getUploadedFiles(String name)
6711: throws EngineException {
6712: if (!mRequestAccessEnabled)
6713: throw new RequestAccessDeniedException();
6714: if (null == mElementContext)
6715: throw new ElementContextMissingException();
6716:
6717: if (null == name)
6718: throw new IllegalArgumentException("name can't be null.");
6719: if (0 == name.length())
6720: throw new IllegalArgumentException("name can't be empty.");
6721:
6722: return mElementContext.getUploadedFiles(name);
6723: }
6724:
6725: /**
6726: * Generates a query URL for a submission.
6727: *
6728: * @param name the name of the submission
6729: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6730: * submission is known with this name; if you don't have access to the
6731: * request data (eg. you're inside a child trigger); or if there's no
6732: * active element context (eg. you're using this method inside the
6733: * constructor instead of inside the {@link #initialize()} method)
6734: * @return the generated URL as a character sequence
6735: * @see #getSubmissionQueryUrl(String, String, String[])
6736: * @see #getSubmissionFormUrl(String)
6737: * @see #getSubmissionFormParameters(String, String[])
6738: * @see #setSubmissionQuery(Template, String, String, String[])
6739: * @see #setSubmissionForm(Template, String, String)
6740: * @since 1.0
6741: */
6742: public CharSequence getSubmissionQueryUrl(String name)
6743: throws EngineException {
6744: return getSubmissionQueryUrl(name, null, null);
6745: }
6746:
6747: /**
6748: * Generates a query URL for a submission and appends a pathinfo to the
6749: * URL of the element.
6750: *
6751: * @param name the name of the submission
6752: * @param pathinfo the pathinfo that will be appended; or
6753: * <code>null</code> if no pathinfo should be appended
6754: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6755: * submission is known with this name; if you don't have access to the
6756: * request data (eg. you're inside a child trigger); or if there's no
6757: * active element context (eg. you're using this method inside the
6758: * constructor instead of inside the {@link #initialize()} method)
6759: * @return the generated URL as a character sequence
6760: * @see #getSubmissionQueryUrl(String, String, String[])
6761: * @see #getSubmissionFormUrl(String)
6762: * @see #getSubmissionFormParameters(String, String[])
6763: * @see #setSubmissionQuery(Template, String, String, String[])
6764: * @see #setSubmissionForm(Template, String, String)
6765: * @since 1.0
6766: */
6767: public CharSequence getSubmissionQueryUrl(String name,
6768: String pathinfo) throws EngineException {
6769: return getSubmissionQueryUrl(name, pathinfo, null);
6770: }
6771:
6772: /**
6773: * Generates a query URL for a submission with default parameter values.
6774: *
6775: * @param name the name of the submission
6776: * @param parameterValues an array of string pairs that will be used to
6777: * set default parameter values; or <code>null</code> if no default
6778: * parameter values should be used
6779: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6780: * submission is known with this name; if you don't have access to the
6781: * request data (eg. you're inside a child trigger); or if there's no
6782: * active element context (eg. you're using this method inside the
6783: * constructor instead of inside the {@link #initialize()} method)
6784: * @return the generated URL as a character sequence
6785: * @see #getSubmissionQueryUrl(String, String, String[])
6786: * @see #getSubmissionFormUrl(String)
6787: * @see #getSubmissionFormParameters(String, String[])
6788: * @see #setSubmissionQuery(Template, String, String, String[])
6789: * @see #setSubmissionForm(Template, String, String)
6790: * @since 1.0
6791: */
6792: public CharSequence getSubmissionQueryUrl(String name,
6793: String[] parameterValues) throws EngineException {
6794: return getSubmissionQueryUrl(name, null, parameterValues);
6795: }
6796:
6797: /**
6798: * Generates a query URL for a submission and appends a pathinfo to the
6799: * URL of the element, default parameter values can also be added.
6800: * <p>This will take the current element context into account with the
6801: * available inputs, global variables, ... and generate an URL that
6802: * persists the data state according to the declared site structure.
6803: * <p>The default parameter values are provided as an array of strings
6804: * that should be structured in pairs. For example, if these output values
6805: * should be used: <code>param1</code>:<code>value1</code> and
6806: * <code>param2</code>:<code>value2</code>, you should define the
6807: * following string array:
6808: * <pre>new String[] {"param1", "value1", "param2", "value2"}</pre>
6809: * <p>The generated URL with not contain a scheme, host or port. It will
6810: * begin with the path part and be absolute, starting with the web
6811: * application's root URL.
6812: *
6813: * @param name the name of the submission
6814: * @param pathinfo the pathinfo that will be appended; or
6815: * <code>null</code> if no pathinfo should be appended
6816: * @param parameterValues an array of string pairs that will be used to
6817: * set default parameter values; or <code>null</code> if no default
6818: * parameter values should be used
6819: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6820: * submission is known with this name; if you don't have access to the
6821: * request data (eg. you're inside a child trigger); or if there's no
6822: * active element context (eg. you're using this method inside the
6823: * constructor instead of inside the {@link #initialize()} method)
6824: * @return the generated URL as a character sequence
6825: * @see #getSubmissionFormUrl(String)
6826: * @see #getSubmissionFormParameters(String, String[])
6827: * @see #setSubmissionQuery(Template, String, String, String[])
6828: * @see #setSubmissionForm(Template, String, String)
6829: * @since 1.0
6830: */
6831: public CharSequence getSubmissionQueryUrl(String name,
6832: String pathinfo, String[] parameterValues)
6833: throws EngineException {
6834: if (!mRequestAccessEnabled)
6835: throw new RequestAccessDeniedException();
6836: if (null == mElementContext)
6837: throw new ElementContextMissingException();
6838:
6839: if (null == name)
6840: throw new IllegalArgumentException("name can't be null.");
6841: if (0 == name.length())
6842: throw new IllegalArgumentException("name can't be empty.");
6843: if (null != parameterValues && parameterValues.length % 2 > 0)
6844: throw new IllegalArgumentException(
6845: "parameterValues should be a series of key/value pairs.");
6846:
6847: return mElementContext.getSubmissionQueryUrl(name, pathinfo,
6848: parameterValues);
6849: }
6850:
6851: /**
6852: * Generates a form action URL for a submission.
6853: *
6854: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
6855: * have access to the request data (eg. you're inside a child trigger); or
6856: * if there's no active element context (eg. you're using this method
6857: * inside the constructor instead of inside the {@link #initialize()}
6858: * method)
6859: * @return the generated URL as a character sequence
6860: * @see #getSubmissionQueryUrl(String, String, String[])
6861: * @see #getSubmissionFormUrl(String)
6862: * @see #getSubmissionFormParameters(String, String[])
6863: * @see #setSubmissionQuery(Template, String, String, String[])
6864: * @see #setSubmissionForm(Template, String, String)
6865: * @since 1.0
6866: */
6867: public CharSequence getSubmissionFormUrl() throws EngineException {
6868: return getSubmissionFormUrl(null);
6869: }
6870:
6871: /**
6872: * Generates a form action URL for a submission and appends a pathinfo to
6873: * the URL of the element.
6874: * <p>This will take the current element context into account with the
6875: * available inputs, global variables, ... and generate an URL that
6876: * persists the data state according to the declared site structure.
6877: * <p>The generated URL with not contain a scheme, host or port. It will
6878: * begin with the path part and be absolute, starting with the web
6879: * application's root URL.
6880: * <p>This method goes together with the {@link
6881: * #getSubmissionFormParameters(String, String[])} method since the state
6882: * is tranferred as hidden form parameters that are part of the form.
6883: *
6884: * @param pathinfo the pathinfo that will be appended; or
6885: * <code>null</code> if no pathinfo should be appended
6886: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
6887: * have access to the request data (eg. you're inside a child trigger); or
6888: * if there's no active element context (eg. you're using this method
6889: * inside the constructor instead of inside the {@link #initialize()}
6890: * method)
6891: * @return the generated URL as a character sequence
6892: * @see #getSubmissionQueryUrl(String, String, String[])
6893: * @see #getSubmissionFormParameters(String, String[])
6894: * @see #setSubmissionQuery(Template, String, String, String[])
6895: * @see #setSubmissionForm(Template, String, String)
6896: * @since 1.0
6897: */
6898: public CharSequence getSubmissionFormUrl(String pathinfo)
6899: throws EngineException {
6900: if (!mRequestAccessEnabled)
6901: throw new RequestAccessDeniedException();
6902: if (null == mElementContext)
6903: throw new ElementContextMissingException();
6904:
6905: return mElementContext.getSubmissionFormUrl(pathinfo);
6906: }
6907:
6908: /**
6909: * Generates the hidden XHTML form parameters for a submission.
6910: *
6911: * @param name the name of the submission
6912: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6913: * submission is known with this name; if you don't have access to the
6914: * request data (eg. you're inside a child trigger); or if there's no
6915: * active element context (eg. you're using this method inside the
6916: * constructor instead of inside the {@link #initialize()} method)
6917: * @return the generated parameters as a character sequence
6918: * @see #getSubmissionQueryUrl(String, String, String[])
6919: * @see #getSubmissionFormUrl(String)
6920: * @see #getSubmissionFormParameters(String, String[])
6921: * @see #setSubmissionQuery(Template, String, String, String[])
6922: * @see #setSubmissionForm(Template, String, String)
6923: * @since 1.0
6924: */
6925: public CharSequence getSubmissionFormParameters(String name)
6926: throws EngineException {
6927: return getSubmissionFormParameters(name, null);
6928: }
6929:
6930: /**
6931: * Generates the hidden XHTML form parameters for a submission and
6932: * overrides the current output values only for this method.
6933: * <p>This will take the current element context into account with the
6934: * available inputs, global variables, ... and generate hidden XHTML form
6935: * parameters that persist the data state according to the declared site
6936: * structure.
6937: * <p>The default parameter values are provided as an array of strings
6938: * that should be structured in pairs. For example, if these output values
6939: * should be used: <code>param1</code>:<code>value1</code> and
6940: * <code>param2</code>:<code>value2</code>, you should define the
6941: * following string array:
6942: * <pre>new String[] {"param1", "value1", "param2", "value2"}</pre>
6943: * <p>This method goes together with the {@link
6944: * #getSubmissionFormUrl(String)} method since the URL needs to be
6945: * provided in the action attribute of the form.
6946: *
6947: * @param name the name of the submission
6948: * @param parameterValues an array of string pairs that will be used to
6949: * set default parameter values; or <code>null</code> if no default
6950: * parameter values should be used
6951: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
6952: * submission is known with this name; if you don't have access to the
6953: * request data (eg. you're inside a child trigger); or if there's no
6954: * active element context (eg. you're using this method inside the
6955: * constructor instead of inside the {@link #initialize()} method)
6956: * @return the generated parameters as a character sequence
6957: * @see #getSubmissionQueryUrl(String, String, String[])
6958: * @see #getSubmissionFormUrl(String)
6959: * @see #getSubmissionFormParametersJavascript(String, String[])
6960: * @see #setSubmissionQuery(Template, String, String, String[])
6961: * @see #setSubmissionForm(Template, String, String)
6962: * @since 1.0
6963: */
6964: public CharSequence getSubmissionFormParameters(String name,
6965: String[] parameterValues) throws EngineException {
6966: if (!mRequestAccessEnabled)
6967: throw new RequestAccessDeniedException();
6968: if (null == mElementContext)
6969: throw new ElementContextMissingException();
6970:
6971: if (null == name)
6972: throw new IllegalArgumentException("name can't be null.");
6973: if (0 == name.length())
6974: throw new IllegalArgumentException("name can't be empty.");
6975: if (null != parameterValues && parameterValues.length % 2 > 0)
6976: throw new IllegalArgumentException(
6977: "parameterValues should be a series of key/value pairs.");
6978:
6979: return mElementContext.getSubmissionFormParameters(name,
6980: parameterValues);
6981: }
6982:
6983: /**
6984: * Generates Javascript that will generate hidden XHTML form parameters for
6985: * a submission and overrides the current output values only for this method.
6986: * <p>This will take the current element context into account with the
6987: * available inputs, global variables, ... and generate hidden XHTML form
6988: * parameters that persist the data state according to the declared site
6989: * structure.
6990: * <p>The default parameter values are provided as an array of strings
6991: * that should be structured in pairs. For example, if these output values
6992: * should be used: <code>param1</code>:<code>value1</code> and
6993: * <code>param2</code>:<code>value2</code>, you should define the
6994: * following string array:
6995: * <pre>new String[] {"param1", "value1", "param2", "value2"}</pre>
6996: * <p>This method goes together with the {@link
6997: * #getSubmissionFormUrl(String)} method since the URL needs to be
6998: * provided in the action attribute of the form.
6999: *
7000: * @param name the name of the submission
7001: * @param parameterValues an array of string pairs that will be used to
7002: * set default parameter values; or <code>null</code> if no default
7003: * parameter values should be used
7004: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
7005: * submission is known with this name; if you don't have access to the
7006: * request data (eg. you're inside a child trigger); or if there's no
7007: * active element context (eg. you're using this method inside the
7008: * constructor instead of inside the {@link #initialize()} method)
7009: * @return the generated parameters as a character sequence
7010: * @see #getSubmissionQueryUrl(String, String, String[])
7011: * @see #getSubmissionFormUrl(String)
7012: * @see #getSubmissionFormParameters(String, String[])
7013: * @see #setSubmissionQuery(Template, String, String, String[])
7014: * @see #setSubmissionForm(Template, String, String)
7015: * @since 1.6
7016: */
7017: public CharSequence getSubmissionFormParametersJavascript(
7018: String name, String[] parameterValues)
7019: throws EngineException {
7020: if (!mRequestAccessEnabled)
7021: throw new RequestAccessDeniedException();
7022: if (null == mElementContext)
7023: throw new ElementContextMissingException();
7024:
7025: if (null == name)
7026: throw new IllegalArgumentException("name can't be null.");
7027: if (0 == name.length())
7028: throw new IllegalArgumentException("name can't be empty.");
7029: if (null != parameterValues && parameterValues.length % 2 > 0)
7030: throw new IllegalArgumentException(
7031: "parameterValues should be a series of key/value pairs.");
7032:
7033: return mElementContext.getSubmissionFormParametersJavascript(
7034: name, parameterValues);
7035: }
7036:
7037: /**
7038: * Generates a query URL for a submission sets it as the content of a
7039: * template value.
7040: *
7041: * @param template the template that will be used to set the value
7042: * @param name the name of the submission
7043: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
7044: * template doesn't contain the value identifier
7045: * <code>SUBMISSION:QUERY:submissionname</code>
7046: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
7047: * submission is known with this name; if you don't have access to the
7048: * request data (eg. you're inside a child trigger); or if there's no
7049: * active element context (eg. you're using this method inside the
7050: * constructor instead of inside the {@link #initialize()} method)
7051: * @see #getSubmissionQueryUrl(String, String, String[])
7052: * @see #getSubmissionFormUrl(String)
7053: * @see #getSubmissionFormParameters(String, String[])
7054: * @see #setSubmissionQuery(Template, String, String, String[])
7055: * @see #setSubmissionForm(Template, String, String)
7056: * @since 1.0
7057: */
7058: public void setSubmissionQuery(Template template, String name)
7059: throws TemplateException, EngineException {
7060: setSubmissionQuery(template, name, null, null);
7061: }
7062:
7063: /**
7064: * Generates a query URL for a submission with a pathinfo and sets it as
7065: * the content of a template value.
7066: *
7067: * @param template the template that will be used to set the value
7068: * @param name the name of the submission
7069: * @param pathinfo the pathinfo that will be appended; or
7070: * <code>null</code> if no pathinfo should be appended
7071: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
7072: * template doesn't contain the value identifier
7073: * <code>SUBMISSION:QUERY:submissionname</code>
7074: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
7075: * submission is known with this name; if you don't have access to the
7076: * request data (eg. you're inside a child trigger); or if there's no
7077: * active element context (eg. you're using this method inside the
7078: * constructor instead of inside the {@link #initialize()} method)
7079: * @see #getSubmissionQueryUrl(String, String, String[])
7080: * @see #getSubmissionFormUrl(String)
7081: * @see #getSubmissionFormParameters(String, String[])
7082: * @see #setSubmissionQuery(Template, String, String, String[])
7083: * @see #setSubmissionForm(Template, String, String)
7084: * @since 1.0
7085: */
7086: public void setSubmissionQuery(Template template, String name,
7087: String pathinfo) throws TemplateException, EngineException {
7088: setSubmissionQuery(template, name, pathinfo, null);
7089: }
7090:
7091: /**
7092: * Generates a query URL for a submission with default parameter values
7093: * and sets it as the content of a template value.
7094: *
7095: * @param template the template that will be used to set the value
7096: * @param name the name of the submission
7097: * @param parameterValues an array of string pairs that will be used to
7098: * set default parameter values; or <code>null</code> if no default
7099: * parameter values should be used
7100: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
7101: * template doesn't contain the value identifier
7102: * <code>SUBMISSION:QUERY:submissionname</code>
7103: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
7104: * submission is known with this name; if you don't have access to the
7105: * request data (eg. you're inside a child trigger); or if there's no
7106: * active element context (eg. you're using this method inside the
7107: * constructor instead of inside the {@link #initialize()} method)
7108: * @see #getSubmissionQueryUrl(String, String, String[])
7109: * @see #getSubmissionFormUrl(String)
7110: * @see #getSubmissionFormParameters(String, String[])
7111: * @see #setSubmissionQuery(Template, String, String, String[])
7112: * @see #setSubmissionForm(Template, String, String)
7113: * @since 1.0
7114: */
7115: public void setSubmissionQuery(Template template, String name,
7116: String[] parameterValues) throws TemplateException,
7117: EngineException {
7118: setSubmissionQuery(template, name, null, parameterValues);
7119: }
7120:
7121: /**
7122: * Generates a query URL for a submission with pathinfo and default
7123: * parameter values and sets it as the content of a template value.
7124: * <p>The URL will be generated by calling the {@link
7125: * #getSubmissionQueryUrl(String, String, String[])} method and it will be
7126: * set to the value identifier with the syntax
7127: * <code>SUBMISSION:QUERY:submissionname</code>.
7128: * <p>Template content that is outputted with the
7129: * <code>#print(Template)</code> method will automatically be scanned for
7130: * value identifiers with this syntax and the submission query URLs will
7131: * generated. You should only use this method if you need a submission URL
7132: * to be generated in a certain context.
7133: *
7134: * @param template the template that will be used to set the value
7135: * @param name the name of the submission
7136: * @param pathinfo the pathinfo that will be appended; or
7137: * <code>null</code> if no pathinfo should be appended
7138: * @param parameterValues an array of string pairs that will be used to
7139: * set default parameter values; or <code>null</code> if no default
7140: * parameter values should be used
7141: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
7142: * template doesn't contain the value identifier
7143: * <code>SUBMISSION:QUERY:submissionname</code>
7144: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
7145: * submission is known with this name; if you don't have access to the
7146: * request data (eg. you're inside a child trigger); or if there's no
7147: * active element context (eg. you're using this method inside the
7148: * constructor instead of inside the {@link #initialize()} method)
7149: * @see #getSubmissionQueryUrl(String, String, String[])
7150: * @see #getSubmissionFormUrl(String)
7151: * @see #getSubmissionFormParameters(String, String[])
7152: * @see #setSubmissionForm(Template, String, String)
7153: * @since 1.0
7154: */
7155: public void setSubmissionQuery(Template template, String name,
7156: String pathinfo, String[] parameterValues)
7157: throws TemplateException, EngineException {
7158: if (!mRequestAccessEnabled)
7159: throw new RequestAccessDeniedException();
7160: if (null == mElementContext)
7161: throw new ElementContextMissingException();
7162:
7163: if (null == template)
7164: throw new IllegalArgumentException(
7165: "template can't be null.");
7166: if (null == name)
7167: throw new IllegalArgumentException("name can't be null.");
7168: if (0 == name.length())
7169: throw new IllegalArgumentException("name can't be empty.");
7170: if (null != parameterValues && parameterValues.length % 2 > 0)
7171: throw new IllegalArgumentException(
7172: "parameterValues should be a series of key/value pairs.");
7173:
7174: mElementContext.setSubmissionQuery(template, name, pathinfo,
7175: parameterValues);
7176: }
7177:
7178: /**
7179: * Generates a form action URL for an submission and sets it as the
7180: * content of a template value.
7181: *
7182: * @param template the template that will be used to set the value
7183: * @param name the name of the submission
7184: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
7185: * template doesn't contain the value identifiers
7186: * <code>SUBMISSION:FORM:submissionname</code> and
7187: * <code>SUBMISSION:PARAMS:submissionname</code>
7188: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
7189: * is known with this name; if the exit hasn't got a destination element;
7190: * if you don't have access to the request data (eg. you're inside a child
7191: * trigger); or if there's no active element context (eg. you're using
7192: * this method inside the constructor instead of inside the {@link
7193: * #initialize()} method)
7194: * @see #getSubmissionQueryUrl(String, String, String[])
7195: * @see #getSubmissionFormUrl(String)
7196: * @see #getSubmissionFormParameters(String, String[])
7197: * @see #setSubmissionQuery(Template, String, String, String[])
7198: * @see #setSubmissionForm(Template, String, String)
7199: * @since 1.0
7200: */
7201: public void setSubmissionForm(Template template, String name)
7202: throws TemplateException, EngineException {
7203: setSubmissionForm(template, name, null, null);
7204: }
7205:
7206: /**
7207: * Generates a form action URL for an submission with a pathinfo and sets
7208: * it as the content of a template value.
7209: *
7210: * @param template the template that will be used to set the value
7211: * @param name the name of the submission
7212: * @param pathinfo the pathinfo that will be appended; or
7213: * <code>null</code> if no pathinfo should be appended
7214: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
7215: * template doesn't contain the value identifiers
7216: * <code>SUBMISSION:FORM:submissionname</code> and
7217: * <code>SUBMISSION:PARAMS:submissionname</code>
7218: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
7219: * is known with this name; if the exit hasn't got a destination element;
7220: * if you don't have access to the request data (eg. you're inside a child
7221: * trigger); or if there's no active element context (eg. you're using
7222: * this method inside the constructor instead of inside the {@link
7223: * #initialize()} method)
7224: * @see #getSubmissionQueryUrl(String, String, String[])
7225: * @see #getSubmissionFormUrl(String)
7226: * @see #getSubmissionFormParameters(String, String[])
7227: * @see #setSubmissionQuery(Template, String, String, String[])
7228: * @see #setSubmissionForm(Template, String, String)
7229: * @since 1.0
7230: */
7231: public void setSubmissionForm(Template template, String name,
7232: String pathinfo) throws TemplateException, EngineException {
7233: setSubmissionForm(template, name, pathinfo, null);
7234: }
7235:
7236: /**
7237: * Generates a form action URL for an submission with default parameter
7238: * values and sets it as the content of a template value.
7239: *
7240: * @param template the template that will be used to set the value
7241: * @param name the name of the submission
7242: * @param parameterValues an array of string pairs that will be used to
7243: * set default parameter values; or <code>null</code> if no default
7244: * parameter values should be used
7245: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
7246: * template doesn't contain the value identifiers
7247: * <code>SUBMISSION:FORM:submissionname</code> and
7248: * <code>SUBMISSION:PARAMS:submissionname</code>
7249: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
7250: * is known with this name; if the exit hasn't got a destination element;
7251: * if you don't have access to the request data (eg. you're inside a child
7252: * trigger); or if there's no active element context (eg. you're using
7253: * this method inside the constructor instead of inside the {@link
7254: * #initialize()} method)
7255: * @see #getSubmissionQueryUrl(String, String, String[])
7256: * @see #getSubmissionFormUrl(String)
7257: * @see #getSubmissionFormParameters(String, String[])
7258: * @see #setSubmissionQuery(Template, String, String, String[])
7259: * @see #setSubmissionForm(Template, String, String)
7260: * @since 1.0
7261: */
7262: public void setSubmissionForm(Template template, String name,
7263: String[] parameterValues) throws TemplateException,
7264: EngineException {
7265: setSubmissionForm(template, name, null, parameterValues);
7266: }
7267:
7268: /**
7269: * Generates a form action URL for an submission with a pathinfo and
7270: * default parameter values and sets it as the content of a template
7271: * value.
7272: * <p>The URL will be generated by calling the {@link
7273: * #getSubmissionFormUrl(String)} and {@link
7274: * #getSubmissionFormParameters(String, String[])} methods and it will be
7275: * set the results to the value identifiers with the syntax
7276: * <code>SUBMISSION:FORM:submissionname</code> and
7277: * <code>SUBMISSION:PARAMS:submissionname</code>.
7278: * <p>Template content that is outputted with the
7279: * <code>#print(Template)</code> method will automatically be scanned for
7280: * value identifiers with this syntax and the submission forms URLs and
7281: * parameters will generated. You should only use this method if you need
7282: * these to be generated in a certain context.
7283: *
7284: * @param template the template that will be used to set the value
7285: * @param name the name of the submission
7286: * @param pathinfo the pathinfo that will be appended; or
7287: * <code>null</code> if no pathinfo should be appended
7288: * @param parameterValues an array of string pairs that will be used to
7289: * set default parameter values; or <code>null</code> if no default
7290: * parameter values should be used
7291: * @exception com.uwyn.rife.template.exceptions.TemplateException if the
7292: * template doesn't contain the value identifiers
7293: * <code>SUBMISSION:FORM:submissionname</code> and
7294: * <code>SUBMISSION:PARAMS:submissionname</code>
7295: * @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
7296: * is known with this name; if the exit hasn't got a destination element;
7297: * if you don't have access to the request data (eg. you're inside a child
7298: * trigger); or if there's no active element context (eg. you're using
7299: * this method inside the constructor instead of inside the {@link
7300: * #initialize()} method)
7301: * @see #getSubmissionQueryUrl(String, String, String[])
7302: * @see #getSubmissionFormUrl(String)
7303: * @see #getSubmissionFormParameters(String, String[])
7304: * @see #setSubmissionQuery(Template, String, String, String[])
7305: * @since 1.0
7306: */
7307: public void setSubmissionForm(Template template, String name,
7308: String pathinfo, String[] parameterValues)
7309: throws TemplateException, EngineException {
7310: if (!mRequestAccessEnabled)
7311: throw new RequestAccessDeniedException();
7312: if (null == mElementContext)
7313: throw new ElementContextMissingException();
7314:
7315: if (null == template)
7316: throw new IllegalArgumentException(
7317: "template can't be null.");
7318: if (null == name)
7319: throw new IllegalArgumentException("name can't be null.");
7320: if (0 == name.length())
7321: throw new IllegalArgumentException("name can't be empty.");
7322: if (null != parameterValues && parameterValues.length % 2 > 0)
7323: throw new IllegalArgumentException(
7324: "parameterValues should be a series of key/value pairs.");
7325:
7326: mElementContext.setSubmissionForm(template, name, pathinfo,
7327: parameterValues);
7328: }
7329:
7330: /**
7331: * Processes an embedded element without a differentiator in a template.
7332: * <p>Embedded elements are evaluated when value identifiers have the
7333: * following syntax: <code>ELEMENT:elementId</code>.
7334: * <p>All embedded elements are automatically processed when the template
7335: * is instantiated, so this method should only be called if you need to
7336: * re-process an embedded element in a particular context.
7337: *
7338: * @param template the template that will be used to process the embedded
7339: * template
7340: * @param elementId the identifier of the element
7341: * @exception com.uwyn.rife.template.exceptions.TemplateException when an
7342: * error occurs during the template processing
7343: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
7344: * element is known with that identifier; or if you don't have access to
7345: * the request data (eg. you're inside a child trigger); or if there's no
7346: * active element context (eg. you're using this method inside the
7347: * constructor instead of inside the {@link #initialize()} method)
7348: * @see #processEmbeddedElement(Template, String, Object)
7349: * @see #processEmbeddedElement(Template, String, String)
7350: * @see #processEmbeddedElement(Template, String, String, Object)
7351: * @since 1.0
7352: */
7353: public void processEmbeddedElement(Template template,
7354: String elementId) throws TemplateException, EngineException {
7355: if (!mRequestAccessEnabled)
7356: throw new RequestAccessDeniedException();
7357: if (null == mElementContext)
7358: throw new ElementContextMissingException();
7359:
7360: if (null == template)
7361: throw new IllegalArgumentException(
7362: "template can't be null.");
7363: if (null == elementId)
7364: throw new IllegalArgumentException(
7365: "elementId can't be null.");
7366: if (0 == elementId.length())
7367: throw new IllegalArgumentException(
7368: "elementId can't be empty.");
7369:
7370: mElementContext.processEmbeddedElement(template, this ,
7371: elementId, null, null);
7372: }
7373:
7374: /**
7375: * Processes an embedded element without a differentiator in a template
7376: * and pass on data to the processed embedded element.
7377: * <p>See {@link #processEmbeddedElement(Template, String)} for more
7378: * information.
7379: *
7380: * @param template the template that will be used to process the embedded
7381: * template
7382: * @param elementId the identifier of the element
7383: * @param data the data that will be available from within the embedded
7384: * element
7385: * @exception com.uwyn.rife.template.exceptions.TemplateException when an
7386: * error occurs during the template processing
7387: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
7388: * element is known with that identifier; or if you don't have access to
7389: * the request data (eg. you're inside a child trigger); or if there's no
7390: * active element context (eg. you're using this method inside the
7391: * constructor instead of inside the {@link #initialize()} method)
7392: * @see #processEmbeddedElement(Template, String)
7393: * @see #processEmbeddedElement(Template, String, String)
7394: * @see #processEmbeddedElement(Template, String, String, Object)
7395: * @since 1.5
7396: */
7397: public void processEmbeddedElement(Template template,
7398: String elementId, Object data) throws TemplateException,
7399: EngineException {
7400: if (!mRequestAccessEnabled)
7401: throw new RequestAccessDeniedException();
7402: if (null == mElementContext)
7403: throw new ElementContextMissingException();
7404:
7405: if (null == template)
7406: throw new IllegalArgumentException(
7407: "template can't be null.");
7408: if (null == elementId)
7409: throw new IllegalArgumentException(
7410: "elementId can't be null.");
7411: if (0 == elementId.length())
7412: throw new IllegalArgumentException(
7413: "elementId can't be empty.");
7414:
7415: mElementContext.processEmbeddedElement(template, this ,
7416: elementId, null, data);
7417: }
7418:
7419: /**
7420: * Processes an embedded element with a differentiator in a template.
7421: * <p>Embedded elements are evaluated when value identifiers have the
7422: * following syntax: <code>ELEMENT:elementId:differentiator</code>.
7423: * <p>All embedded elements are automatically processed when the template
7424: * is instantiated, so this method should only be called if you need to
7425: * re-process an embedded element in a particular context.
7426: *
7427: * @param template the template that will be used to process the embedded
7428: * template
7429: * @param elementId the identifier of the element
7430: * @param differentiator the differentiator that will be used; or
7431: * <code>null</code> if no differentiator should be used
7432: * @exception com.uwyn.rife.template.exceptions.TemplateException when an
7433: * error occurs during the template processing
7434: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
7435: * element is known with that identifier; or if you don't have access to
7436: * the request data (eg. you're inside a child trigger); or if there's no
7437: * active element context (eg. you're using this method inside the
7438: * constructor instead of inside the {@link #initialize()} method)
7439: * @see #processEmbeddedElement(Template, String)
7440: * @see #processEmbeddedElement(Template, String, Object)
7441: * @see #processEmbeddedElement(Template, String, String, Object)
7442: * @since 1.0
7443: */
7444: public void processEmbeddedElement(Template template,
7445: String elementId, String differentiator)
7446: throws TemplateException, EngineException {
7447: if (!mRequestAccessEnabled)
7448: throw new RequestAccessDeniedException();
7449: if (null == mElementContext)
7450: throw new ElementContextMissingException();
7451:
7452: if (null == template)
7453: throw new IllegalArgumentException(
7454: "template can't be null.");
7455: if (null == elementId)
7456: throw new IllegalArgumentException(
7457: "elementId can't be null.");
7458: if (0 == elementId.length())
7459: throw new IllegalArgumentException(
7460: "elementId can't be empty.");
7461:
7462: mElementContext.processEmbeddedElement(template, this ,
7463: elementId, differentiator, null);
7464: }
7465:
7466: /**
7467: * Processes an embedded element with a differentiator in a template
7468: * and pass on data to the processed embedded element.
7469: * <p>See {@link #processEmbeddedElement(Template, String, String)} for more
7470: * information.
7471: *
7472: * @param template the template that will be used to process the embedded
7473: * template
7474: * @param elementId the identifier of the element
7475: * @param differentiator the differentiator that will be used; or
7476: * @param data the data that will be available from within the embedded
7477: * element
7478: * <code>null</code> if no differentiator should be used
7479: * @exception com.uwyn.rife.template.exceptions.TemplateException when an
7480: * error occurs during the template processing
7481: * @exception com.uwyn.rife.engine.exceptions.EngineException if no
7482: * element is known with that identifier; or if you don't have access to
7483: * the request data (eg. you're inside a child trigger); or if there's no
7484: * active element context (eg. you're using this method inside the
7485: * constructor instead of inside the {@link #initialize()} method)
7486: * @see #processEmbeddedElement(Template, String)
7487: * @see #processEmbeddedElement(Template, String, Object)
7488: * @see #processEmbeddedElement(Template, String, String)
7489: * @since 1.5
7490: */
7491: public void processEmbeddedElement(Template template,
7492: String elementId, String differentiator, Object data)
7493: throws TemplateException, EngineException {
7494: if (!mRequestAccessEnabled)
7495: throw new RequestAccessDeniedException();
7496: if (null == mElementContext)
7497: throw new ElementContextMissingException();
7498:
7499: if (null == template)
7500: throw new IllegalArgumentException(
7501: "template can't be null.");
7502: if (null == elementId)
7503: throw new IllegalArgumentException(
7504: "elementId can't be null.");
7505: if (0 == elementId.length())
7506: throw new IllegalArgumentException(
7507: "elementId can't be empty.");
7508:
7509: mElementContext.processEmbeddedElement(template, this ,
7510: elementId, differentiator, data);
7511: }
7512:
7513: /**
7514: * Evaluate the <code>ROLEUSER</code> expression tags in a template.
7515: * <p>The {@link #print(Template)} method automatically evaluates all role
7516: * user expression tags. This method should thus only be called when you
7517: * need them to be evaluated in a specific context.
7518: * <p>This block and value expression tag is evaluated through a method
7519: * that's not part of the {@link com.uwyn.rife.template.Template} class
7520: * since it only makes sense in an element context where a users can be
7521: * identified.
7522: * <p>The value tags have the following syntax
7523: * <code>LANGUAGE:ROLEUSER:identifier</code> and the block tags have the
7524: * following syntax
7525: * <code>LANGUAGE:ROLEUSER:identifier:[[ boolean_expression ]]</code>.
7526: * <p>Below is an example of roleuser expression tags in use:
7527: * <pre><!--V 'OGNL:ROLEUSER:role1'-->User is not in role "admin"<!--/V-->
7528: *<!--B 'OGNL:ROLEUSER:role1:[[ isInRole("admin") ]]'-->User is in role "admin"<!--/B--></pre>
7529: *
7530: * @param template the template instance where the evaluation should
7531: * happen
7532: * @param id the block and the value identifier
7533: * @return the list of names of the template values that were generated
7534: * @exception com.uwyn.rife.template.exceptions.TemplateException when an
7535: * error occurs during the expression tags evaluation
7536: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
7537: * have access to the request data (eg. you're inside a child trigger); or
7538: * if there's no active element context (eg. you're using this method
7539: * inside the constructor instead of inside the {@link #initialize()}
7540: * method)
7541: * @since 1.0
7542: */
7543: public List<String> evaluateExpressionRoleUserTags(
7544: Template template, String id) throws TemplateException,
7545: EngineException {
7546: if (!mRequestAccessEnabled)
7547: throw new RequestAccessDeniedException();
7548: if (null == mElementContext)
7549: throw new ElementContextMissingException();
7550:
7551: if (null == template)
7552: throw new IllegalArgumentException(
7553: "template can't be null.");
7554:
7555: if (null == id) {
7556: return Collections.emptyList();
7557: }
7558:
7559: List<String> set_values = new ArrayList<String>();
7560: mElementContext.evaluateExpressionRoleUserTags(set_values,
7561: template, id);
7562: return set_values;
7563: }
7564:
7565: /**
7566: * Activates an exit.
7567: * <p>This immediately breaks out of the element and notifies the engine
7568: * that the next step of the flow must be looked up and executed.
7569: *
7570: * @param name the name of the exit
7571: * @exception com.uwyn.rife.engine.exceptions.EngineException a runtime
7572: * exception that is used to immediately interrupt the execution, don't
7573: * catch this exception; or there's no active element context (eg. you're
7574: * using this method inside the constructor instead of inside the {@link
7575: * #initialize()} method)
7576: * @since 1.0
7577: */
7578: public void exit(String name) throws EngineException {
7579: if (null == mElementContext)
7580: throw new ElementContextMissingException();
7581:
7582: if (null == name)
7583: throw new IllegalArgumentException("name can't be null.");
7584: if (0 == name.length())
7585: throw new IllegalArgumentException("name can't be empty.");
7586:
7587: mElementContext.exit(name);
7588: }
7589:
7590: /**
7591: * Interrupts the execution in this element and transfers the execution to
7592: * the child element.
7593: *
7594: * @exception com.uwyn.rife.engine.exceptions.EngineException a runtime
7595: * exception that is used to immediately interrupt the execution, don't
7596: * catch this exception; or you don't have access to the request data (eg.
7597: * you're inside a child trigger); or there's no active element context
7598: * (eg. you're using this method inside the constructor instead of inside
7599: * the {@link #initialize()} method)
7600: * @since 1.0
7601: */
7602: public void child() throws EngineException {
7603: if (!mRequestAccessEnabled)
7604: throw new RequestAccessDeniedException();
7605: if (null == mElementContext)
7606: throw new ElementContextMissingException();
7607:
7608: mElementContext.child();
7609: }
7610:
7611: /**
7612: * Interrupts the execution in RIFE completely and defers it to the
7613: * servlet container.
7614: * <p>If RIFE is being run as a filter, it will execute the next filter in
7615: * the chain.
7616: * <p>If RIFE is being run as a servlet, the status code <code>404: Not
7617: * Found</code> will be sent to the client.
7618: *
7619: * @exception com.uwyn.rife.engine.exceptions.EngineException a runtime
7620: * exception that is used to immediately interrupt the execution, don't
7621: * catch this exception; or you don't have access to the request data (eg.
7622: * you're inside a child trigger); or there's no active element context
7623: * (eg. you're using this method inside the constructor instead of inside
7624: * the {@link #initialize()} method)
7625: * @since 1.0
7626: */
7627: public void defer() throws EngineException {
7628: if (!mRequestAccessEnabled)
7629: throw new RequestAccessDeniedException();
7630: if (null == mElementContext)
7631: throw new ElementContextMissingException();
7632:
7633: mElementContext.defer();
7634: }
7635:
7636: /**
7637: * Interrupts the execution in this element and forwards the entire
7638: * request to another URL.
7639: * <p>The response of the forwarded request will be sent the to original
7640: * client, as if the request was sent directly to the forwarded URL.
7641: *
7642: * @param url the URL to which the request will be forwarded
7643: * @exception com.uwyn.rife.engine.exceptions.EngineException a runtime
7644: * exception that is used to immediately interrupt the execution, don't
7645: * catch this exception; or you don't have access to the request data (eg.
7646: * you're inside a child trigger); or there's no active element context
7647: * (eg. you're using this method inside the constructor instead of inside
7648: * the {@link #initialize()} method)
7649: * @since 1.0
7650: */
7651: public void forward(String url) throws EngineException {
7652: if (!mRequestAccessEnabled)
7653: throw new RequestAccessDeniedException();
7654: if (null == mElementContext)
7655: throw new ElementContextMissingException();
7656:
7657: mElementContext.forward(url);
7658: }
7659:
7660: /**
7661: * Interrupts the execution in this element and redirects the client to
7662: * another URL.
7663: *
7664: * @param url the URL to which the request will be redirected
7665: * @exception com.uwyn.rife.engine.exceptions.EngineException a runtime
7666: * exception that is used to immediately interrupt the execution, don't
7667: * catch this exception; or you don't have access to the request data (eg.
7668: * you're inside a child trigger); or there's no active element context
7669: * (eg. you're using this method inside the constructor instead of inside
7670: * the {@link #initialize()} method)
7671: * @since 1.0
7672: */
7673: public void redirect(String url) throws EngineException {
7674: if (!mRequestAccessEnabled)
7675: throw new RequestAccessDeniedException();
7676: if (null == mElementContext)
7677: throw new ElementContextMissingException();
7678:
7679: mElementContext.redirect(url);
7680: }
7681:
7682: /**
7683: * Returns the name of the character encoding (MIME charset) used for the
7684: * body sent in this response. The character encoding may have been
7685: * specified explicitly using the {@link #setContentType} method, or
7686: * implicitly using the {@link #setResponseLocale} method. Explicit
7687: * specifications take precedence over implicit specifications. If no
7688: * character encoding has been specified, <code>ISO-8859-1</code> is
7689: * returned.
7690: * <p>See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) for more
7691: * information about character encoding and MIME.
7692: *
7693: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
7694: * have access to the request data (eg. you're inside a child trigger); or
7695: * if there's no active element context (eg. you're using this method
7696: * inside the constructor instead of inside the {@link #initialize()}
7697: * method)
7698: * @return a <code>String</code> specifying the name of the character
7699: * encoding, for example, <code>UTF-8</code>
7700: * @see #setContentType #setResponseLocale
7701: * @since 1.0
7702: */
7703: public String getResponseCharacterEncoding() throws EngineException {
7704: if (!mRequestAccessEnabled)
7705: throw new RequestAccessDeniedException();
7706: if (null == mElementContext)
7707: throw new ElementContextMissingException();
7708:
7709: return mElementContext.getResponse().getCharacterEncoding();
7710: }
7711:
7712: /**
7713: * Sets the length of the content body in the response In HTTP servlets,
7714: * this method sets the HTTP Content-Length header.
7715: *
7716: * @param length an integer specifying the length of the content being
7717: * returned to the client; sets the Content-Length header
7718: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
7719: * have access to the request data (eg. you're inside a child trigger); or
7720: * if there's no active element context (eg. you're using this method
7721: * inside the constructor instead of inside the {@link #initialize()}
7722: * method)
7723: * @since 1.0
7724: */
7725: public void setContentLength(int length) throws EngineException {
7726: if (!mRequestAccessEnabled)
7727: throw new RequestAccessDeniedException();
7728: if (null == mElementContext)
7729: throw new ElementContextMissingException();
7730:
7731: mElementContext.getResponse().setContentLength(length);
7732: }
7733:
7734: /**
7735: * Sets the content type of the response being sent to the client, if the
7736: * response has not been committed yet. The given content type may include
7737: * a character encoding specification, for example,
7738: * <code>text/html;charset=UTF-8</code>. The response's character encoding
7739: * is only set from the given content type if this method is called before
7740: * <code>getWriter</code> is called.
7741: * <p>This method may be called repeatedly to change content type and
7742: * character encoding. This method has no effect if called after the
7743: * response has been committed. It does not set the response's character
7744: * encoding if it is called after <code>getWriter</code> has been called
7745: * or after the response has been committed.
7746: * <p>Containers must communicate the content type and the character
7747: * encoding used for the servlet response's writer to the client if the
7748: * protocol provides a way for doing so. In the case of HTTP, the
7749: * <code>Content-Type</code> header is used.
7750: *
7751: * @param type a <code>String</code> specifying the MIME type of the
7752: * content
7753: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
7754: * have access to the request data (eg. you're inside a child trigger); or
7755: * if there's no active element context (eg. you're using this method
7756: * inside the constructor instead of inside the {@link #initialize()}
7757: * method)
7758: * @see #setResponseLocale
7759: * @see #getOutputStream
7760: * @since 1.0
7761: */
7762: public void setContentType(String type) throws EngineException {
7763: if (!mRequestAccessEnabled)
7764: throw new RequestAccessDeniedException();
7765: if (null == mElementContext)
7766: throw new ElementContextMissingException();
7767:
7768: mElementContext.getResponse().setContentType(type);
7769: }
7770:
7771: /**
7772: * Adds a response header with the given name and value. This method
7773: * allows response headers to have multiple values.
7774: *
7775: * @param name the name of the header
7776: * @param value the additional header value If it contains octet string,
7777: * it should be encoded according to RFC 2047
7778: * (http://www.ietf.org/rfc/rfc2047.txt)
7779: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
7780: * have access to the request data (eg. you're inside a child trigger); or
7781: * if there's no active element context (eg. you're using this method
7782: * inside the constructor instead of inside the {@link #initialize()}
7783: * method)
7784: * @see #setHeader
7785: * @since 1.0
7786: */
7787: public void addHeader(String name, String value)
7788: throws EngineException {
7789: if (!mRequestAccessEnabled)
7790: throw new RequestAccessDeniedException();
7791: if (null == mElementContext)
7792: throw new ElementContextMissingException();
7793:
7794: mElementContext.getResponse().addHeader(name, value);
7795: }
7796:
7797: /**
7798: * Sets a response header with the given name and date-value. The date is
7799: * specified in terms of milliseconds since the epoch. If the header had
7800: * already been set, the new value overwrites the previous one. The
7801: * <code>containsHeader</code> method can be used to test for the presence
7802: * of a header before setting its value.
7803: *
7804: * @param name the name of the header to set
7805: * @param date the assigned date value
7806: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
7807: * have access to the request data (eg. you're inside a child trigger); or
7808: * if there's no active element context (eg. you're using this method
7809: * inside the constructor instead of inside the {@link #initialize()}
7810: * method)
7811: * @see #setDateHeader
7812: * @since 1.0
7813: */
7814: public void addDateHeader(String name, long date)
7815: throws EngineException {
7816: if (!mRequestAccessEnabled)
7817: throw new RequestAccessDeniedException();
7818: if (null == mElementContext)
7819: throw new ElementContextMissingException();
7820:
7821: mElementContext.getResponse().addDateHeader(name, date);
7822: }
7823:
7824: /**
7825: * Adds a response header with the given name and integer value. This
7826: * method allows response headers to have multiple values.
7827: *
7828: * @param name the name of the header
7829: * @param value the assigned integer value
7830: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
7831: * have access to the request data (eg. you're inside a child trigger); or
7832: * if there's no active element context (eg. you're using this method
7833: * inside the constructor instead of inside the {@link #initialize()}
7834: * method)
7835: * @see #setIntHeader
7836: * @since 1.0
7837: */
7838: public void addIntHeader(String name, int value)
7839: throws EngineException {
7840: if (!mRequestAccessEnabled)
7841: throw new RequestAccessDeniedException();
7842: if (null == mElementContext)
7843: throw new ElementContextMissingException();
7844:
7845: mElementContext.getResponse().addIntHeader(name, value);
7846: }
7847:
7848: /**
7849: * Returns a boolean indicating whether the named response header has
7850: * already been set.
7851: *
7852: * @param name the header name
7853: * @return <code>true</code> if the named response header has already been
7854: * set; or
7855: * <p><code>false</code> otherwise
7856: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
7857: * have access to the request data (eg. you're inside a child trigger); or
7858: * if there's no active element context (eg. you're using this method
7859: * inside the constructor instead of inside the {@link #initialize()}
7860: * method)
7861: * @since 1.0
7862: */
7863: public boolean containsHeader(String name) throws EngineException {
7864: if (!mRequestAccessEnabled)
7865: throw new RequestAccessDeniedException();
7866: if (null == mElementContext)
7867: throw new ElementContextMissingException();
7868:
7869: return mElementContext.getResponse().containsHeader(name);
7870: }
7871:
7872: /**
7873: * Sends an error response to the client using the specified status code
7874: * and clearing the buffer.
7875: * <p>If the response has already been committed, this method throws an
7876: * IllegalStateException. After using this method, the response should be
7877: * considered to be committed and should not be written to.
7878: *
7879: * @param statusCode the error status code
7880: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
7881: * have access to the request data (eg. you're inside a child trigger); or
7882: * if there's no active element context (eg. you're using this method
7883: * inside the constructor instead of inside the {@link #initialize()}
7884: * method)
7885: * @see #sendError(int, String)
7886: * @since 1.0
7887: */
7888: public void sendError(int statusCode) throws EngineException {
7889: if (!mRequestAccessEnabled)
7890: throw new RequestAccessDeniedException();
7891: if (null == mElementContext)
7892: throw new ElementContextMissingException();
7893:
7894: mElementContext.getResponse().sendError(statusCode);
7895: }
7896:
7897: /**
7898: * Sends an error response to the client using the specified status. The
7899: * server defaults to creating the response to look like an HTML-formatted
7900: * server error page containing the specified message, setting the content
7901: * type to "text/html", leaving cookies and other headers unmodified. If
7902: * an error-page declaration has been made for the web application
7903: * corresponding to the status code passed in, it will be served back in
7904: * preference to the suggested msg parameter.
7905: * <p>If the response has already been committed, this method throws an
7906: * IllegalStateException. After using this method, the response should be
7907: * considered to be committed and should not be written to.
7908: *
7909: * @param statusCode the error status code
7910: * @param message the descriptive message
7911: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
7912: * have access to the request data (eg. you're inside a child trigger); or
7913: * if there's no active element context (eg. you're using this method
7914: * inside the constructor instead of inside the {@link #initialize()}
7915: * method)
7916: * @see #sendError(int)
7917: * @since 1.0
7918: */
7919: public void sendError(int statusCode, String message)
7920: throws EngineException {
7921: if (!mRequestAccessEnabled)
7922: throw new RequestAccessDeniedException();
7923: if (null == mElementContext)
7924: throw new ElementContextMissingException();
7925:
7926: mElementContext.getResponse().sendError(statusCode, message);
7927: }
7928:
7929: /**
7930: * Sends a temporary redirect response to the client using the specified
7931: * redirect location URL. This method can accept relative URLs; the
7932: * servlet container must convert the relative URL to an absolute URL
7933: * before sending the response to the client. If the location is relative
7934: * without a leading '/' the container interprets it as relative to the
7935: * current request URI. If the location is relative with a leading '/' the
7936: * container interprets it as relative to the servlet container root.
7937: * <p>If the response has already been committed, this method throws an
7938: * IllegalStateException. After using this method, the response should be
7939: * considered to be committed and should not be written to.
7940: *
7941: * @param location the redirect location URL
7942: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
7943: * have access to the request data (eg. you're inside a child trigger); or
7944: * if there's no active element context (eg. you're using this method
7945: * inside the constructor instead of inside the {@link #initialize()}
7946: * method)
7947: * @since 1.0
7948: */
7949: public void sendRedirect(String location) throws EngineException {
7950: if (!mRequestAccessEnabled)
7951: throw new RequestAccessDeniedException();
7952: if (null == mElementContext)
7953: throw new ElementContextMissingException();
7954:
7955: mElementContext.getResponse().sendRedirect(location);
7956: }
7957:
7958: /**
7959: * Sets up the current request to prevent all caching of the response by
7960: * the client.
7961: *
7962: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
7963: * have access to the request data (eg. you're inside a child trigger); or
7964: * if there's no active element context (eg. you're using this method
7965: * inside the constructor instead of inside the {@link #initialize()}
7966: * method)
7967: * @since 1.0
7968: */
7969: public void preventCaching() throws EngineException {
7970: if (!mRequestAccessEnabled)
7971: throw new RequestAccessDeniedException();
7972: if (null == mElementContext)
7973: throw new ElementContextMissingException();
7974:
7975: ServletUtils.preventCaching(mElementContext.getResponse());
7976: }
7977:
7978: /**
7979: * Sets a response header with the given name and date-value. The date is
7980: * specified in terms of milliseconds since the epoch. If the header had
7981: * already been set, the new value overwrites the previous one. The
7982: * <code>containsHeader</code> method can be used to test for the presence
7983: * of a header before setting its value.
7984: *
7985: * @param name the name of the header to set
7986: * @param date the assigned date value
7987: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
7988: * have access to the request data (eg. you're inside a child trigger); or
7989: * if there's no active element context (eg. you're using this method
7990: * inside the constructor instead of inside the {@link #initialize()}
7991: * method)
7992: * @see #containsHeader
7993: * @see #addDateHeader
7994: * @since 1.0
7995: */
7996: public void setDateHeader(String name, long date)
7997: throws EngineException {
7998: if (!mRequestAccessEnabled)
7999: throw new RequestAccessDeniedException();
8000: if (null == mElementContext)
8001: throw new ElementContextMissingException();
8002:
8003: mElementContext.getResponse().setDateHeader(name, date);
8004: }
8005:
8006: /**
8007: * Sets a response header with the given name and value. If the header had
8008: * already been set, the new value overwrites the previous one. The
8009: * <code>containsHeader</code> method can be used to test for the presence
8010: * of a header before setting its value.
8011: *
8012: * @param name the name of the header
8013: * @param value the header value If it contains octet string, it should be
8014: * encoded according to RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt)
8015: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8016: * have access to the request data (eg. you're inside a child trigger); or
8017: * if there's no active element context (eg. you're using this method
8018: * inside the constructor instead of inside the {@link #initialize()}
8019: * method)
8020: * @see #containsHeader
8021: * @see #addHeader
8022: * @since 1.0
8023: */
8024: public void setHeader(String name, String value)
8025: throws EngineException {
8026: if (!mRequestAccessEnabled)
8027: throw new RequestAccessDeniedException();
8028: if (null == mElementContext)
8029: throw new ElementContextMissingException();
8030:
8031: mElementContext.getResponse().setHeader(name, value);
8032: }
8033:
8034: /**
8035: * Sets a response header with the given name and integer value. If the
8036: * header had already been set, the new value overwrites the previous one.
8037: * The <code>containsHeader</code> method can be used to test for the
8038: * presence of a header before setting its value.
8039: *
8040: * @param name the name of the header
8041: * @param value the assigned integer value
8042: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8043: * have access to the request data (eg. you're inside a child trigger); or
8044: * if there's no active element context (eg. you're using this method
8045: * inside the constructor instead of inside the {@link #initialize()}
8046: * method)
8047: * @see #containsHeader
8048: * @see #addIntHeader
8049: * @since 1.0
8050: */
8051: public void setIntHeader(String name, int value)
8052: throws EngineException {
8053: if (!mRequestAccessEnabled)
8054: throw new RequestAccessDeniedException();
8055: if (null == mElementContext)
8056: throw new ElementContextMissingException();
8057:
8058: mElementContext.getResponse().setIntHeader(name, value);
8059: }
8060:
8061: /**
8062: * Sets the status code for this response. This method is used to set the
8063: * return status code when there is no error (for example, for the status
8064: * codes SC_OK or SC_MOVED_TEMPORARILY). If there is an error, and the
8065: * caller wishes to invoke an error-page defined in the web application,
8066: * the <code>sendError</code> method should be used instead.
8067: * <p>The container clears the buffer and sets the Location header,
8068: * preserving cookies and other headers.
8069: *
8070: * @param statusCode the status code
8071: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8072: * have access to the request data (eg. you're inside a child trigger); or
8073: * if there's no active element context (eg. you're using this method
8074: * inside the constructor instead of inside the {@link #initialize()}
8075: * method)
8076: * @see #sendError
8077: * @since 1.0
8078: */
8079: public void setStatus(int statusCode) throws EngineException {
8080: if (!mRequestAccessEnabled)
8081: throw new RequestAccessDeniedException();
8082: if (null == mElementContext)
8083: throw new ElementContextMissingException();
8084:
8085: mElementContext.getResponse().setStatus(statusCode);
8086: }
8087:
8088: /**
8089: * Sets the locale of the response, if the response has not been committed
8090: * yet. It also sets the response's character encoding appropriately for
8091: * the locale, if the character encoding has not been explicitly set using
8092: * {@link #setContentType} and the response hasn't been committed yet. If
8093: * the deployment descriptor contains a
8094: * <code>locale-encoding-mapping-list</code> element, and that element
8095: * provides a mapping for the given locale, that mapping is used.
8096: * Otherwise, the mapping from locale to character encoding is container
8097: * dependent.
8098: * <p>This method may be called repeatedly to change locale and character
8099: * encoding. The method has no effect if called after the response has
8100: * been committed. It does not set the response's character encoding if it
8101: * is called after {@link #setContentType} has been called with a charset
8102: * specification, or after the response has been committed.
8103: * <p>Containers must communicate the locale and the character encoding
8104: * used for the servlet response's writer to the client if the protocol
8105: * provides a way for doing so. In the case of HTTP, the locale is
8106: * communicated via the <code>Content-Language</code> header, the
8107: * character encoding as part of the <code>Content-Type</code> header for
8108: * text media types. Note that the character encoding cannot be
8109: * communicated via HTTP headers if the servlet does not specify a content
8110: * type; however, it is still used to encode text written via the servlet
8111: * response's writer.
8112: *
8113: * @param locale the locale of the response
8114: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8115: * have access to the request data (eg. you're inside a child trigger); or
8116: * if there's no active element context (eg. you're using this method
8117: * inside the constructor instead of inside the {@link #initialize()}
8118: * method)
8119: * @see #getResponseLocale
8120: * @see #setContentType
8121: * @since 1.0
8122: */
8123: public void setResponseLocale(Locale locale) throws EngineException {
8124: if (!mRequestAccessEnabled)
8125: throw new RequestAccessDeniedException();
8126: if (null == mElementContext)
8127: throw new ElementContextMissingException();
8128:
8129: mElementContext.getResponse().setLocale(locale);
8130: }
8131:
8132: /**
8133: * Returns the locale specified for this response using the {@link
8134: * #setResponseLocale} method. Calls made to
8135: * <code>setResponseLocale</code> after the response is committed have no
8136: * effect. If no locale has been specified, the container's default locale
8137: * is returned.
8138: *
8139: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8140: * have access to the request data (eg. you're inside a child trigger); or
8141: * if there's no active element context (eg. you're using this method
8142: * inside the constructor instead of inside the {@link #initialize()}
8143: * method)
8144: * @return the locale of the response
8145: * @see #setResponseLocale
8146: * @since 1.0
8147: */
8148: public Locale getResponseLocale() throws EngineException {
8149: if (!mRequestAccessEnabled)
8150: throw new RequestAccessDeniedException();
8151: if (null == mElementContext)
8152: throw new ElementContextMissingException();
8153:
8154: return mElementContext.getResponse().getLocale();
8155: }
8156:
8157: /**
8158: * Returns the root URL of the server that is running this web
8159: * applications.
8160: * <p>This includes the protocol, the server name and the server port, for
8161: * example: <code>http://www.somehost.com:8080</code>.
8162: *
8163: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8164: * have access to the request data (eg. you're inside a child trigger); or
8165: * if there's no active element context (eg. you're using this method
8166: * inside the constructor instead of inside the {@link #initialize()}
8167: * method)
8168: * @return the server's root url
8169: * @since 1.0
8170: */
8171: public String getServerRootUrl() throws EngineException {
8172: if (!mRequestAccessEnabled)
8173: throw new RequestAccessDeniedException();
8174: if (null == mElementContext)
8175: throw new ElementContextMissingException();
8176:
8177: return mElementContext.getRequestState().getServerRootUrl(-1);
8178: }
8179:
8180: /**
8181: * Returns the root URL of this web applications.
8182: * <p>This includes the protocol, the server name, the server port and the
8183: * URL of RIFE's gateway, for example:
8184: * <code>http://www.somehost.com:8080/my/webapp/</code>.
8185: *
8186: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8187: * have access to the request data (eg. you're inside a child trigger); or
8188: * if there's no active element context (eg. you're using this method
8189: * inside the constructor instead of inside the {@link #initialize()}
8190: * method)
8191: * @return the web application's root url
8192: * @since 1.0
8193: */
8194: public String getWebappRootUrl() throws EngineException {
8195: if (!mRequestAccessEnabled)
8196: throw new RequestAccessDeniedException();
8197: if (null == mElementContext)
8198: throw new ElementContextMissingException();
8199:
8200: return mElementContext.getRequestState().getWebappRootUrl(-1);
8201: }
8202:
8203: /**
8204: * Returns the name of the character encoding used in the body of this
8205: * request. This method returns <code>null</code> if the request does not
8206: * specify a character encoding
8207: *
8208: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8209: * have access to the request data (eg. you're inside a child trigger); or
8210: * if there's no active element context (eg. you're using this method
8211: * inside the constructor instead of inside the {@link #initialize()}
8212: * method)
8213: * @return a <code>String</code> containing the name of the character
8214: * encoding; or
8215: * <p><code>null</code> if the request does not specify a character
8216: * encoding
8217: * @since 1.0
8218: */
8219: public String getRequestCharacterEncoding() throws EngineException {
8220: if (!mRequestAccessEnabled)
8221: throw new RequestAccessDeniedException();
8222: if (null == mElementContext)
8223: throw new ElementContextMissingException();
8224:
8225: return mElementContext.getRequestState().getCharacterEncoding();
8226: }
8227:
8228: /**
8229: * Returns the MIME type of the body of the request, or <code>null</code>
8230: * if the type is not known. For HTTP servlets, same as the value of the
8231: * CGI variable CONTENT_TYPE.
8232: *
8233: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8234: * have access to the request data (eg. you're inside a child trigger); or
8235: * if there's no active element context (eg. you're using this method
8236: * inside the constructor instead of inside the {@link #initialize()}
8237: * method)
8238: * @return a <code>String</code> containing the name of the MIME type of
8239: * the request; or
8240: * <p><code>null</code> if the type is not known
8241: * @since 1.0
8242: */
8243: public String getContentType() throws EngineException {
8244: if (!mRequestAccessEnabled)
8245: throw new RequestAccessDeniedException();
8246: if (null == mElementContext)
8247: throw new ElementContextMissingException();
8248:
8249: return mElementContext.getRequestState().getContentType();
8250: }
8251:
8252: /**
8253: * Returns the value of the specified request header as a
8254: * <code>long</code> value that represents a <code>Date</code> object. Use
8255: * this method with headers that contain dates, such as
8256: * <code>If-Modified-Since</code>.
8257: * <p>The date is returned as the number of milliseconds since January 1,
8258: * 1970 GMT. The header name is case insensitive.
8259: * <p>If the request did not have a header of the specified name, this
8260: * method returns -1. If the header can't be converted to a date, the
8261: * method throws an <code>IllegalArgumentException</code>.
8262: *
8263: * @param name a <code>String</code> specifying the name of the header
8264: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8265: * have access to the request data (eg. you're inside a child trigger); or
8266: * if there's no active element context (eg. you're using this method
8267: * inside the constructor instead of inside the {@link #initialize()}
8268: * method)
8269: * @return a <code>long</code> value representing the date specified in
8270: * the header expressed as the number of milliseconds since January 1,
8271: * 1970 GMT, or -1 if the named header was not included with the request
8272: * @since 1.0
8273: */
8274: public long getDateHeader(String name) throws EngineException {
8275: if (!mRequestAccessEnabled)
8276: throw new RequestAccessDeniedException();
8277: if (null == mElementContext)
8278: throw new ElementContextMissingException();
8279:
8280: return mElementContext.getRequestState().getDateHeader(name);
8281: }
8282:
8283: /**
8284: * Returns the value of the specified request header as a
8285: * <code>String</code>. If the request did not include a header of the
8286: * specified name, this method returns <code>null</code>. If there are
8287: * multiple headers with the same name, this method returns the first head
8288: * in the request. The header name is case insensitive. You can use this
8289: * method with any request header.
8290: *
8291: * @param name a <code>String</code> specifying the header name
8292: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8293: * have access to the request data (eg. you're inside a child trigger); or
8294: * if there's no active element context (eg. you're using this method
8295: * inside the constructor instead of inside the {@link #initialize()}
8296: * method)
8297: * @return a <code>String</code> containing the value of the requested
8298: * header; or
8299: * <p><code>null</code> if the request does not have a header of that name
8300: * @since 1.0
8301: */
8302: public String getHeader(String name) {
8303: if (!mRequestAccessEnabled)
8304: throw new RequestAccessDeniedException();
8305: if (null == mElementContext)
8306: throw new ElementContextMissingException();
8307:
8308: return mElementContext.getRequestState().getHeader(name);
8309: }
8310:
8311: /**
8312: * Returns an enumeration of all the header names this request contains.
8313: * If the request has no headers, this method returns an empty
8314: * enumeration.
8315: * <p>Some servlet containers do not allow servlets to access headers
8316: * using this method, in which case this method returns <code>null</code>
8317: *
8318: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8319: * have access to the request data (eg. you're inside a child trigger); or
8320: * if there's no active element context (eg. you're using this method
8321: * inside the constructor instead of inside the {@link #initialize()}
8322: * method)
8323: * @return an enumeration of all the header names sent with this request;
8324: * if the request has no headers, an empty enumeration; if the servlet
8325: * container does not allow servlets to use this method, <code>null</code>
8326: * @since 1.0
8327: */
8328: public Enumeration getHeaderNames() throws EngineException {
8329: if (!mRequestAccessEnabled)
8330: throw new RequestAccessDeniedException();
8331: if (null == mElementContext)
8332: throw new ElementContextMissingException();
8333:
8334: return mElementContext.getRequestState().getHeaderNames();
8335: }
8336:
8337: /**
8338: * Returns all the values of the specified request header as an
8339: * <code>Enumeration</code> of <code>String</code> objects.
8340: * <p>Some headers, such as <code>Accept-Language</code> can be sent by
8341: * clients as several headers each with a different value rather than
8342: * sending the header as a comma separated list.
8343: * <p>If the request did not include any headers of the specified name,
8344: * this method returns an empty <code>Enumeration</code>. The header name
8345: * is case insensitive. You can use this method with any request header.
8346: *
8347: * @param name a <code>String</code> specifying the header name
8348: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8349: * have access to the request data (eg. you're inside a child trigger); or
8350: * if there's no active element context (eg. you're using this method
8351: * inside the constructor instead of inside the {@link #initialize()}
8352: * method)
8353: * @return an <code>Enumeration</code> containing the values of the
8354: * requested header. If the request does not have any headers of that name
8355: * return an empty enumeration. If the container does not allow access to
8356: * header information, it returns <code>null</code>.
8357: * @since 1.0
8358: */
8359: public Enumeration getHeaders(String name) throws EngineException {
8360: if (!mRequestAccessEnabled)
8361: throw new RequestAccessDeniedException();
8362: if (null == mElementContext)
8363: throw new ElementContextMissingException();
8364:
8365: return mElementContext.getRequestState().getHeaders(name);
8366: }
8367:
8368: /**
8369: * Retrieves initialization configuration of this web application.
8370: *
8371: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8372: * have access to the request data (eg. you're inside a child trigger); or
8373: * if there's no active element context (eg. you're using this method
8374: * inside the constructor instead of inside the {@link #initialize()}
8375: * method)
8376: * @return the initialization configuration instance of this web
8377: * application
8378: * @see InitConfig
8379: * @since 1.0
8380: */
8381: public InitConfig getInitConfig() throws EngineException {
8382: if (!mRequestAccessEnabled)
8383: throw new RequestAccessDeniedException();
8384: if (null == mElementContext)
8385: throw new ElementContextMissingException();
8386:
8387: return mElementContext.getRequestState().getInitConfig();
8388: }
8389:
8390: /**
8391: * Returns the value of the specified request header as an
8392: * <code>int</code>. If the request does not have a header of the
8393: * specified name, this method returns -1. If the header cannot be
8394: * converted to an integer, this method throws a
8395: * <code>NumberFormatException</code>.
8396: * <p>The header name is case insensitive.
8397: *
8398: * @param name a <code>String</code> specifying the name of a request
8399: * header
8400: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8401: * have access to the request data (eg. you're inside a child trigger); or
8402: * if there's no active element context (eg. you're using this method
8403: * inside the constructor instead of inside the {@link #initialize()}
8404: * method)
8405: * @return an integer expressing the value of the request header; or
8406: * <p><code>-1</code> if the request doesn't have a header of this name
8407: * @since 1.0
8408: */
8409: public int getIntHeader(String name) throws EngineException {
8410: if (!mRequestAccessEnabled)
8411: throw new RequestAccessDeniedException();
8412: if (null == mElementContext)
8413: throw new ElementContextMissingException();
8414:
8415: return mElementContext.getRequestState().getIntHeader(name);
8416: }
8417:
8418: /**
8419: * Returns the preferred <code>Locale</code> that the client will accept
8420: * content in, based on the Accept-Language header. If the client request
8421: * doesn't provide an Accept-Language header, this method returns the
8422: * default locale for the server.
8423: *
8424: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8425: * have access to the request data (eg. you're inside a child trigger); or
8426: * if there's no active element context (eg. you're using this method
8427: * inside the constructor instead of inside the {@link #initialize()}
8428: * method)
8429: * @return the preferred <code>Locale</code> for the client
8430: * @since 1.0
8431: */
8432: public Locale getRequestLocale() throws EngineException {
8433: if (!mRequestAccessEnabled)
8434: throw new RequestAccessDeniedException();
8435: if (null == mElementContext)
8436: throw new ElementContextMissingException();
8437:
8438: return mElementContext.getRequestState().getLocale();
8439: }
8440:
8441: /**
8442: * Returns an <code>Enumeration</code> of <code>Locale</code> objects
8443: * indicating, in decreasing order starting with the preferred locale, the
8444: * locales that are acceptable to the client based on the Accept-Language
8445: * header. If the client request doesn't provide an Accept-Language
8446: * header, this method returns an <code>Enumeration</code> containing one
8447: * <code>Locale</code>, the default locale for the server.
8448: *
8449: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8450: * have access to the request data (eg. you're inside a child trigger); or
8451: * if there's no active element context (eg. you're using this method
8452: * inside the constructor instead of inside the {@link #initialize()}
8453: * method)
8454: * @return an <code>Enumeration</code> of preferred <code>Locale</code>
8455: * objects for the client
8456: * @since 1.0
8457: */
8458: public Enumeration getRequestLocales() throws EngineException {
8459: if (!mRequestAccessEnabled)
8460: throw new RequestAccessDeniedException();
8461: if (null == mElementContext)
8462: throw new ElementContextMissingException();
8463:
8464: return mElementContext.getRequestState().getLocales();
8465: }
8466:
8467: /**
8468: * Returns any extra path information associated with the URL the client
8469: * sent when it made this request. The extra path information follows the
8470: * element URL but precedes the query string and will start with a "/"
8471: * character.
8472: * <p>The URL of an element that should support pathinfo, has to end with
8473: * an asterisk (for example: <code>/my/url/*</code>).
8474: * <p>This method returns an empty string if there was no extra path
8475: * information.
8476: *
8477: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8478: * have access to the request data (eg. you're inside a child trigger); or
8479: * if there's no active element context (eg. you're using this method
8480: * inside the constructor instead of inside the {@link #initialize()}
8481: * method)
8482: * @return a <code>String</code>, decoded by the web engine, specifying
8483: * extra path information that comes after the element URL but before the
8484: * query string in the request URL; or
8485: * <p>or an empty string if the URL does not have any extra path
8486: * information
8487: * @since 1.0
8488: */
8489: public String getPathInfo() throws EngineException {
8490: if (!mRequestAccessEnabled)
8491: throw new RequestAccessDeniedException();
8492: if (null == mElementContext)
8493: throw new ElementContextMissingException();
8494:
8495: return mElementContext.getRequestState().getElementState()
8496: .getPathInfo();
8497: }
8498:
8499: /**
8500: * Returns the method of this request.
8501: *
8502: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8503: * have access to the request data (eg. you're inside a child trigger); or
8504: * if there's no active element context (eg. you're using this method
8505: * inside the constructor instead of inside the {@link #initialize()}
8506: * method)
8507: * @return the method of this request
8508: * @since 1.0
8509: */
8510: public RequestMethod getMethod() throws EngineException {
8511: if (!mRequestAccessEnabled)
8512: throw new RequestAccessDeniedException();
8513: if (null == mElementContext)
8514: throw new ElementContextMissingException();
8515:
8516: return mElementContext.getRequestState().getElementState()
8517: .getMethod();
8518: }
8519:
8520: /**
8521: * Returns the name and version of the protocol the request uses in the
8522: * form <i>protocol/majorVersion.minorVersion</i>, for example, HTTP/1.1.
8523: *
8524: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8525: * have access to the request data (eg. you're inside a child trigger); or
8526: * if there's no active element context (eg. you're using this method
8527: * inside the constructor instead of inside the {@link #initialize()}
8528: * method)
8529: * @return a <code>String</code> containing the protocol name and version
8530: * number
8531: * @since 1.0
8532: */
8533: public String getProtocol() throws EngineException {
8534: if (!mRequestAccessEnabled)
8535: throw new RequestAccessDeniedException();
8536: if (null == mElementContext)
8537: throw new ElementContextMissingException();
8538:
8539: return mElementContext.getRequestState().getProtocol();
8540: }
8541:
8542: /**
8543: * Returns the Internet Protocol (IP) address of the client or last proxy
8544: * that sent the request.
8545: *
8546: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
8547: * no active element context (eg. you're using this method inside the
8548: * constructor instead of inside the {@link #initialize()} method)
8549: * @return a <code>String</code> containing the IP address of the client
8550: * that sent the request
8551: * @since 1.0
8552: */
8553: public String getRemoteAddr() throws EngineException {
8554: if (null == mElementContext)
8555: throw new ElementContextMissingException();
8556:
8557: return mElementContext.getRequestState().getRemoteAddr();
8558: }
8559:
8560: /**
8561: * Returns the login of the user making this request, if the user has been
8562: * authenticated, or <code>null</code> if the user has not been
8563: * authenticated. Whether the user name is sent with each subsequent
8564: * request depends on the browser and type of authentication.
8565: *
8566: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
8567: * no active element context (eg. you're using this method inside the
8568: * constructor instead of inside the {@link #initialize()} method)
8569: * @return a <code>String</code> specifying the login of the user making
8570: * this request; or
8571: * <p><code>null</code> if the user login is not known
8572: * @since 1.0
8573: */
8574: public String getRemoteUser() throws EngineException {
8575: if (null == mElementContext)
8576: throw new ElementContextMissingException();
8577:
8578: return mElementContext.getRequestState().getRemoteUser();
8579: }
8580:
8581: /**
8582: * Returns the fully qualified name of the client or the last proxy that
8583: * sent the request. If the engine cannot or chooses not to resolve the
8584: * hostname (to improve performance), this method returns the
8585: * dotted-string form of the IP address.
8586: *
8587: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
8588: * no active element context (eg. you're using this method inside the
8589: * constructor instead of inside the {@link #initialize()} method)
8590: * @return a <code>String</code> containing the fully qualified name of
8591: * the client
8592: * @since 1.0
8593: */
8594: public String getRemoteHost() throws EngineException {
8595: if (null == mElementContext)
8596: throw new ElementContextMissingException();
8597:
8598: return mElementContext.getRequestState().getRemoteHost();
8599: }
8600:
8601: /**
8602: * Returns the port number to which the request was sent. It is the value
8603: * of the part after ":" in the <code>Host</code> header value, if any, or
8604: * the server port where the client connection was accepted on.
8605: *
8606: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8607: * have access to the request data (eg. you're inside a child trigger); or
8608: * if there's no active element context (eg. you're using this method
8609: * inside the constructor instead of inside the {@link #initialize()}
8610: * method)
8611: * @return an integer specifying the port number
8612: * @since 1.0
8613: */
8614: public int getServerPort() throws EngineException {
8615: if (!mRequestAccessEnabled)
8616: throw new RequestAccessDeniedException();
8617: if (null == mElementContext)
8618: throw new ElementContextMissingException();
8619:
8620: return mElementContext.getRequestState().getServerPort();
8621: }
8622:
8623: /**
8624: * Returns the name of the scheme used to make this request, for example,
8625: * <code>http</code>, <code>https</code>, or <code>ftp</code>. Different
8626: * schemes have different rules for constructing URLs, as noted in RFC
8627: * 1738.
8628: *
8629: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8630: * have access to the request data (eg. you're inside a child trigger); or
8631: * if there's no active element context (eg. you're using this method
8632: * inside the constructor instead of inside the {@link #initialize()}
8633: * method)
8634: * @return a <code>String</code> containing the name of the scheme used to
8635: * make this request
8636: * @since 1.0
8637: */
8638: public String getScheme() throws EngineException {
8639: if (!mRequestAccessEnabled)
8640: throw new RequestAccessDeniedException();
8641: if (null == mElementContext)
8642: throw new ElementContextMissingException();
8643:
8644: return mElementContext.getRequestState().getScheme();
8645: }
8646:
8647: /**
8648: * Returns the host name of the server to which the request was sent. It
8649: * is the value of the part before ":" in the <code>Host</code> header
8650: * value, if any, or the resolved server name, or the server IP address.
8651: *
8652: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8653: * have access to the request data (eg. you're inside a child trigger); or
8654: * if there's no active element context (eg. you're using this method
8655: * inside the constructor instead of inside the {@link #initialize()}
8656: * method)
8657: * @return a <code>String</code> containing the name of the server
8658: * @since 1.0
8659: */
8660: public String getServerName() throws EngineException {
8661: if (!mRequestAccessEnabled)
8662: throw new RequestAccessDeniedException();
8663: if (null == mElementContext)
8664: throw new ElementContextMissingException();
8665:
8666: return mElementContext.getRequestState().getServerName();
8667: }
8668:
8669: /**
8670: * Returns a boolean indicating whether this request was made using a
8671: * secure channel, such as HTTPS.
8672: *
8673: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8674: * have access to the request data (eg. you're inside a child trigger); or
8675: * if there's no active element context (eg. you're using this method
8676: * inside the constructor instead of inside the {@link #initialize()}
8677: * method)
8678: * @return a boolean indicating if the request was made using a secure
8679: * channel
8680: * @since 1.0
8681: */
8682: public boolean isSecure() throws EngineException {
8683: if (!mRequestAccessEnabled)
8684: throw new RequestAccessDeniedException();
8685: if (null == mElementContext)
8686: throw new ElementContextMissingException();
8687:
8688: return mElementContext.getRequestState().isSecure();
8689: }
8690:
8691: /**
8692: * Returns the value of the named attribute as an <code>Object</code>, or
8693: * <code>null</code> if no attribute of the given name exists.
8694: * <p>Attributes can be set two ways. The servlet container may set
8695: * attributes to make available custom information about a request. For
8696: * example, for requests made using HTTPS, the attribute
8697: * <code>javax.servlet.request.X509Certificate</code> can be used to
8698: * retrieve information on the certificate of the client. Attributes can
8699: * also be set programatically using {@link #setRequestAttribute}. This allows
8700: * information to be embedded into a request an communicate amongst
8701: * elements.
8702: * <p>Attribute names should follow the same conventions as package names.
8703: * This specification reserves names matching <code>java.*</code>,
8704: * <code>javax.*</code>, and <code>sun.*</code>.
8705: *
8706: * @param name a <code>String</code> specifying the name of the attribute
8707: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
8708: * no active element context (eg. you're using this method inside the
8709: * constructor instead of inside the {@link #initialize()} method)
8710: * @return an <code>Object</code> containing the value of the attribute,
8711: * or <code>null</code> if the attribute does not exist
8712: * @see #hasRequestAttribute
8713: * @see #getRequestAttributeNames
8714: * @see #removeRequestAttribute
8715: * @see #setRequestAttribute
8716: * @since 1.0
8717: */
8718: public Object getRequestAttribute(String name)
8719: throws EngineException {
8720: if (null == mElementContext)
8721: throw new ElementContextMissingException();
8722:
8723: return mElementContext.getRequestState().getRequestAttribute(
8724: name);
8725: }
8726:
8727: /**
8728: * Checks if a request attribute exists.
8729: *
8730: * @param name a <code>String</code> specifying the name of the attribute
8731: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
8732: * no active element context (eg. you're using this method inside the
8733: * constructor instead of inside the {@link #initialize()} method)
8734: * @return <code>true</code> if the attribute exists; or
8735: * <p><code>false</code> otherwise
8736: * @see #getRequestAttribute
8737: * @see #getRequestAttributeNames
8738: * @see #removeRequestAttribute
8739: * @see #setRequestAttribute
8740: * @since 1.0
8741: */
8742: public boolean hasRequestAttribute(String name)
8743: throws EngineException {
8744: if (null == mElementContext)
8745: throw new ElementContextMissingException();
8746:
8747: return mElementContext.getRequestState().hasRequestAttribute(
8748: name);
8749: }
8750:
8751: /**
8752: * Returns an <code>Enumeration</code> containing the names of the
8753: * attributes available to this request. This method returns an empty
8754: * <code>Enumeration</code> if the request has no attributes available to
8755: * it.
8756: *
8757: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
8758: * no active element context (eg. you're using this method inside the
8759: * constructor instead of inside the {@link #initialize()} method)
8760: * @return an <code>Enumeration</code> of strings containing the names of
8761: * the request's attributes
8762: * @see #getRequestAttribute
8763: * @see #hasRequestAttribute
8764: * @see #removeRequestAttribute
8765: * @see #setRequestAttribute
8766: * @since 1.0
8767: */
8768: public Enumeration getRequestAttributeNames()
8769: throws EngineException {
8770: if (null == mElementContext)
8771: throw new ElementContextMissingException();
8772:
8773: return mElementContext.getRequestState()
8774: .getRequestAttributeNames();
8775: }
8776:
8777: /**
8778: * Removes an attribute from this request. This method is not generally
8779: * needed as attributes only persist as long as the request is being
8780: * handled.
8781: * <p>Attribute names should follow the same conventions as package names.
8782: * Names beginning with <code>java.*</code>, <code>javax.*</code>, and
8783: * <code>com.sun.*</code>, are reserved for use by Sun Microsystems.
8784: *
8785: * @param name a <code>String</code> specifying the name of the attribute
8786: * to remove
8787: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
8788: * no active element context (eg. you're using this method inside the
8789: * constructor instead of inside the {@link #initialize()} method)
8790: * @see #getRequestAttribute
8791: * @see #hasRequestAttribute
8792: * @see #getRequestAttributeNames
8793: * @see #setRequestAttribute
8794: * @since 1.0
8795: */
8796: public void removeRequestAttribute(String name)
8797: throws EngineException {
8798: if (null == mElementContext)
8799: throw new ElementContextMissingException();
8800:
8801: mElementContext.getRequestState().removeRequestAttribute(name);
8802: }
8803:
8804: /**
8805: * Stores an attribute in this request. Attributes are reset between
8806: * requests.
8807: * <p>Attribute names should follow the same conventions as package names.
8808: * Names beginning with <code>java.*</code>, <code>javax.*</code>, and
8809: * <code>com.sun.*</code>, are reserved for use by Sun Microsystems. <br>
8810: * If the object passed in is null, the effect is the same as calling
8811: * {@link #removeRequestAttribute}.
8812: *
8813: * @param name a <code>String</code> specifying the name of the attribute
8814: * @param object the <code>Object</code> to be stored
8815: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
8816: * no active element context (eg. you're using this method inside the
8817: * constructor instead of inside the {@link #initialize()} method)
8818: * @see #getRequestAttribute
8819: * @see #hasRequestAttribute
8820: * @see #getRequestAttributeNames
8821: * @see #removeRequestAttribute
8822: * @since 1.0
8823: */
8824: public void setRequestAttribute(String name, Object object)
8825: throws EngineException {
8826: if (null == mElementContext)
8827: throw new ElementContextMissingException();
8828:
8829: mElementContext.getRequestState().setRequestAttribute(name,
8830: object);
8831: }
8832:
8833: /**
8834: * Retrieves the context of this element.
8835: * <p>By default, this method will throw an exception since it gives raw
8836: * access to web engine features that aren't managed. See {@link
8837: * #setProhibitRawAccess} for more information about activating it.
8838: *
8839: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8840: * have raw access to the web engine; or if there's no active element
8841: * context (eg. you're using this method inside the constructor instead of
8842: * inside the {@link #initialize()} method)
8843: * @return the context that belongs to this element instance
8844: * @see ElementContext
8845: * @see #setProhibitRawAccess
8846: * @since 1.0
8847: */
8848: public ElementContext getElementContext() throws EngineException {
8849: if (prohibitRawAccess())
8850: throw new RawAccessDeniedException();
8851: if (null == mElementContext)
8852: throw new ElementContextMissingException();
8853:
8854: return mElementContext;
8855: }
8856:
8857: /**
8858: * Returns the current <code>HttpServletRequest</code>.
8859: * <p>By default, this method will throw an exception since it gives raw
8860: * access to web engine features that aren't managed. See {@link
8861: * #setProhibitRawAccess} for more information about activating it.
8862: *
8863: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8864: * have raw access to the web engine; or if there's no active element
8865: * context (eg. you're using this method inside the constructor instead of
8866: * inside the {@link #initialize()} method)
8867: * @return the current <code>HttpServletRequest</code>
8868: * @see #setProhibitRawAccess
8869: * @since 1.0
8870: */
8871: public HttpServletRequest getHttpServletRequest()
8872: throws EngineException {
8873: if (prohibitRawAccess())
8874: throw new RawAccessDeniedException();
8875: if (null == mElementContext)
8876: throw new ElementContextMissingException();
8877:
8878: return mElementContext.getRequestState().getRequest()
8879: .getHttpServletRequest();
8880: }
8881:
8882: /**
8883: * Returns the current <code>HttpServletResponse</code>.
8884: * <p>By default, this method will throw an exception since it gives raw
8885: * access to web engine features that aren't managed. See {@link
8886: * #setProhibitRawAccess} for more information about activating it.
8887: *
8888: * @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
8889: * have raw access to the web engine; or if there's no active element
8890: * context (eg. you're using this method inside the constructor instead of
8891: * inside the {@link #initialize()} method)
8892: * @return the current <code>HttpServletResponse</code>
8893: * @see #setProhibitRawAccess
8894: * @since 1.0
8895: */
8896: public HttpServletResponse getHttpServletResponse()
8897: throws EngineException {
8898: if (prohibitRawAccess())
8899: throw new RawAccessDeniedException();
8900: if (null == mElementContext)
8901: throw new ElementContextMissingException();
8902:
8903: return mElementContext.getResponse().getHttpServletResponse();
8904: }
8905:
8906: /**
8907: * Returns the <code>ServletContext</code> of this web application.
8908: * <p>By default, this method will throw an exception since it gives raw
8909: * access to web engine features that aren't managed. See {@link
8910: * #setProhibitRawAccess} for more information about activating it.
8911: *
8912: * @exception com.uwyn.rife.engine.exceptions.EngineException if there's
8913: * no active element context (eg. you're using this method inside the
8914: * constructor instead of inside the {@link #initialize()} method)
8915: * @return the <code>ServletContext</code>
8916: * @see #setProhibitRawAccess
8917: * @since 1.0
8918: */
8919: public ServletContext getServletContext() throws EngineException {
8920: if (null == mElementContext)
8921: throw new ElementContextMissingException();
8922:
8923: return mElementContext.getRequestState().getInitConfig()
8924: .getServletContext();
8925: }
8926:
8927: void setElementAware(ElementAware elementAware) {
8928: mElementAware = elementAware;
8929: elementAware.noticeElement(this );
8930: }
8931:
8932: ElementAware getElementAware() {
8933: return mElementAware;
8934: }
8935:
8936: ElementContext _getElementContext() {
8937: return mElementContext;
8938: }
8939:
8940: public void setElementContext(ElementContext elementContext) {
8941: mElementContext = elementContext;
8942: }
8943:
8944: void setElementInfo(ElementInfo elementInfo) {
8945: assert elementInfo != null;
8946:
8947: mElementInfo = elementInfo;
8948: }
8949:
8950: void enableRequestAccess(boolean enabled) {
8951: mRequestAccessEnabled = enabled;
8952: }
8953:
8954: public Object clone() throws CloneNotSupportedException {
8955: ElementSupport new_elementsupport = (ElementSupport) super
8956: .clone();
8957:
8958: new_elementsupport.mElementContext = null;
8959:
8960: if (mElementAware != null) {
8961: // prevent a self-referencing clone
8962: if (this == mElementAware) {
8963: new_elementsupport.mElementAware = (ElementAware) new_elementsupport;
8964: }
8965: // clone it since the ElementAware instance is not the same as
8966: // the ElementSupport instance
8967: else {
8968: new_elementsupport.mElementAware = ObjectUtils
8969: .genericClone(mElementAware);
8970: if (null == new_elementsupport.mElementAware) {
8971: throw new CloneNotSupportedException();
8972: }
8973: }
8974: new_elementsupport.mElementAware
8975: .noticeElement(new_elementsupport);
8976: }
8977:
8978: return new_elementsupport;
8979: }
8980: }
|