/*
* Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
* Distributed under the terms of either:
* - the common development and distribution license (CDDL), v1.0; or
* - the GNU Lesser General Public License, v2.1 or later
* $Id: ElementSupport.java 3846 2007-07-11 11:33:53Z gbevin $
*/
package com.uwyn.rife.engine;
import java.io.OutputStream;
import java.io.Serializable;
import java.util.*;
import javax.servlet.ServletContext;
import javax.servlet.http.Cookie;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.uwyn.rife.continuations.ContinuableObject;
import com.uwyn.rife.continuations.ContinuationContext;
import com.uwyn.rife.continuations.exceptions.ContinuationsNotActiveException;
import com.uwyn.rife.engine.exceptions.*;
import com.uwyn.rife.template.Template;
import com.uwyn.rife.template.TemplateTransformer;
import com.uwyn.rife.template.exceptions.TemplateException;
import com.uwyn.rife.tools.*;
import com.uwyn.rife.tools.exceptions.ConversionException;
import com.uwyn.rife.tools.exceptions.SerializationUtilsErrorException;
/**
* <p>The <code>ElementSupport</code> class provides all the methods to
* communicate from inside an element with the context in which it is being
* executed.
*
* @author Geert Bevin (gbevin[remove] at uwyn dot com)
* @version $Revision: 3846 $
* @see ElementAware
* @since 1.0
*/
public class ElementSupport implements ContinuableObject, Cloneable
{
private ElementAware mElementAware = null;
private transient ElementInfo mElementInfo = null;
private transient ElementContext mElementContext = null;
private boolean mRequestAccessEnabled = true;
private ElementInitializer mInitializer = null;
private ElementChildTrigger mChildTrigger = null;
private Class mDeploymentClass = null;
private boolean mProhibitRawAccess = true;
private boolean mCloneContinuations = true;
protected ElementSupport()
{
}
/**
* Sets the <code>ElementInitializer</code> class that will be used to
* initialize the element.
* <p>Customizing the initialization can also simply be done by
* overloading the <code>initialize()</code> method if the element extends
* the {@link Element} class.
*
* @param initializer the initializer
* @see #initialize()
* @see ElementInitializer
* @since 1.0
*/
public void setInitializer(ElementInitializer initializer)
{
mInitializer = initializer;
}
/**
* Initializes the element, this method should never be called explicitly.
* <p>The initialization happens in a fully setup context and is the first
* method that will be called by the engine.
* <p>The default implementation executes the {@link ElementInitializer}
* that has been registered with {@link #setInitializer}.
*
* @see #setInitializer(ElementInitializer)
* @since 1.0
*/
public void initialize()
{
if (mInitializer != null)
{
mInitializer.initialize();
}
}
/**
* Sets the <code>ElementChildTrigger</code> class that will be used to
* child trigger is executed.
* <p>Customizing the child trigger can also simply be done by overloading
* the <code>childTriggered()</code> method if the element extends the
* {@link Element} class.
*
* @param childTrigger the child trigger
* @see #childTriggered(String, String[])
* @see ElementChildTrigger
* @since 1.0
*/
public void setChildTrigger(ElementChildTrigger childTrigger)
{
mChildTrigger = childTrigger;
}
/**
* Called by the engine when a child trigger occurs, this method should
* never be called explicitly.
* <p>The default implementation executes the {@link ElementChildTrigger}
* that has been registered with {@link #setChildTrigger}.
*
* @param name the name of the variable that initiated the child trigger
* @param values the values of the variable that initiated the child
* trigger
* @return <code>true</code> if the execution should be interrupted and
* step down the inheritance stack (ie. when the activation of the child
* has been triggered); or
* <p><code>false</code> if the execution should just continue
* @see #setChildTrigger(ElementChildTrigger)
* @since 1.0
*/
public boolean childTriggered(String name, String[] values)
{
if (null == mChildTrigger)
{
throw new ChildTriggerNotImplementedException(getClass().getName(), name);
}
return mChildTrigger.childTriggered(name, values);
}
/**
* Set the <code>ElementDeployer</code> class that will be used for
* deployment.
* <p>An instance of this class will be created when the element is
* deployed within a site. The instance's {@link ElementDeployer#deploy()}
* method will be called. This is handy if you need to setup
* element-specific resources for all its instances.
* <p>Customizing the element deployer can also simply be done by
* overloading the <code>getDeploymentClass()</code> method if the element
* extends the {@link Element} class.
*
* @param klass the <code>ElementDeployer</code> that will be used to
* deploy the element
* @see ElementDeployer#deploy()
* @see #getDeploymentClass()
* @see #getDeployer()
* @since 1.0
*/
public void setDeploymentClass(Class<? extends ElementDeployer> klass)
{
mDeploymentClass = klass;
}
/**
* Retrieves the class that will be used for the deployment of the
* element.
*
* @return an instance of <code>ElementDeployer</code>; or
* <p>null if no deployment class is used
* @see #setDeploymentClass(Class)
* @see #getDeployer()
* @since 1.0
*/
public Class getDeploymentClass()
{
return mDeploymentClass;
}
/**
* Changes the access permissions to raw servlet API methods.
* <p>By default, RIFE shields you away from raw access to the servlet API
* and controls all incoming and outgoing data. This makes it possible to
* offer the advanced engine features.
* <p>Sometimes it's useful however to still be able to access the raw
* servlet API features, for instance when integrating other libraries.
* The fact that a method needs to be called before being able to do so
* makes it easy to identify which elements are outside of the controlled
* context of the RIFE application.
*
* @param access <code>true</code> if the raw servlet API access is
* prohibited; or
* <p><code>false</code> if it is allowed
* @see #prohibitRawAccess()
* @since 1.0
*/
public void setProhibitRawAccess(boolean access)
{
mProhibitRawAccess = access;
}
/**
* Indicates whether the access to raw servlet API methods is allowed.
* <p>Instead of using the {@link #setProhibitRawAccess(boolean)} method,
* one can also overload this method to allow raw access. By default, raw
* access is forbidden.
*
* @return <code>true</code> if the raw servlet API access is prohibited;
* or
* <p><code>false</code> if it is allowed
* @see #setProhibitRawAccess(boolean)
* @since 1.0
*/
public boolean prohibitRawAccess()
{
return mProhibitRawAccess;
}
/**
* Changes the engine's behavior when new continuation steps are created.
* <p>By default, the active continuation is cloned when a new step needs
* to be created. This makes it possible to use the browser's back button
* and start a new continuation trail. Each previous step thus keeps it
* associated state. By disabling the cloning, performance will increase
* and memory usage will decrease since the active continuation will
* simply be migrated to the new continuation step. Note that none of the
* previous steps will be usable anymore though.
*
* @param clone <code>true</code> to make the engine clone continuations;
* or
* <p><code>false</code> to disable the cloning
* @see #cloneContinuations()
* @since 1.0
*/
public void setCloneContinuations(boolean clone)
{
mCloneContinuations = clone;
}
/**
* Indicates whether continuations are cloned at each step.
* <p>Instead of using the {@link #setCloneContinuations(boolean)} method,
* one can also overload this method to configure the cloning. By default,
* cloning is active.
*
* @return <code>true</code> to make the engine clone continuations; or
* <p><code>false</code> to disable the cloning
* @see #setCloneContinuations (boolean)
* @since 1.0
*/
public boolean cloneContinuations()
{
return mCloneContinuations;
}
/**
* Pauses the execution of the element and creates a new continuation.
* <p>The next request will resume exactly at the same location with a
* completely restored call stack and variable stack.
*
* @since 1.0
*/
public final void pause()
{
// this is deliberately empty since the continuation support
// rewrites method calls to pause
throw new ContinuationsNotActiveException();
}
/**
* Steps back to the start of the previous continuation.
* <p>If there is no previous continuation, the element will be executed
* from the beginning again.
*
* @see #duringStepBack
* @since 1.5
*/
public final void stepBack()
{
// this is deliberately empty since the continuation support
// rewrites method calls to pause
throw new ContinuationsNotActiveException();
}
/**
* Indicates whether the current element execution is a step back.
*
* @return <code>true</code> if a step back occurred in this request; or
* <p><code>false</code> otherwise
* @see #stepBack
* @since 1.5
*/
public boolean duringStepBack()
{
return mElementContext.duringStepBack();
}
/**
* Pauses the execution of the element and creates a new continuation. The
* execution will immediately continue in the element that is the target
* of the called exit.
* <p>As soon as the called element returns or executes {@link #answer()},
* the execution will resume in the calling element with a completely
* restored call stack and variable stack.
*
* @param exit the name of the exit whose target element will be called
* @return the object that was provided through the {@link #answer(Object)}
* method in the called element; or
* <p><code>null</code> if no answer was provided
* @see #answer()
* @see #answer(Object)
* @since 1.0
*/
public final Object call(String exit)
{
// this is deliberately empty since the continuation support
// rewrites method calls to call
throw new ContinuationsNotActiveException();
}
/**
* Resumes the execution in the calling element by providing no answer
* object.
* <p>The execution in the active element will be interrupted immediately
* and the call continuation will be resumed exactly where is was paused
* before.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException a runtime
* exception that is used to immediately interrupt the execution, don't
* catch this exception
* @see #call(String)
* @see #answer(Object)
* @since 1.0
*/
public final void answer()
throws EngineException
{
// this is deliberately empty since the continuation support
// rewrites method calls to answer
throw new ContinuationsNotActiveException();
}
/**
* Resumes the execution in the calling element by providing an answer.
* <p>The execution in the active element will be interrupted immediately
* and the call continuation will be resumed exactly where is was paused
* before.
*
* @param answer the object that will be answered to the calling element
* @exception com.uwyn.rife.engine.exceptions.EngineException a runtime
* exception that is used to immediately interrupt the execution, don't
* catch this exception
* @see #call(String)
* @see #answer()
* @since 1.0
*/
public final void answer(Object answer)
throws EngineException
{
// this is deliberately empty since the continuation support
// rewrites method calls to answer
throw new ContinuationsNotActiveException();
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEHTML enginehtml}
* type, using the current element's absolute ID as the template name.
* <p>If the element is an arrival, the absolute ID of the real element it
* points to will be used.
*
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getHtmlTemplate(String)
* @see #getHtmlTemplate(String, TemplateTransformer)
* @see #getHtmlTemplate(String, String)
* @see #getHtmlTemplate(String, String, TemplateTransformer)
* @since 1.3
*/
public Template getHtmlTemplate()
throws TemplateException, EngineException
{
return getHtmlTemplate(getElementInfo().getReferenceId().substring(1), null, null);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEHTML enginehtml}
* type.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getHtmlTemplate()
* @see #getHtmlTemplate(String, TemplateTransformer)
* @see #getHtmlTemplate(String, String)
* @see #getHtmlTemplate(String, String, TemplateTransformer)
* @since 1.0
*/
public Template getHtmlTemplate(String name)
throws TemplateException, EngineException
{
return getHtmlTemplate(name, null, null);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEHTML enginehtml}
* type.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @param transformer the template transformer that will be used to modify
* the template's source before it's parsed
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getHtmlTemplate()
* @see #getHtmlTemplate(String)
* @see #getHtmlTemplate(String, String)
* @see #getHtmlTemplate(String, String, TemplateTransformer)
* @since 1.0
*/
public Template getHtmlTemplate(String name, TemplateTransformer transformer)
throws TemplateException, EngineException
{
return getHtmlTemplate(name, null, transformer);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEHTML enginehtml}
* type.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @param encoding the encoding of the template's source
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getHtmlTemplate()
* @see #getHtmlTemplate(String)
* @see #getHtmlTemplate(String, TemplateTransformer)
* @see #getHtmlTemplate(String, String, TemplateTransformer)
* @since 1.0
*/
public Template getHtmlTemplate(String name, String encoding)
throws TemplateException, EngineException
{
return getHtmlTemplate(name, encoding, null);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEHTML enginehtml}
* type.
* <p>The special engine template types contain additional block and value
* filters to offer the following features:
* <ul>
* <li>embedded elements<br>(eg.: <code><!--V
* 'ELEMENT:my.elementid'/--></code>)
* <li>role user context for scripted block assignment to values<br>(eg<code>.:
* <!--V 'OGNL:ROLEUSER:rolecheck'-->User is not in role
* "admin"<!--/V--><br><!--B 'OGNL:ROLEUSER:rolecheck:[[
* isInRole("admin") ]]'-->User is in role "admin"<!--/B--></code>)
* </ul>
* <p>Non-engine versions of the same template types are not able to
* provide these functionalities.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @param encoding the encoding of the template's source
* @param transformer the template transformer that will be used to modify
* the template's source before it's parsed
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getHtmlTemplate()
* @see #getHtmlTemplate(String)
* @see #getHtmlTemplate(String, TemplateTransformer)
* @see #getHtmlTemplate(String, String)
* @since 1.0
*/
public Template getHtmlTemplate(String name, String encoding, TemplateTransformer transformer)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getHtmlTemplate(name, encoding, transformer);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXHTML
* enginexhtml} type, using the current element's absolute ID as the
* template name.
*
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getXhtmlTemplate(String)
* @see #getXhtmlTemplate(String, TemplateTransformer)
* @see #getXhtmlTemplate(String, String)
* @see #getXhtmlTemplate(String, String, TemplateTransformer)
* @since 1.3
*/
public Template getXhtmlTemplate()
throws TemplateException, EngineException
{
return getXhtmlTemplate(getElementInfo().getReferenceId().substring(1), null, null);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXHTML
* enginexhtml} type.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getXhtmlTemplate()
* @see #getXhtmlTemplate(String, TemplateTransformer)
* @see #getXhtmlTemplate(String, String)
* @see #getXhtmlTemplate(String, String, TemplateTransformer)
* @since 1.0
*/
public Template getXhtmlTemplate(String name)
throws TemplateException, EngineException
{
return getXhtmlTemplate(name, null, null);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXHTML
* enginexhtml} type.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @param transformer the template transformer that will be used to modify
* the template's source before it's parsed
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getXhtmlTemplate()
* @see #getXhtmlTemplate(String)
* @see #getXhtmlTemplate(String, String)
* @see #getXhtmlTemplate(String, String, TemplateTransformer)
* @since 1.0
*/
public Template getXhtmlTemplate(String name, TemplateTransformer transformer)
throws TemplateException, EngineException
{
return getXhtmlTemplate(name, null, transformer);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXHTML
* enginexhtml} type.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @param encoding the encoding of the template's source
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getXhtmlTemplate()
* @see #getXhtmlTemplate(String)
* @see #getXhtmlTemplate(String, TemplateTransformer)
* @see #getXhtmlTemplate(String, String, TemplateTransformer)
* @since 1.0
*/
public Template getXhtmlTemplate(String name, String encoding)
throws TemplateException, EngineException
{
return getXhtmlTemplate(name, encoding, null);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXHTML
* enginexhtml} type.
* <p>The special engine template types contain additional block and value
* filters to offer the following features:
* <ul>
* <li>embedded elements<br>(eg.: <code><!--V
* 'ELEMENT:my.elementid'/--></code>)
* <li>role user context for scripted block assignment to values<br>(eg<code>.:
* <!--V 'OGNL:ROLEUSER:rolecheck'-->User is not in role
* "admin"<!--/V--><br><!--B 'OGNL:ROLEUSER:rolecheck:[[
* isInRole("admin") ]]'-->User is in role "admin"<!--/B--></code>)
* </ul>
* <p>Non-engine versions of the same template types are not able to
* provide these functionalities.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @param encoding the encoding of the template's source
* @param transformer the template transformer that will be used to modify
* the template's source before it's parsed
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getXhtmlTemplate()
* @see #getXhtmlTemplate(String)
* @see #getXhtmlTemplate(String, TemplateTransformer)
* @see #getXhtmlTemplate(String, String)
* @since 1.0
*/
public Template getXhtmlTemplate(String name, String encoding, TemplateTransformer transformer)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getXhtmlTemplate(name, encoding, transformer);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXML enginexml}
* type, using the current element's absolute ID as the template name.
*
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getXmlTemplate(String)
* @see #getXmlTemplate(String, TemplateTransformer)
* @see #getXmlTemplate(String, String)
* @see #getXmlTemplate(String, String, TemplateTransformer)
* @since 1.3
*/
public Template getXmlTemplate()
throws TemplateException, EngineException
{
return getXmlTemplate(getElementInfo().getReferenceId().substring(1), null, null);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXML enginexml}
* type.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getXmlTemplate()
* @see #getXmlTemplate(String, TemplateTransformer)
* @see #getXmlTemplate(String, String)
* @see #getXmlTemplate(String, String, TemplateTransformer)
* @since 1.0
*/
public Template getXmlTemplate(String name)
throws TemplateException, EngineException
{
return getXmlTemplate(name, null, null);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXML enginexml}
* type.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @param transformer the template transformer that will be used to modify
* the template's source before it's parsed
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getXmlTemplate(String)
* @see #getXmlTemplate(String)
* @see #getXmlTemplate(String, String)
* @see #getXmlTemplate(String, String, TemplateTransformer)
* @since 1.0
*/
public Template getXmlTemplate(String name, TemplateTransformer transformer)
throws TemplateException, EngineException
{
return getXmlTemplate(name, null, transformer);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXML enginexml}
* type.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @param encoding the encoding of the template's source
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getXmlTemplate(String)
* @see #getXmlTemplate(String)
* @see #getXmlTemplate(String, TemplateTransformer)
* @see #getXmlTemplate(String, String, TemplateTransformer)
* @since 1.0
*/
public Template getXmlTemplate(String name, String encoding)
throws TemplateException, EngineException
{
return getXmlTemplate(name, encoding, null);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINEXML enginexml}
* type.
* <p>The special engine template types contain additional block and value
* filters to offer the following features:
* <ul>
* <li>embedded elements<br>(eg.: <code><!--V
* 'ELEMENT:my.elementid'/--></code>)
* <li>role user context for scripted block assignment to values<br>(eg<code>.:
* <!--V 'OGNL:ROLEUSER:rolecheck'-->User is not in role
* "admin"<!--/V--><br><!--B 'OGNL:ROLEUSER:rolecheck:[[
* isInRole("admin") ]]'-->User is in role "admin"<!--/B--></code>)
* </ul>
* <p>Non-engine versions of the same template types are not able to
* provide these functionalities.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @param encoding the encoding of the template's source
* @param transformer the template transformer that will be used to modify
* the template's source before it's parsed
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getXmlTemplate(String)
* @see #getXmlTemplate(String)
* @see #getXmlTemplate(String, TemplateTransformer)
* @see #getXmlTemplate(String, String)
* @since 1.0
*/
public Template getXmlTemplate(String name, String encoding, TemplateTransformer transformer)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getXmlTemplate(name, encoding, transformer);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINETXT enginetxt}
* type, using the current element's absolute ID as the template name.
*
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getTxtTemplate(String)
* @see #getTxtTemplate(String, TemplateTransformer)
* @see #getTxtTemplate(String, String)
* @see #getTxtTemplate(String, String, TemplateTransformer)
* @since 1.3
*/
public Template getTxtTemplate()
throws TemplateException, EngineException
{
return getTxtTemplate(getElementInfo().getReferenceId().substring(1), null, null);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINETXT enginetxt}
* type.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getTxtTemplate()
* @see #getTxtTemplate(String, TemplateTransformer)
* @see #getTxtTemplate(String, String)
* @see #getTxtTemplate(String, String, TemplateTransformer)
* @since 1.0
*/
public Template getTxtTemplate(String name)
throws TemplateException, EngineException
{
return getTxtTemplate(name, null, null);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINETXT enginetxt}
* type.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @param transformer the template transformer that will be used to modify
* the template's source before it's parsed
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getTxtTemplate()
* @see #getTxtTemplate(String)
* @see #getTxtTemplate(String, String)
* @see #getTxtTemplate(String, String, TemplateTransformer)
* @since 1.0
*/
public Template getTxtTemplate(String name, TemplateTransformer transformer)
throws TemplateException, EngineException
{
return getTxtTemplate(name, null, transformer);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINETXT enginetxt}
* type.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @param encoding the encoding of the template's source
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getTxtTemplate()
* @see #getTxtTemplate(String)
* @see #getTxtTemplate(String, TemplateTransformer)
* @see #getTxtTemplate(String, String, TemplateTransformer)
* @since 1.0
*/
public Template getTxtTemplate(String name, String encoding)
throws TemplateException, EngineException
{
return getTxtTemplate(name, encoding, null);
}
/**
* Creates a new template instance of the {@link
* com.uwyn.rife.template.TemplateFactoryEngineTypes#ENGINETXT enginetxt}
* type.
* <p>The special engine template types contain additional block and value
* filters to offer the following features:
* <ul>
* <li>embedded elements<br>(eg.: <code>[!V 'ELEMENT:my.elementid'/]</code>)
* <li>role user context for scripted block assignment to values<br>(eg<code>.:
* [!V 'OGNL:ROLEUSER:rolecheck']User is not in role "admin"[!/V]<br>[!B
* 'OGNL:ROLEUSER:rolecheck:[[ isInRole("admin") ]]']User is in role
* "admin"[!/B]</code>)
* </ul>
* <p>Non-engine versions of the same template types are not able to
* provide these functionalities.
*
* @param name the name of the template. Note that this follows the Java
* naming conventions for classes and packages. Directories correspond to
* package names and file separators correspond to dots. Any non-valid
* class name character will be replaced by an underscore.
* @param encoding the encoding of the template's source
* @param transformer the template transformer that will be used to modify
* the template's source before it's parsed
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurred during the retrieval, parsing or compilation of the
* template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the initialization of the template in the element
* context; or if you don't have access to the request data (eg. you're
* inside a child trigger); or if there's no active element context (eg.
* you're using this method inside the constructor instead of inside the
* {@link #initialize()} method)
* @return a new instance of the template
* @see #getTxtTemplate()
* @see #getTxtTemplate(String)
* @see #getTxtTemplate(String, TemplateTransformer)
* @see #getTxtTemplate(String, String)
* @since 1.0
*/
public Template getTxtTemplate(String name, String encoding, TemplateTransformer transformer)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getTxtTemplate(name, encoding, transformer);
}
/**
* Transforms a provided <code>String</code> object into a new string,
* containing only valid HTML characters.
*
* @param source The string that has to be transformed into a valid HTML
* string.
* @return The encoded <code>String</code> object.
* @see #encodeXml(String)
* @since 1.0
*/
public String encodeHtml(String source)
{
return StringUtils.encodeHtml(source);
}
/**
* Transforms a provided <code>String</code> object into a new string,
* containing only valid XML characters.
*
* @param source The string that has to be transformed into a valid XML
* string.
* @return The encoded <code>String</code> object.
* @see #encodeHtml(String)
* @since 1.0
*/
public String encodeXml(String source)
{
return StringUtils.encodeXml(source);
}
/**
* Enables or disables the response text buffer. By default, it is
* enabled.
* <p>Disabling an enabled text buffer, flushes the already buffered
* content first.
* <p>If the text buffer is disabled, text content will be send
* immediately to the client, this can decrease performance. Unless you
* need to stream content in real time, it's best to leave the text buffer
* enabled. It will be flushed and sent in one go at the end of the
* request.
* <p>Exits that cancel embedding rely on the fact that the text buffer is
* active to be able to discard the partial content of the embedding
* element.
*
* @param enabled <code>true</code> to enable the text buffer; or
* <p><code>false</code> to disable it
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurred during the modification of the text buffer presence; or if you
* don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #isTextBufferEnabled()
* @see #flush()
* @see #clearBuffer()
* @since 1.0
*/
public void enableTextBuffer(boolean enabled)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().enableTextBuffer(enabled);
}
/**
* Indicates whether the response text buffer is enabled or disabled.
*
* @return <code>true</code> if the text buffer is enabled; or
* <p><code>false</code> if it is disabled
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #enableTextBuffer(boolean)
* @see #flush()
* @see #clearBuffer()
* @since 1.0
*/
public boolean isTextBufferEnabled()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getResponse().isTextBufferEnabled();
}
/**
* Prints the content of a template to the request text output. The
* template is first processed in the active element context by the {@link
* #processTemplate(Template)} method.
*
* @param template the template that will be printed
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurs during the retrieval of the template content
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the output of the template content; or if you don't have
* access to the request data (eg. you're inside a child trigger); or if
* there's no active element context (eg. you're using this method inside
* the constructor instead of inside the {@link #initialize()} method)
* @see #print(Object)
* @see #processTemplate(Template)
* @since 1.0
*/
public void print(Template template)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
mElementContext.print(template);
}
/**
* Processes a template in the active element context.
* <p>This performs the following value replacements if they haven't
* already been set.
* <p>Each template type can have a value encoder attached to it (for
* instance a HTML encoder to replace non-ascii characters with the
* appropriate entities). All variable content that is handled in this
* method will be encoded before being set in the template.
* <table border="0">
* <tr>
* <td><code>OGNL:ROLEUSER:valueid<br><code>GROOVY:ROLEUSER:valueid<br></code><code>JANINO:ROLEUSER:valueid<br></code></code>
* <td>These scripted block value tags will be processed according to the
* active element context.
* <p>For example: <code><!--V 'OGNL:ROLEUSER:rolecheck'-->User is
* no admin<!--/V--><br><!--B 'OGNL:ROLEUSER:rolecheck:[[
* isInRole("admin") ]]'-->User is admin<!--/B--></code>
* <p>Will display '<code>User is admin</code>' if the user has the admin
* role, and otherwise '<code>User is no admin</code>'.
* <tr>
* <td><code>EXIT:QUERY:exitname</code>
* <td>Will be replaced with the URL that links to the target of the named
* exit. The state will be carried around according to the currently set
* outputs.
* <tr>
* <td><code>EXIT:FORM:exitname</code>
* <td>Will be replaced with the URL that links to the target of the named
* exit. No state information will be added to the URL. The
* <code>EXIT:PARAMS</code> value tag should be put at the location where
* hidden form parameters are allowed.
* <tr>
* <td><code>EXIT:PARAMS:exitname</code>
* <td>Will be replaced by the hidden form parameters that are need to
* carry the state around according to the currently set outputs. This tag
* goes hand-in-hand with the <code>EXIT:FORM</code> tag.
* <tr>
* <td><code>SUBMISSION:QUERY:submissionname</code>
* <td>Will be replaced with the URL that sends the named submission to
* currently the active element. The state will be carried around
* according to the currently set inputs.
* <tr>
* <td><code>SUBMISSION:FORM:submissionname</code>
* <td>Will be replaced with the URL that sends the named submission to
* currently the active element. No state information will be added to the
* URL. The <code>SUBMISSION:PARAMS</code> value tag should be put at the
* location where hidden form parameters are allowed.
* <tr>
* <td><code>SUBMISSION:PARAMS:submissionname</code>
* <td>Will be replaced by the hidden form parameters that are need to
* carry the state around according to the currently set inputs. This tag
* goes hand-in-hand with the <code>SUBMISSION:FORM</code> tag.
* <tr>
* <td><code>PARAM:name</code>
* <td>Will be replaced with the encoded content of the named submission
* parameter.
* <tr>
* <td><code>INPUT:name</code>
* <td>Will be replaced with the encoded content of the named input.
* <tr>
* <td><code>OUTPUT:name</code>
* <td>Will be replaced with the encoded content of the named output.
* <tr>
* <td><code>INCOOKIE:name</code>
* <td>Will be replaced with the encoded content of the named incookie.
* <tr>
* <td><code>OUTCOOKIE:nam</code>
* <td>Will be replaced with the encoded content of the named outcookie.
* <tr>
* <td><code>WEBAPP:ROOTURL</code>
* <td>Will be replaced with the absolute root URL of the web application.
* This is typically used in a <base href=""> tag. All URLs can then
* be relative according to this root URL and the application can be used
* anywhere and with any web application name.
* <tr>
* <td>automated form building for submission beans
* <td>see {@link com.uwyn.rife.site.FormBuilder}
* </table>
*
* @param template the template instance that needs to be processed
* @exception com.uwyn.rife.template.exceptions.TemplateException if an
* error occurs during the manipulation of the template
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the retrieval of the values from the current element
* context, or during the output of the template content; or if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return a list with the ids of all the template values that have been
* set
* @since 1.0
*/
public List<String> processTemplate(Template template)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
return mElementContext.processTemplate(template);
}
/**
* Prints the string representation of an object to the request text
* output. The string representation will be created through a
* <code>String.valueOf(value)</code> call.
*
* @param value the object that will be output
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the output of the content; or if you don't have access to
* the request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @since 1.0
*/
public void print(Object value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().print(value);
}
/**
* Retrieves an output stream to send binary data through the response.
* <p>Note that the text output is written to the same output stream. Of
* course, when the text buffer is active this only happen at the end of
* the request.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the creation of the output stream; or if you don't have
* access to the request data (eg. you're inside a child trigger); or if
* there's no active element context (eg. you're using this method inside
* the constructor instead of inside the {@link #initialize()} method)
* @return an instance of the response output stream
* @since 1.0
*/
public OutputStream getOutputStream()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getResponse().getOutputStream();
}
/**
* Clears the request text output buffer, all buffered text will be
* discarded.
* <p>If no text buffer is active, this method doesn't do anything.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #isTextBufferEnabled()
* @see #enableTextBuffer(boolean)
* @see #flush()
* @since 1.0
*/
public void clearBuffer()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().clearBuffer();
}
/**
* Flushes the request text output buffer and the request output stream.
* This sends any buffered data immediately to the client.
* <p>All text in the active buffer will be sent to the client and the
* buffer will be empty again, if no text buffer is enabled only the
* output stream will be flushed.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurs during the output of the content; or if you don't have access to
* the request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #isTextBufferEnabled()
* @see #enableTextBuffer(boolean)
* @see #clearBuffer()
* @since 1.0
*/
public void flush()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().flush();
}
/**
* Retrieves the site in which this element is declared.
*
* @return a site instance
* @exception com.uwyn.rife.engine.exceptions.EngineException if the
* element information hasn't been provided yet (eg. you're using this
* method inside the constructor instead of inside the {@link
* #initialize()} method)
* @since 1.0
*/
public Site getSite()
throws EngineException
{
if (null == mElementInfo) throw new ElementInfoMissingException();
return mElementInfo.getSite();
}
/**
* Retrieves the deployer of this element.
*
* @return the instance of the deployer that was used to deploy the
* element; or
* <p><code>null</code> if no deployment class has been declared
* @exception com.uwyn.rife.engine.exceptions.EngineException if the
* element information hasn't been provided yet (eg. you're using this
* method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #getDeploymentClass()
* @see #setDeploymentClass(Class)
* @since 1.0
*/
public ElementDeployer getDeployer()
throws EngineException
{
if (null == mElementInfo) throw new ElementInfoMissingException();
return mElementInfo.getDeployer();
}
/**
* Retrieves the declaration information of this element.
*
* @return the declaration information of this element
* @exception com.uwyn.rife.engine.exceptions.EngineException if the
* element information hasn't been provided yet (eg. you're using this
* method inside the constructor instead of inside the {@link
* #initialize()} method)
* @since 1.0
*/
public ElementInfo getElementInfo()
throws EngineException
{
if (null == mElementInfo) throw new ElementInfoMissingException();
return _getElementInfo();
}
ElementInfo _getElementInfo()
throws EngineException
{
return mElementInfo;
}
/**
* Retrieves the source implementation name of this element.
*
* @return the source implementation name
* @exception com.uwyn.rife.engine.exceptions.EngineException if the
* element information hasn't been provided yet (eg. you're using this
* method inside the constructor instead of inside the {@link
* #initialize()} method)
* @since 1.0
*/
public String getSourceName()
throws EngineException
{
if (null == mElementInfo) throw new ElementInfoMissingException();
return mElementInfo.getImplementation();
}
/**
* Retrieves the declaration name of this element.
*
* @return the declaration name
* @exception com.uwyn.rife.engine.exceptions.EngineException if the
* element information hasn't been provided yet (eg. you're using this
* method inside the constructor instead of inside the {@link
* #initialize()} method)
* @since 1.0
*/
public String getDeclarationName()
throws EngineException
{
if (null == mElementInfo) throw new ElementInfoMissingException();
return mElementInfo.getDeclarationName();
}
/**
* Retrieves the information of the target element of the active request.
* <p>This can be different from the current element due to precedence,
* behavioural inheritance, child triggers, element embedding, ...
*
* @return the request's target element information
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @since 1.0
*/
public ElementInfo getTarget()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getTarget();
}
/**
* Retrieves the element that is embedding the current element.
*
* @return the embedding element; or
* <p><code>null</code> if this element is not embedded
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getEmbeddingTemplate()
* @see #getEmbedDifferentiator()
* @see #hasEmbedValue()
* @see #getEmbedValue()
* @see #hasEmbedData()
* @see #getEmbedData()
* @see #getEmbedProperties()
* @see #isEmbedded()
* @since 1.0
*/
public ElementSupport getEmbeddingElement()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
EmbeddingContext embedding_context = mElementContext.getRequestState().getEmbeddingContext();
if (null == embedding_context)
{
return null;
}
return embedding_context.getEmbeddingElement();
}
/**
* Retrieves the template that is embedding the current element.
*
* @return the embedding template; or
* <p><code>null</code> if this element is not embedded
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getEmbeddingElement()
* @see #getEmbedDifferentiator()
* @see #hasEmbedValue()
* @see #getEmbedValue()
* @see #hasEmbedData()
* @see #getEmbedData()
* @see #getEmbedProperties()
* @see #isEmbedded()
* @since 1.0
*/
public Template getEmbeddingTemplate()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
EmbeddingContext embedding_context = mElementContext.getRequestState().getEmbeddingContext();
if (null == embedding_context)
{
return null;
}
return embedding_context.getTemplate();
}
/**
* Retrieves the differentiator that was used to set this embedded element apart.
*
* @return this embedded element's differentiator; or
* <p><code>null</code> if this embedded element didn't have a differentiator
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getEmbeddingTemplate()
* @see #getEmbeddingElement()
* @see #hasEmbedValue()
* @see #getEmbedValue()
* @see #hasEmbedData()
* @see #getEmbedData()
* @see #getEmbedProperties()
* @see #isEmbedded()
* @since 1.0
*/
public String getEmbedDifferentiator()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getEmbedDifferentiator();
}
/**
* Indicates whether the embedded element's template value has content.
*
* @return <code>true</code> if the value has content; or
* <p><code>false</code> otherwise
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getEmbeddingTemplate()
* @see #getEmbeddingElement()
* @see #getEmbedDifferentiator()
* @see #getEmbedValue()
* @see #hasEmbedData()
* @see #getEmbedData()
* @see #getEmbedProperties()
* @see #isEmbedded()
* @since 1.0
*/
public boolean hasEmbedValue()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getEmbedValue() != null;
}
/**
* Retrieves the current content of the value tag of this embedded element.
* <p>For example:
* <pre><!--V 'ELEMENT:my.element'-->this is the embed value<!--/V--></pre>
* <p>Will return:
* <pre>this is the embed value</pre>
* <p>Note that when you have several embedded elements in the same
* template with the same element id, you have to use embedded element
* differentiators if you want to provide different embed values. For
* example:
* <pre><!--V 'ELEMENT:my.element:differentiator1'-->this is the first embed value<!--/V-->
*<!--V 'ELEMENT:my.element:differentiator2'-->this is the second embed value<!--/V--></pre>
*
* @return the value from the embedded template; or
* <p>null if no default value was provided or if the current element is
* not embedded
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getEmbeddingTemplate()
* @see #getEmbeddingElement()
* @see #getEmbedDifferentiator()
* @see #hasEmbedValue()
* @see #getEmbedData()
* @see #hasEmbedData()
* @see #getEmbedProperties()
* @see #isEmbedded()
* @since 1.0
*/
public String getEmbedValue()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getEmbedValue();
}
/**
* Indicates whether data was passed on during the processing of this embedded element.
*
* @return <code>true</code> if data was passed on; or
* <p><code>false</code> otherwise
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getEmbeddingTemplate()
* @see #getEmbeddingElement()
* @see #getEmbedDifferentiator()
* @see #hasEmbedValue()
* @see #getEmbedValue()
* @see #getEmbedData()
* @see #getEmbedProperties()
* @see #isEmbedded()
* @since 1.0
*/
public boolean hasEmbedData()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getEmbedValue() != null;
}
/**
* Retrieves the data that was passed on for the processing of this embedded element.
* @return the value from the embedded template; or
* <p>null if no data was provided or if the current element is
* not embedded
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getEmbeddingTemplate()
* @see #getEmbeddingElement()
* @see #getEmbedDifferentiator()
* @see #getEmbedValue()
* @see #hasEmbedValue()
* @see #hasEmbedData()
* @see #getEmbedProperties()
* @see #isEmbedded()
* @since 1.5
*/
public Object getEmbedData()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getEmbedData();
}
/**
* Retrieves the embed value as a property list (see {@link
* #getEmbedValue()} for more information about embed values).
* <p>The content of the embed value will be parsed as a property list
* according to the format described in {@link
* java.util.Properties#load(java.io.InputStream)}.
* <p>For instance:
* <pre><!--V 'ELEMENT:my.element'-->
*key1 = value1
*key2 = value1
*<!--/V--></pre>
* <p>Will return a property list where the key '<code>key1</code>' is
* associated to '<code>value1</code>' and '<code>key2</code>' to '<code>value2</code>'.
*
* @return the embed value parsed as a property list; or
* <p>null if no default value was provided, if the current element is not
* embedded
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getEmbeddingTemplate()
* @see #getEmbeddingElement()
* @see #getEmbedDifferentiator()
* @see #hasEmbedValue()
* @see #getEmbedValue()
* @see #hasEmbedData()
* @see #isEmbedded()
* @since 1.0
*/
public Properties getEmbedProperties()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getEmbedProperties();
}
/**
* Indicates whether this element is running embedded inside another
* element's template.
*
* @return <code>true</code> if this element is embedded; or
* <p><code>false</code> otherwise
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getEmbeddingTemplate()
* @see #getEmbeddingElement()
* @see #getEmbedDifferentiator()
* @see #hasEmbedValue()
* @see #getEmbedValue()
* @see #hasEmbedData()
* @see #getEmbedProperties()
* @since 1.4
*/
public boolean isEmbedded()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().isEmbedded();
}
/**
* Indicates whether this element has a certain injected named property.
*
* @param name the name of the property
* @exception com.uwyn.rife.engine.exceptions.EngineException if the
* element information hasn't been provided yet (eg. you're using this
* method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return <code>true</code> if the element contains the property; or
* <p><code>false</code> otherwise
* @see #getProperty(String)
* @see #getProperty(String, Object)
* @see #getPropertyTyped(String, Class)
* @see #getPropertyTyped(String, Class, Object)
* @see #getPropertyString(String)
* @see #getPropertyString(String, String)
* @see #isPropertyEmpty(String)
* @since 1.0
*/
public boolean hasProperty(String name)
throws EngineException
{
if (null == mElementInfo) throw new ElementInfoMissingException();
return mElementInfo.containsProperty(name);
}
/**
* Retrieves the value of an injected named property.
* <p>Note that there are two types of properties, fixed value properties
* ({@link com.uwyn.rife.ioc.PropertyValueObject string literals}) and dynamic value
* properties ({@link com.uwyn.rife.ioc.PropertyValueParticipant participant objects},
* {@link com.uwyn.rife.ioc.PropertyValueTemplate template instances}, ...). The fixed value
* is set during the declaration of the property and the dynamic value is
* retrieved or instantiated each time the property value is obtained.
* <p>Property values can be of any type and class. If the resulting value
* needs to be a certain standard type or primitive value, use the {@link
* com.uwyn.rife.tools.Convert} helper class to perform the conversion
* in-line. Since properties are very often used as string literals,
* there's {@link #getPropertyString(String)} method to make this more
* convenient.
*
* @param name the name of the property
* @exception com.uwyn.rife.engine.exceptions.EngineException if the
* element information hasn't been provided yet (eg. you're using this
* method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the property value; or
* <p><code>null</code> if no such property exists
* @see #hasProperty(String)
* @see #getProperty(String, Object)
* @see #getPropertyTyped(String, Class)
* @see #getPropertyTyped(String, Class, Object)
* @see #getPropertyString(String)
* @see #getPropertyString(String, String)
* @see #isPropertyEmpty(String)
* @since 1.0
*/
public Object getProperty(String name)
throws EngineException
{
if (null == mElementInfo) throw new ElementInfoMissingException();
return mElementInfo.getProperty(name);
}
/**
* Retrieves the value of an injected named property, using a default value
* as fallback.
*
* @param name the name of the property
* @param defaultValue the value that should be used if the
* property can't be found
* @exception com.uwyn.rife.engine.exceptions.EngineException if the
* element information hasn't been provided yet (eg. you're using this
* method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the property value; or
* <p>the default value if no such property exists
* @see #hasProperty(String)
* @see #getProperty(String)
* @see #getPropertyTyped(String, Class)
* @see #getPropertyTyped(String, Class, Object)
* @see #getPropertyString(String)
* @see #getPropertyString(String, String)
* @see #isPropertyEmpty(String)
* @since 1.0
*/
public Object getProperty(String name, Object defaultValue)
throws EngineException
{
if (null == mElementInfo) throw new ElementInfoMissingException();
return mElementInfo.getProperty(name, defaultValue);
}
/**
* Retrieves the value of an injected named property and converts it to the
* specified type.
* <p>This method has advantages over a regular cast, since it throws a
* meaningful exception to the user in case the type of the property value
* is not compatible.
*
* @param name the name of the property
* @param type the class you want the property to be converted to
* @exception com.uwyn.rife.engine.exceptions.EngineException if the
* element information hasn't been provided yet (eg. you're using this
* method inside the constructor instead of inside the {@link
* #initialize()} method)
* @exception com.uwyn.rife.engine.exceptions.PropertyIncompatibleTypeException
* if the type of the property value wasn't compatible with the requested type
* @return the property value, casted to the requested type; or
* <p><code>null</code> if no such property exists
* @see #hasProperty(String)
* @see #getProperty(String)
* @see #getProperty(String, Object)
* @see #getPropertyTyped(String, Class, Object)
* @see #getPropertyString(String)
* @see #getPropertyString(String, String)
* @see #isPropertyEmpty(String)
* @since 1.3
*/
public <T> T getPropertyTyped(String name, Class<T> type)
{
if (null == mElementInfo) throw new ElementInfoMissingException();
return (T)mElementInfo.getPropertyTyped(name, type);
}
/**
* Retrieves the value of an injected named property and converts it to the
* specified type, using a default value as fallback.
* <p>This method has advantages over a regular cast, since it throws a
* meaningful exception to the user in case the type of the property value
* is not compatible.
*
* @param name the name of the property
* @param type the class you want the property to be converted to
* @param defaultValue the object that should be used if the
* property can't be found
* @exception com.uwyn.rife.engine.exceptions.EngineException if the
* element information hasn't been provided yet (eg. you're using this
* method inside the constructor instead of inside the {@link
* #initialize()} method)
* @exception com.uwyn.rife.engine.exceptions.PropertyIncompatibleTypeException
* if the type of the property value wasn't compatible with the requested type
* @return the property value, casted to the requested type; or
* <p>the default value if no such property exists
* @see #hasProperty(String)
* @see #getProperty(String)
* @see #getProperty(String, Object)
* @see #getPropertyTyped(String, Class)
* @see #getPropertyString(String)
* @see #getPropertyString(String, String)
* @see #isPropertyEmpty(String)
* @since 1.3
*/
public <T> T getPropertyTyped(String name, Class<T> type, T defaultValue)
{
if (null == mElementInfo) throw new ElementInfoMissingException();
return (T)mElementInfo.getPropertyTyped(name, type, defaultValue);
}
/**
* Retrieves the value of an injected named property and converts it to a
* string.
*
* @param name the name of the property
* @exception com.uwyn.rife.engine.exceptions.EngineException if the
* element information hasn't been provided yet (eg. you're using this
* method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the string representation of the property value; or
* <p><code>null</code> if no such property exists
* @see #hasProperty(String)
* @see #getProperty(String)
* @see #getProperty(String, Object)
* @see #getPropertyTyped(String, Class)
* @see #getPropertyTyped(String, Class, Object)
* @see #getPropertyString(String, String)
* @see #isPropertyEmpty(String)
* @since 1.0
*/
public String getPropertyString(String name)
throws EngineException
{
if (null == mElementInfo) throw new ElementInfoMissingException();
return mElementInfo.getPropertyString(name);
}
/**
* Retrieves the value of an injected named property and converts it to a
* string, using a default value as fallback.
*
* @param name the name of the property
* @param defaultValue the string literal that should be used if the
* property can't be found
* @exception com.uwyn.rife.engine.exceptions.EngineException if the
* element information hasn't been provided yet (eg. you're using this
* method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the string representation of the property value; or
* <p>the default value if no such property exists or when the resulting
* string is empty
* @see #hasProperty(String)
* @see #getProperty(String)
* @see #getProperty(String, Object)
* @see #getPropertyTyped(String, Class)
* @see #getPropertyTyped(String, Class, Object)
* @see #getPropertyString(String)
* @see #isPropertyEmpty(String)
* @since 1.0
*/
public String getPropertyString(String name, String defaultValue)
throws EngineException
{
if (null == mElementInfo) throw new ElementInfoMissingException();
return mElementInfo.getPropertyString(name, defaultValue);
}
/**
* Checks if a property is not available or if the string presentation is
* empty.
*
* @param name the name of the property
* @exception com.uwyn.rife.engine.exceptions.EngineException if the
* element information hasn't been provided yet (eg. you're using this
* method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return <code>true</code> if the property is empty; or
* <p><code>false</code> otherwise
* @see #hasProperty(String)
* @see #getProperty(String)
* @see #getProperty(String, Object)
* @see #getPropertyTyped(String, Class)
* @see #getPropertyTyped(String, Class, Object)
* @see #getPropertyString(String)
* @see #getPropertyString(String, String)
* @since 1.0
*/
public boolean isPropertyEmpty(String name)
throws EngineException
{
if (null == mElementInfo) throw new ElementInfoMissingException();
return mElementInfo.isPropertyEmpty(name);
}
/**
* Retrieves an instance of a named input bean and populates the
* properties with the input values. The class of the bean is looked up
* through its name, as is the property prefix.
* <p>This bean is not serialized or deserialized, each property
* corresponds to an input and is individually sent by the client.
*
* @param name the name of the input bean
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* bean is known with this name; or if an error occurred during the
* instantiation of the bean; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the populated input bean instance
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public <BeanType> BeanType getNamedInputBean(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return (BeanType)mElementContext.getNamedInputBean(name);
}
/**
* Retrieves an instance of an input bean and populates the properties
* with the input values.
* <p>This bean is not serialized or de-serialized, each property
* corresponds to an input and is individually sent by the client.
*
* @param beanClass the class of the input bean
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurred during the instantiation of the bean; or if you don't have
* access to the request data (eg. you're inside a child trigger); or if
* there's no active element context (eg. you're using this method inside
* the constructor instead of inside the {@link #initialize()} method)
* @return the populated input bean instance
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public <BeanType> BeanType getInputBean(Class<BeanType> beanClass)
throws EngineException
{
return getInputBean(beanClass, null);
}
/**
* Retrieves an instance of an input bean and populates the properties
* with the input values, taking the provided prefix into account.
* <p>This bean is not serialized or de-serialized, each property
* corresponds to an input and is individually sent by the client.
*
* @param beanClass the class of the input bean
* @param prefix the prefix that will be put in front of each property
* name
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurred during the instantiation of the bean; or if you don't have
* access to the request data (eg. you're inside a child trigger); or if
* there's no active element context (eg. you're using this method inside
* the constructor instead of inside the {@link #initialize()} method)
* @return the populated input bean instance
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public <BeanType> BeanType getInputBean(Class<BeanType> beanClass, String prefix)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == beanClass) throw new IllegalArgumentException("beanClass can't be null.");
return mElementContext.getInputBean(beanClass, prefix);
}
/**
* Checks whether a value has been provided to an input.
*
* @param name the name of the input
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return <code>true</code> if the input has a value; or
* <p><code>false</code> otherwise
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public boolean hasInputValue(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.hasInputValue(name);
}
/**
* Checks whether an input has no value or whether the value is empty.
*
* @param name the name of the input
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return <code>true</code> if the input has no value or when the value
* is empty; or
* <p><code>false</code> otherwise
* @see #hasInputValue(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public boolean isInputEmpty(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.isInputEmpty(name);
}
/**
* Retrieves the value of an input.
*
* @param name the name of the input
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the value of the input; or
* <p><code>null</code> if no value is present for this input
* @since 1.0
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String, String)
* @see #getInputValues(String)
*/
public String getInput(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.getInput(name);
}
/**
* Retrieves the value of an input and returns a default value if no input
* value is present
*
* @param name the name of the input
* @param defaultValue the default value that will be used when no input
* value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the input value; or
* <p>the default value if no input value is present
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInputValues(String)
* @since 1.0
*/
public String getInput(String name, String defaultValue)
throws EngineException
{
String input = getInput(name);
if (input == null)
{
return defaultValue;
}
return input;
}
/**
* Retrieves the value of a serialized input.
*
* @param name the name of the input
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the deserialized input
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInputValues(String)
* @since 1.3.1
*/
public <TargetType extends Serializable> TargetType getInputSerializable(String name)
throws EngineException
{
return (TargetType)getInputSerializable(name, null);
}
/**
* Retrieves the value of a serialized input and returns a default value if no input
* value is present
*
* @param name the name of the input
* @param defaultValue the default value that will be used when no input
* value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the deserialized input; or
* <p>the default value if no input value is present
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInputValues(String)
* @since 1.3.1
*/
public <TargetType extends Serializable> TargetType getInputSerializable(String name, TargetType defaultValue)
throws EngineException
{
String input = getInput(name);
if (input == null)
{
return defaultValue;
}
try
{
return (TargetType)SerializationUtils.deserializeFromString(input);
}
catch (SerializationUtilsErrorException e)
{
throw new InputsDeserializationException(getDeclarationName(), name, e);
}
}
/**
* Retrieves the value of an input and converts it to a Date.
*
* @param name the name of the input
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the converted input value; or
* <p>{@code null} if the input didn't have a value
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.6.1
*/
public Date getInputDate(String name)
throws EngineException
{
return getInputDate(name, null);
}
/**
* Retrieves the value of an input and converts it to a Date, using a
* default value if no input value is present.
*
* @param name the name of the input
* @param defaultValue the default value that will be used when no input
* value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the converted input value; or
* <p>the default value if no input value is present
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.6.1
*/
public Date getInputDate(String name, Date defaultValue)
throws EngineException
{
String input = getInput(name);
if (input == null)
{
return defaultValue;
}
try
{
return (Date)Convert.toDate(input);
}
catch (ConversionException e)
{
throw new EngineException(e);
}
}
/**
* Retrieves the values of an input.
*
* @param name the name of the input
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return a string array with all the input values; or
* <p><code>null</code> if no input values are present
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @since 1.0
*/
public String[] getInputValues(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.getInputValues(name);
}
/**
* Retrieves the value of an input and converts it to a boolean.
*
* @param name the name of the input
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the converted input value; or
* <p><code>false</code> if no input value is present or if the input
* value is not a valid boolean
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public boolean getInputBoolean(String name)
throws EngineException
{
return getInputBoolean(name, ElementInfo.DEFAULT_BOOLEAN);
}
/**
* Retrieves the value of an input and converts it to a boolean, using a
* default value if no input value is present.
*
* @param name the name of the input
* @param defaultValue the default value that will be used when no input
* value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the converted input value; or
* <p>the default value if no input value is present
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public boolean getInputBoolean(String name, boolean defaultValue)
throws EngineException
{
String value = getInput(name);
if (value == null)
{
return defaultValue;
}
return StringUtils.convertToBoolean(value);
}
/**
* Retrieves the value of an input and converts it to an integer.
*
* @param name the name of the input
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the converted input value; or
* <p><code>0</code> if no input value is present or if the input value is
* not a valid integer
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public int getInputInt(String name)
throws EngineException
{
return getInputInt(name, ElementInfo.DEFAULT_INTEGER);
}
/**
* Retrieves the value of an input and converts it to an integer, using a
* default value if no input value is present.
*
* @param name the name of the input
* @param defaultValue the default value that will be used when no input
* value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the converted input value; or
* <p>the default value if no input value is present
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public int getInputInt(String name, int defaultValue)
throws EngineException
{
String value = getInput(name);
if (value == null)
{
return defaultValue;
}
try
{
return Integer.parseInt(value);
}
catch (NumberFormatException e)
{
return defaultValue;
}
}
/**
* Retrieves the value of an input and converts it to a long.
*
* @param name the name of the input
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the converted input value; or
* <p><code>0L</code> if no input value is present or if the input value
* is not a valid long
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public long getInputLong(String name)
throws EngineException
{
return getInputLong(name, ElementInfo.DEFAULT_LONG);
}
/**
* Retrieves the value of an input and converts it to a long, using a
* default value if no input value is present.
*
* @param name the name of the input
* @param defaultValue the default value that will be used when no input
* value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the converted input value; or
* <p>the default value if no input value is present
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public long getInputLong(String name, long defaultValue)
throws EngineException
{
String value = getInput(name);
if (value == null)
{
return defaultValue;
}
try
{
return Long.parseLong(value);
}
catch (NumberFormatException e)
{
return defaultValue;
}
}
/**
* Retrieves the value of an input and converts it to a double.
*
* @param name the name of the input
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the converted input value; or
* <p><code>0.0d</code> if no input value is present or if the input value
* is not a valid double
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public double getInputDouble(String name)
throws EngineException
{
return getInputDouble(name, ElementInfo.DEFAULT_DOUBLE);
}
/**
* Retrieves the value of an input and converts it to a double, using a
* default value if no input value is present.
*
* @param name the name of the input
* @param defaultValue the default value that will be used when no input
* value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the converted input value; or
* <p>the default value if no input value is present
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public double getInputDouble(String name, double defaultValue)
throws EngineException
{
String value = getInput(name);
if (value == null)
{
return defaultValue;
}
try
{
return Double.parseDouble(value);
}
catch (NumberFormatException e)
{
return defaultValue;
}
}
/**
* Retrieves the value of an input and converts it to a float.
*
* @param name the name of the input
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the converted input value; or
* <p><code>0.0f</code> if no input value is present or if the input value
* is not a valid float
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public float getInputFloat(String name)
throws EngineException
{
return getInputFloat(name, ElementInfo.DEFAULT_FLOAT);
}
/**
* Retrieves the value of an input and converts it to a float, using a
* default value if no input value is present.
*
* @param name the name of the input
* @param defaultValue the default value that will be used when no input
* value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no input
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the converted input value; or
* <p>the default value if no input value is present
* @see #hasInputValue(String)
* @see #isInputEmpty(String)
* @see #getNamedInputBean(String)
* @see #getInputBean(Class)
* @see #getInputBean(Class, String)
* @see #getInput(String)
* @see #getInput(String, String)
* @see #getInputValues(String)
* @since 1.0
*/
public float getInputFloat(String name, float defaultValue)
throws EngineException
{
String value = getInput(name);
if (value == null)
{
return defaultValue;
}
try
{
return Float.parseFloat(value);
}
catch (NumberFormatException e)
{
return defaultValue;
}
}
/**
* Sets a select box option, a radio button or a checkbox to selected or
* checked according to input values.
* <p>The actual logic is performed by the {@link
* #selectParameter(Template, String, String[])} method. This method only
* prefixes the parameter name with the <code>INPUT:</code> literal, which
* is the syntax that is used to be able to handle automatic population
* correctly for each value type (inputs or submission parameters).
* <p>This method is automatically called during the {@link
* #print(Template)} for all the inputs and values that this element
* received. You should thus only call it explicitly if you need it to be
* executed with custom values.
*
* @param template the template instance where the selection should happen
* @param name the name of the input
* @param values the values that should selected or checked
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return a list with the identifiers of the template values that have
* been set, this is never <code>null</code>, when no values are set an
* empty list is returned
* @see #selectParameter(Template, String, String[])
* @see #selectSubmissionParameter(Template, String, String[])
* @since 1.0
*/
public Collection<String> selectInputParameter(Template template, String name, String[] values)
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.selectInputParameter(template, name, values);
}
/**
* Sets the value of an output.
*
* @param name the name of the output
* @param value the value that has to be set
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void setOutput(String name, String value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null == value) throw new IllegalArgumentException("value can't be null.");
mElementContext.setOutput(name, value);
}
/**
* Set the values of an output.
*
* @param name the name of the output
* @param values the values that have to be set
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void setOutput(String name, String[] values)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null == values) throw new IllegalArgumentException("values can't be null.");
if (0 == values.length) throw new IllegalArgumentException("values can't be empty.");
mElementContext.setOutput(name, values);
}
/**
* Sets the value of an output from a <code>boolean</code>.
*
* @param name the name of the output
* @param value the value that has to be set
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void setOutput(String name, boolean value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.setOutput(name, String.valueOf(value));
}
/**
* Sets the value of an output from a <code>char</code>.
*
* @param name the name of the output
* @param value the value that has to be set
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void setOutput(String name, char value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.setOutput(name, String.valueOf(value));
}
/**
* Set the value of an output from an array of <code>char</code>s that
* will be concatenated to a <code>String</code>.
*
* @param name the name of the output
* @param value the value that has to be set
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void setOutput(String name, char[] value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.setOutput(name, String.valueOf(value));
}
/**
* Sets the value of an output from a <code>double</code>.
*
* @param name the name of the output
* @param value the value that has to be set
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void setOutput(String name, double value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.setOutput(name, String.valueOf(value));
}
/**
* Sets the value of an output from a <code>float</code>.
*
* @param name the name of the output
* @param value the value that has to be set
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void setOutput(String name, float value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.setOutput(name, String.valueOf(value));
}
/**
* Sets the value of an output from an <code>int</code>.
*
* @param name the name of the output
* @param value the value that has to be set
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void setOutput(String name, int value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.setOutput(name, String.valueOf(value));
}
/**
* Sets the value of an output from a <code>long</code>.
*
* @param name the name of the output
* @param value the value that has to be set
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void setOutput(String name, long value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.setOutput(name, String.valueOf(value));
}
/**
* Sets the value of an output from a generic <code>object</code>. The object
* will be converted to its <code>String</code> representation.
*
* @param name the name of the output
* @param value the value that has to be set
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void setOutput(String name, Object value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.setOutput(name, value, null);
}
/**
* Adds a value to the current values of an output.
*
* @param name the name of the output
* @param value the value that has to be added
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void addOutputValue(String name, String value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null == value) throw new IllegalArgumentException("value can't be null.");
mElementContext.addOutputValue(name, value);
}
/**
* Adds values to the current values of an output.
*
* @param name the name of the output
* @param values the values that have to be added
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void addOutputValues(String name, String[] values)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null == values) throw new IllegalArgumentException("values can't be null.");
if (0 == values.length) throw new IllegalArgumentException("values can't be empty.");
mElementContext.addOutputValues(name, values);
}
/**
* Adds a <code>boolean</code> value to the current values of an output.
*
* @param name the name of the output
* @param value the value that has to be added
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void addOutputValue(String name, boolean value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.addOutputValue(name, String.valueOf(value));
}
/**
* Adds a <code>char</code> value to the current values of an output.
*
* @param name the name of the output
* @param value the value that has to be added
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void addOutputValue(String name, char value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.addOutputValue(name, String.valueOf(value));
}
/**
* Adds values from an array of <code>char</code>s to the current values
* of an output.
*
* @param name the name of the output
* @param value the values that have to be added
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void addOutputValue(String name, char[] value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.addOutputValue(name, String.valueOf(value));
}
/**
* Adds a <code>double</code> value to the current values of an output.
*
* @param name the name of the output
* @param value the value that has to be added
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void addOutputValue(String name, double value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.addOutputValue(name, String.valueOf(value));
}
/**
* Adds a <code>float</code> value to the current values of an output.
*
* @param name the name of the output
* @param value the value that has to be added
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void addOutputValue(String name, float value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.addOutputValue(name, String.valueOf(value));
}
/**
* Adds a <code>int</code> value to the current values of an output.
*
* @param name the name of the output
* @param value the value that has to be added
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void addOutputValue(String name, int value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.addOutputValue(name, String.valueOf(value));
}
/**
* Adds a <code>long</code> value to the current values of an output.
*
* @param name the name of the output
* @param value the value that has to be added
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void addOutputValue(String name, long value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.addOutputValue(name, String.valueOf(value));
}
/**
* Adds a generic <code>object</code> value to the current values of an
* output.
*
* @param name the name of the output
* @param value the value that has to be added
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void addOutputValue(String name, Object value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.addOutputValue(name, value);
}
/**
* Sets an instance of a named output bean and populates the output values
* from the property values. The class of the bean is looked up through
* its name, as is the property prefix.
* <p>This bean is not serialized or deserialized, each output corresponds
* to a property and is individually sent to the client.
*
* @param name the name of the output bean
* @param bean the bean instance that should be used to set the outputs
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* bean is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void setNamedOutputBean(String name, Object bean)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null == bean) throw new IllegalArgumentException("bean can't be null.");
mElementContext.setNamedOutputBean(name, bean);
}
/**
* Sets an instance of a named input bean and populates the output values
* from the property values.
* <p>This bean is not serialized or deserialized, each output corresponds
* to a property and is individually sent to the client.
*
* @param bean the bean instance that should be used to set the outputs
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void setOutputBean(Object bean)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == bean) throw new IllegalArgumentException("bean can't be null.");
mElementContext.setOutputBean(bean, null);
}
/**
* Sets an instance of a named input bean and populates the output values
* from the property values.
* <p>This bean is not serialized or deserialized, each output corresponds
* to a property and is individually sent to the client.
*
* @param bean the bean instance that should be used to set the outputs
* @param prefix the prefix that will be put in front of each property
* name
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void setOutputBean(Object bean, String prefix)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == bean) throw new IllegalArgumentException("bean can't be null.");
mElementContext.setOutputBean(bean, prefix);
}
/**
* Clears the output value of an output.
*
* @param name the name of the output
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if no output is known with this name; or if
* you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void clearOutput(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.clearOutput(name);
}
/**
* Clears the outputs that correspond to the properties of a named output
* bean. The class of the bean is looked up through its name, as is the
* property prefix.
*
* @param name the name of the output bean
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* bean is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void clearNamedOutputBean(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.clearNamedOutputBean(name);
}
/**
* Clears the outputs that correspond to the properties of an output bean.
*
* @param beanClass the class of the output bean
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* bean is known with this name; if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class, String)
* @see #getOutput(String)
* @since 1.0
*/
public void clearOutputBean(Class beanClass)
throws EngineException
{
clearOutputBean(beanClass, null);
}
/**
* Clears the outputs that correspond to the properties of an output bean,
* taking the provided prefix into account.
*
* @param beanClass the class of the output bean
* @param prefix the prefix that will be put in front of each property
* name
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #getOutput(String)
* @since 1.0
*/
public void clearOutputBean(Class beanClass, String prefix)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == beanClass) throw new IllegalArgumentException("beanClass can't be null.");
mElementContext.clearOutputBean(beanClass, prefix);
}
/**
* Retrieves the value of the ouput.
*
* @param name the name of the output
* @return the textual value of the output as it's used by framework; or
* {@code null} if the output couldn't be found.
* @exception com.uwyn.rife.engine.exceptions.EngineException if no output
* is known with this name; if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @see #setNamedOutputBean(String, Object)
* @see #setOutputBean(Object)
* @see #setOutputBean(Object, String)
* @see #setOutput(String, String)
* @see #setOutput(String, String[])
* @see #addOutputValue(String, String)
* @see #addOutputValues(String, String[])
* @see #clearOutput(String)
* @see #clearNamedOutputBean(String)
* @see #clearOutputBean(Class)
* @see #clearOutputBean(Class, String)
* @since 1.6
*/
public String[] getOutput(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.getOutput(name);
}
/**
* Checks whether a cookie is present.
*
* @param name the name of the cookie
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* incookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return <code>true</code> if the cookie was present; or
* <p><code>false</code> otherwise
* @see #getCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public boolean hasCookie(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.hasCookie(name);
}
/**
* Retrieves a cookie.
*
* @param name the name of the cookie.
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* incookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the instance of the cookie; or
* <p><code>null</code> if no such cookie is present
* @see #hasCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public Cookie getCookie(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.getCookie(name);
}
/**
* Retrieves the value of a cookie.
*
* @param name the name of the cookie
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* incookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the value of the cookie; or
* <p><code>null</code> if no such cookie is present
* @see #hasCookie(String)
* @see #getCookie(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public String getCookieValue(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.getCookieValue(name);
}
/**
* Retrieves all current cookies names with their values.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return a new map of all the current cookies names with their values
* @see #hasCookie(String)
* @see #getCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #setCookie(Cookie)
* @since 1.0
*/
public Map<String, String> getCookieValues()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getCookieValues();
}
/**
* Retrieves the value of a named cookie, using a default value as
* fallback.
*
* @param name the name of the cookie
* @param defaultValue the default value that will be used when no cookie
* value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* incookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the cookie value; or
* <p>the default value if no cookie value is present
* @see #hasCookie(String)
* @see #getCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public String getCookieValue(String name, String defaultValue)
throws EngineException
{
String value = getCookieValue(name);
if (value == null)
{
return defaultValue;
}
return value;
}
/**
* Retrieves the value of a named cookie and converts it to a boolean.
*
* @param name the name of the cookie
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* incookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted cookie value; or
* <p><code>false</code> if no cookie value is present or if the cookie
* value is not a valid boolean
* @see #hasCookie(String)
* @see #getCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public boolean getCookieValueBoolean(String name)
throws EngineException
{
return getCookieValueBoolean(name, ElementInfo.DEFAULT_BOOLEAN);
}
/**
* Retrieves the value of a named cookie and converts it to a boolean,
* using a default value if no input value is present.
*
* @param name the name of the cookie
* @param defaultValue the default value that will be used when no cookie
* value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* incookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted cookie value; or
* <p>the default value if no cookie value is present
* @see #hasCookie(String)
* @see #getCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public boolean getCookieValueBoolean(String name, boolean defaultValue)
throws EngineException
{
String value = getCookieValue(name);
if (value == null)
{
return defaultValue;
}
return StringUtils.convertToBoolean(value);
}
/**
* Retrieves the value of a named cookie and converts it to an integer.
*
* @param name the name of the cookie
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* incookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted cookie value; or
* <p><code>0</code> if no cookie value is present or if the cookie value
* is not a valid integer
* @see #hasCookie(String)
* @see #getCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public int getCookieValueInt(String name)
throws EngineException
{
return getCookieValueInt(name, ElementInfo.DEFAULT_INTEGER);
}
/**
* Retrieves the value of a named cookie and converts it to an integer,
* using a default value if no input value is present.
*
* @param name the name of the cookie
* @param defaultValue the default value that will be used when no cookie
* value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* incookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted cookie value; or
* <p>the default value if no cookie value is present
* @see #hasCookie(String)
* @see #getCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public int getCookieValueInt(String name, int defaultValue)
throws EngineException
{
String value = getCookieValue(name);
if (value == null)
{
return defaultValue;
}
try
{
return Integer.parseInt(value);
}
catch (NumberFormatException e)
{
return defaultValue;
}
}
/**
* Retrieves the value of a named cookie and converts it to a long.
*
* @param name the name of the cookie
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* incookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted cookie value; or
* <p><code>0L</code> if no cookie value is present or if the cookie value
* is not a valid long
* @see #hasCookie(String)
* @see #getCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public long getCookieValueLong(String name)
throws EngineException
{
return getCookieValueLong(name, ElementInfo.DEFAULT_LONG);
}
/**
* Retrieves the value of a named cookie and converts it to a long, using
* a default value if no input value is present.
*
* @param name the name of the cookie
* @param defaultValue the default value that will be used when no cookie
* value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* incookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted cookie value; or
* <p>the default value if no cookie value is present
* @see #hasCookie(String)
* @see #getCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public long getCookieValueLong(String name, long defaultValue)
throws EngineException
{
String value = getCookieValue(name);
if (value == null)
{
return defaultValue;
}
try
{
return Long.parseLong(value);
}
catch (NumberFormatException e)
{
return defaultValue;
}
}
/**
* Retrieves the value of a named cookie and converts it to a double.
*
* @param name the name of the cookie
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* incookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted cookie value; or
* <p><code>0.0d</code> if no cookie value is present or if the cookie
* value is not a valid double
* @see #hasCookie(String)
* @see #getCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public double getCookieValueDouble(String name)
throws EngineException
{
return getCookieValueDouble(name, ElementInfo.DEFAULT_DOUBLE);
}
/**
* Retrieves the value of a named cookie and converts it to a double,
* using a default value if no input value is present.
*
* @param name the name of the cookie
* @param defaultValue the default value that will be used when no cookie
* value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* incookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted cookie value; or
* <p>the default value if no cookie value is present
* @see #hasCookie(String)
* @see #getCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public double getCookieValueDouble(String name, double defaultValue)
throws EngineException
{
String value = getCookieValue(name);
if (value == null)
{
return defaultValue;
}
try
{
return Double.parseDouble(value);
}
catch (NumberFormatException e)
{
return defaultValue;
}
}
/**
* Retrieves the value of a named cookie and converts it to a float.
*
* @param name the name of the cookie
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* incookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted cookie value; or
* <p><code>0.0</code>f if no cookie value is present or if the cookie
* value is not a valid float
* @see #hasCookie(String)
* @see #getCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public float getCookieValueFloat(String name)
throws EngineException
{
return getCookieValueFloat(name, ElementInfo.DEFAULT_FLOAT);
}
/**
* Retrieves the value of a named cookie and converts it to a float, using
* a default value if no input value is present.
*
* @param name the name of the cookie
* @param defaultValue the default value that will be used when no cookie
* value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* incookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted cookie value; or
* <p>the default value if no cookie value is present
* @see #hasCookie(String)
* @see #getCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public float getCookieValueFloat(String name, float defaultValue)
throws EngineException
{
String value = getCookieValue(name);
if (value == null)
{
return defaultValue;
}
try
{
return Float.parseFloat(value);
}
catch (NumberFormatException e)
{
return defaultValue;
}
}
/**
* Sets a cookie which will be sent to the browser.
* <p>Cookies are handles outside of the web engine's data flow
* management. They are preserved by the browser and are automatically
* provided at each request.
*
* @param cookie the cookie instance that will be set
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* outcookie is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #hasCookie(String)
* @see #getCookie(String)
* @see #getCookieValue(String)
* @see #getCookieValue(String, String)
* @see #getCookieValues()
* @see #setCookie(Cookie)
* @since 1.0
*/
public void setCookie(Cookie cookie)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == cookie) throw new IllegalArgumentException("cookie can't be null.");
if (null == cookie.getName()) throw new IllegalArgumentException("cookie name can't be empty.");
mElementContext.setCookie(cookie);
}
/**
* Returns the unique identifier of the current continuation.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger)
* @return the unique identifier of the current continuations; or
* <p><code>null</code> if no continuation is active
* @since 1.0
*/
public String getContinuationId()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
return ContinuationContext.getActiveContextId();
}
/**
* Generates a query URL for an exit.
*
* @param name the name of the exit
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the generated URL as a character sequence
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public CharSequence getExitQueryUrl(String name)
throws EngineException
{
return getExitQueryUrl(name, null, null);
}
/**
* Generates a query URL for an exit and appends a pathinfo to the URL of
* the destination element.
*
* @param name the name of the exit
* @param pathinfo the pathinfo that will be appended; or
* <code>null</code> if no pathinfo should be appended
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the generated URL as a character sequence
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public CharSequence getExitQueryUrl(String name, String pathinfo)
throws EngineException
{
return getExitQueryUrl(name, pathinfo, null);
}
/**
* Generates a query URL for an exit and overrides the current output
* values only for this method.
*
* @param name the name of the exit
* @param outputValues an array of string pairs that will be used to
* override the current output values; or <code>null</code> if no output
* values should be overridden
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the generated URL as a character sequence
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public CharSequence getExitQueryUrl(String name, String[] outputValues)
throws EngineException
{
return getExitQueryUrl(name, null, outputValues);
}
/**
* Generates a query URL for an exit and appends a pathinfo to the URL of
* the destination element. The current output values can be overridden
* for this method alone.
* <p>This will take the current element context into account with the
* available outputs, global variables, ... and generate an URL that
* persists the data state according to the declared site structure.
* <p>The output values are provided as an array of strings that should be
* structured in pairs. For example, if these output values should be
* used: <code>output1</code>:<code>value1</code> and <code>output2</code>:<code>value2</code>,
* you should define the following string array:
* <pre>new String[] {"output1", "value1", "output2", "value2"}</pre>
* <p>The generated URL with not contain a scheme, host or port. It will
* begin with the path part and be absolute, starting with the web
* application's root URL.
*
* @param name the name of the exit
* @param pathinfo the pathinfo that will be appended; or
* <code>null</code> if no pathinfo should be appended
* @param outputValues an array of string pairs that will be used to
* override the current output values; or <code>null</code> if no output
* values should be overridden
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the generated URL as a character sequence
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public CharSequence getExitQueryUrl(String name, String pathinfo, String[] outputValues)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null != outputValues &&
outputValues.length % 2 > 0) throw new IllegalArgumentException("outputValues should be a series of key/value pairs.");
return mElementContext.getExitQueryUrl(name, pathinfo, outputValues);
}
/**
* Generates a form action URL for an exit.
*
* @param name the name of the exit
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the generated URL as a character sequence
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public CharSequence getExitFormUrl(String name)
throws EngineException
{
return getExitFormUrl(name, null);
}
/**
* Generates a form action URL for an exit and appends a pathinfo to the
* URL of the destination element.
* <p>This will take the current element context into account with the
* available outputs, global variables, ... and generate an URL that
* persists the data state according to the declared site structure.
* <p>The generated URL with not contain a scheme, host or port. It will
* begin with the path part and be absolute, starting with the web
* application's root URL.
* <p>This method goes together with the {@link
* #getExitFormParameters(String, String[])} method since the state is
* tranferred as hidden form parameters that are part of the form.
*
* @param name the name of the exit
* @param pathinfo the pathinfo that will be appended; or
* <code>null</code> if no pathinfo should be appended
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the generated URL as a character sequence
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public CharSequence getExitFormUrl(String name, String pathinfo)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.getExitFormUrl(name, pathinfo);
}
/**
* Generates the XHTML hidden form parameters for an exit.
*
* @param name the name of the exit
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the generated parameters as a character sequence
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public CharSequence getExitFormParameters(String name)
throws EngineException
{
return getExitFormParameters(name, null);
}
/**
* Generates the hidden XHTML form parameters for an exit and overrides
* the current output values only for this method.
* <p>This will take the current element context into account with the
* available outputs, global variables, ... and generate hidden XHTML form
* parameters that persist the data state according to the declared site
* structure.
* <p>The output values are provided as an array of strings that should be
* structured in pairs. For example, if these output values should be
* used: <code>output1</code>:<code>value1</code> and <code>output2</code>:<code>value2</code>,
* you should define the following string array:
* <pre>new String[] {"output1", "value1", "output2", "value2"}</pre>
* <p>This method goes together with the {@link
* #getExitFormUrl(String, String)} method since the URL needs to be
* provided in the action attribute of the form.
*
* @param name the name of the exit
* @param outputValues an array of string pairs that will be used to
* override the current output values; or <code>null</code> if no output
* values should be overridden
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the generated parameters as a character sequence
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParametersJavascript(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public CharSequence getExitFormParameters(String name, String[] outputValues)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null != outputValues &&
outputValues.length % 2 > 0) throw new IllegalArgumentException("outputValues should be a series of key/value pairs.");
return mElementContext.getExitFormParameters(name, outputValues);
}
/**
* Generates Javascript that will generate hidden XHTML form parameters for
* an exit and overrides the current output values only for this method.
* <p>This will take the current element context into account with the
* available outputs, global variables, ... and generate hidden XHTML form
* parameters that persist the data state according to the declared site
* structure.
* <p>The output values are provided as an array of strings that should be
* structured in pairs. For example, if these output values should be
* used: <code>output1</code>:<code>value1</code> and <code>output2</code>:<code>value2</code>,
* you should define the following string array:
* <pre>new String[] {"output1", "value1", "output2", "value2"}</pre>
* <p>This method goes together with the {@link
* #getExitFormUrl(String, String)} method since the URL needs to be
* provided in the action attribute of the form.
*
* @param name the name of the exit
* @param outputValues an array of string pairs that will be used to
* override the current output values; or <code>null</code> if no output
* values should be overridden
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the generated parameters as a character sequence
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.6
*/
public CharSequence getExitFormParametersJavascript(String name, String[] outputValues)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null != outputValues &&
outputValues.length % 2 > 0) throw new IllegalArgumentException("outputValues should be a series of key/value pairs.");
return mElementContext.getExitFormParametersJavascript(name, outputValues);
}
/**
* Generates a query URL for an exit and sets it as the content of a
* template value.
*
* @param template the template that will be used to set the value
* @param name the name of the exit
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifier
* <code>EXIT:QUERY:exitname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public void setExitQuery(Template template, String name)
throws TemplateException, EngineException
{
setExitQuery(template, name, null, null);
}
/**
* Generates a query URL with a pathinfo for an exit and sets it as the
* content of a template value.
*
* @param template the template that will be used to set the value
* @param name the name of the exit
* @param pathinfo the pathinfo that will be appended; or
* <code>null</code> if no pathinfo should be appended
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifier
* <code>EXIT:QUERY:exitname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public void setExitQuery(Template template, String name, String pathinfo)
throws TemplateException, EngineException
{
setExitQuery(template, name, pathinfo, null);
}
/**
* Generates a query URL for an exit with overridden outputs and sets it
* as the content of a template value.
*
* @param template the template that will be used to set the value
* @param name the name of the exit
* @param outputValues an array of string pairs that will be used to
* override the current output values; or <code>null</code> if no output
* values should be overridden
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifier
* <code>EXIT:QUERY:exitname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public void setExitQuery(Template template, String name, String[] outputValues)
throws TemplateException, EngineException
{
setExitQuery(template, name, null, outputValues);
}
/**
* Generates a query URL for an exit with a pathinfo and overridden
* outputs and sets it as the content of a template value.
* <p>The URL will be generated by calling the {@link
* #getExitQueryUrl(String, String, String[])} method and it will be set
* to the value identifier with the syntax
* <code>EXIT:QUERY:exitname</code>.
* <p>Template content that is outputted with the
* <code>#print(Template)</code> method will automatically be scanned for
* value identifiers with this syntax and the exit query URLs will
* generated. You should only use this method if you need a query URL to
* be generated in a certain context.
*
* @param template the template that will be used to set the value
* @param name the name of the exit
* @param pathinfo the pathinfo that will be appended; or
* <code>null</code> if no pathinfo should be appended
* @param outputValues an array of string pairs that will be used to
* override the current output values; or <code>null</code> if no output
* values should be overridden
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifier
* <code>EXIT:QUERY:exitname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public void setExitQuery(Template template, String name, String pathinfo, String[] outputValues)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null != outputValues &&
outputValues.length % 2 > 0) throw new IllegalArgumentException("outputValues should be a series of key/value pairs.");
mElementContext.setExitQuery(template, name, pathinfo, outputValues);
}
/**
* Generates a form action URL for an exit and sets it as the content of a
* template value.
*
* @param template the template that will be used to set the value
* @param name the name of the exit
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifiers
* <code>EXIT:FORM:exitname</code> and <code>EXIT:PARAMS:exitname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public void setExitForm(Template template, String name)
throws TemplateException, EngineException
{
setExitForm(template, name, null, null);
}
/**
* Generates a form action URL for an exit with a pathinfo and sets it as
* the content of a template value.
*
* @param template the template that will be used to set the value
* @param name the name of the exit
* @param pathinfo the pathinfo that will be appended; or
* <code>null</code> if no pathinfo should be appended
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifiers
* <code>EXIT:FORM:exitname</code> and <code>EXIT:PARAMS:exitname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public void setExitForm(Template template, String name, String pathinfo)
throws TemplateException, EngineException
{
setExitForm(template, name, pathinfo, null);
}
/**
* Generates a form action URL for an exit with overridden outputs and
* sets it as the content of a template value.
*
* @param template the template that will be used to set the value
* @param name the name of the exit
* @param outputValues an array of string pairs that will be used to
* override the current output values; or <code>null</code> if no output
* values should be overridden
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifiers
* <code>EXIT:FORM:exitname</code> and <code>EXIT:PARAMS:exitname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @see #setExitForm(Template, String, String)
* @since 1.0
*/
public void setExitForm(Template template, String name, String[] outputValues)
throws TemplateException, EngineException
{
setExitForm(template, name, null, outputValues);
}
/**
* Generates a form action URL for an exit with a pathinfo and overridden
* outputs and sets it as the content of a template value.
* <p>The URL will be generated by calling the {@link
* #getExitFormUrl(String, String)} and {@link
* #getExitFormParameters(String, String[])} methods and it will be set
* the results to the value identifiers with the syntax
* <code>EXIT:FORM:exitname</code> and <code>EXIT:PARAMS:exitname</code>.
* <p>Template content that is outputted with the
* <code>#print(Template)</code> method will automatically be scanned for
* value identifiers with this syntax and the exit forms URLs and
* parameters will generated. You should only use this method if you need
* these to be generated in a certain context.
*
* @param template the template that will be used to set the value
* @param name the name of the exit
* @param pathinfo the pathinfo that will be appended; or
* <code>null</code> if no pathinfo should be appended
* @param outputValues an array of string pairs that will be used to
* override the current output values; or <code>null</code> if no output
* values should be overridden
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifiers
* <code>EXIT:FORM:exitname</code> and <code>EXIT:PARAMS:exitname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #getExitQueryUrl(String, String, String[])
* @see #getExitFormUrl(String, String)
* @see #getExitFormParameters(String, String[])
* @see #setExitQuery(Template, String, String, String[])
* @since 1.0
*/
public void setExitForm(Template template, String name, String pathinfo, String[] outputValues)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null != outputValues &&
outputValues.length % 2 > 0) throw new IllegalArgumentException("outputValues should be a series of key/value pairs.");
mElementContext.setExitForm(template, name, pathinfo, outputValues);
}
/**
* Sets a select box option, a radio button or a checkbox to selected or
* checked.
* <p>This method will check the template for certain value tags and set
* them to the correct attributes according to the name and the provided
* values in this method. This is dependent on the template type and
* currently only makes sense for <code>enginehtml</code>,
* <code>enginexhtml</code>, <code>html</code> and <code>xhtml</code>
* templates.
* <p>For example for select boxes, consider the name '<code>colors</code>',
* the values '<code>blue</code>' and '<code>red</code>', and the
* following XHTML template excerpt:
* <pre><select name="colors">
*<option value="blue"[!V 'colors:blue:SELECTED'][!/V]>Blue</option>
*<option value="orange"[!V 'colors:orange:SELECTED'][!/V]>Orange</option>
*<option value="red"[!V 'colors:red:SELECTED'][!/V]>Red</option>
*<option value="green"[!V colors:green:SELECTED''][!/V]>Green</option>
*</select></pre>
* <p>the result will then be:
* <pre><select name="colors">
*<option value="blue" selected="selected">Blue</option>
*<option value="orange">Orange</option>
*<option value="red" selected="selected">Red</option>
*<option value="green">Green</option>
*</select></pre>
* <p>For example for radio buttons, consider the name '<code>sex</code>',
* the value '<code>male</code>' and the following XHTML template excerpt:
* <pre><input type="radio" name="sex" value="male"[!V 'sex:male:CHECKED'][!/V] />
*<input type="radio" name="sex" value="female"[!V 'sex:female:CHECKED'][!/V] /></pre>
* <p>the result will then be:
* <pre><input type="radio" name="sex" value="male" checked="checked" />
*<input type="radio" name="sex" value="female" /></pre>
* <p>For example for checkboxes, consider the name '<code>active</code>',
* the value '<code>true</code>' and the following XHTML template excerpt:
* <pre><input type="checkbox" name="active"[!V 'active:CHECKED'][!/V] />
*<input type="checkbox" name="senditnow"[!V 'senditnow:CHECKED'][!/V] /></pre>
* <p>the result will then be:
* <pre><input type="checkbox" name="active" checked="checked" />
*<input type="checkbox" name="senditnow" /></pre>
*
* @param template the template instance where the selection should happen
* @param name the name of the parameter
* @param values the values that should selected or checked
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return a list with the identifiers of the template values that have
* been set, this is never <code>null</code>, when no values are set an
* empty list is returned
* @see #selectInputParameter(Template, String, String[])
* @see #selectSubmissionParameter(Template, String, String[])
* @since 1.0
*/
public Collection<String> selectParameter(Template template, String name, String[] values)
{
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.selectParameter(template, name, values);
}
/**
* Generates a form that corresponds to a bean instance.
*
* @param template the template instance where the generation should
* happen
* @param beanInstance the instance of the bean that should be used to
* generate the form
* @exception com.uwyn.rife.engine.exceptions.EngineException if errors
* occurred during the introspection of the bean instance; or if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see com.uwyn.rife.site.FormBuilder
* @see #generateForm(Template, Object, String)
* @see #generateEmptyForm(Template, Class, String)
* @see #removeForm(Template, Class)
* @since 1.0
*/
public void generateForm(Template template, Object beanInstance)
throws EngineException
{
generateForm(template, beanInstance, null);
}
/**
* Generates a form that corresponds to a bean instance.
* <p>This method delegates all logic to the {@link
* com.uwyn.rife.site.FormBuilder#generateForm(Template, Object, Map, String)}
* method of the provided template instance.
*
* @param template the template instance where the generation should
* happen
* @param beanInstance the instance of the bean that should be used to
* generate the form
* @param prefix the prefix that will be prepended to all bean property
* names
* @exception com.uwyn.rife.engine.exceptions.EngineException if errors
* occurred during the introspection of the bean instance; or if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see com.uwyn.rife.site.FormBuilder
* @see #generateEmptyForm(Template, Class, String)
* @see #removeForm(Template, Class)
* @since 1.0
*/
public void generateForm(Template template, Object beanInstance, String prefix)
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == beanInstance) throw new IllegalArgumentException("beanInstance can't be null.");
mElementContext.generateForm(template, beanInstance, prefix);
}
/**
* Generates a form that corresponds to an empty instance of a bean class.
*
* @param template the template instance where the generation should
* happen
* @param beanClass the class of the bean that should be used to generate
* the form
* @exception com.uwyn.rife.engine.exceptions.EngineException if errors
* occurred during the introspection of the bean; or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @see com.uwyn.rife.site.FormBuilder
* @see #generateForm(Template, Object, String)
* @see #generateEmptyForm(Template, Class, String)
* @see #removeForm(Template, Class)
* @since 1.0
*/
public void generateEmptyForm(Template template, Class beanClass)
throws EngineException
{
generateEmptyForm(template, beanClass, null);
}
/**
* Generates a form that corresponds to an empty instance of a bean class.
* <p>An '<em>empty</em>' instance is an object that has been created by
* calling the default constructor of the bean class, without making any
* additional changes to it afterwards.
* <p>This method delegates all logic to the {@link
* com.uwyn.rife.site.FormBuilder#generateForm(Template, Class, Map, String)}
* method of the provided template instance.
*
* @param template the template instance where the generation should
* happen
* @param beanClass the class of the bean that should be used to generate
* the form
* @param prefix the prefix that will be prepended to all bean property
* names
* @exception com.uwyn.rife.engine.exceptions.EngineException if errors
* occurred during the introspection of the bean; or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @see com.uwyn.rife.site.FormBuilder
* @see #generateForm(Template, Object, String)
* @see #removeForm(Template, Class)
* @since 1.0
*/
public void generateEmptyForm(Template template, Class beanClass, String prefix)
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == beanClass) throw new IllegalArgumentException("beanClass can't be null.");
mElementContext.generateEmptyForm(template, beanClass, prefix);
}
/**
* Removes a generated form, leaving the builder value tags empty again as
* if this form never had been generated.
*
* @param template the template instance where the form should be removed
* from
* @param beanClass the class of the bean that should be used to remove
* the form
* @exception com.uwyn.rife.engine.exceptions.EngineException if errors
* occurred during the introspection of the bean; or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @see com.uwyn.rife.site.FormBuilder
* @see #generateForm(Template, Object, String)
* @see #generateEmptyForm(Template, Class, String)
* @see #removeForm(Template, Class)
* @since 1.0
*/
public void removeForm(Template template, Class beanClass)
throws EngineException
{
removeForm(template, beanClass, null);
}
/**
* Removes a generated form, leaving the builder value tags empty again as
* if this form never had been generated.
* <p>This method delegates all logic to the {@link
* com.uwyn.rife.site.FormBuilder#removeForm(Template, Class, String)}
* method of the provided template instance.
*
* @param template the template instance where the form should be removed
* from
* @param beanClass the class of the bean that should be used to remove
* the form
* @param prefix the prefix that will be prepended to all bean property
* names
* @exception com.uwyn.rife.engine.exceptions.EngineException if errors
* occurred during the introspection of the bean; or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @see com.uwyn.rife.site.FormBuilder
* @see #generateForm(Template, Object, String)
* @see #generateEmptyForm(Template, Class, String)
* @since 1.0
*/
public void removeForm(Template template, Class beanClass, String prefix)
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == beanClass) throw new IllegalArgumentException("beanClass can't be null.");
mElementContext.removeForm(template, beanClass, prefix);
}
/**
* Sets a select box option, a radio button or a checkbox to selected or
* checked according to submission parameter values.
* <p>The actual logic is performed by the {@link
* #selectParameter(Template, String, String[])} method. This method only
* prefixes the parameter name with the <code>PARAM:</code> literal, which
* is the syntax that is used to be able to handle automatic population
* correctly for each value type (inputs or submission parameters).
* <p>This method is automatically called during the {@link
* #print(Template)} for all the inputs and values that this element
* received. You should thus only call it explicitly if you need it to be
* executed with custom values.
*
* @param template the template instance where the selection should happen
* @param name the name of the parameter
* @param values the values that should selected or checked
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return a list with the identifiers of the template values that have
* been set, this is never <code>null</code>, when no values are set an
* empty list is returned
* @see #selectParameter(Template, String, String[])
* @see #selectInputParameter(Template, String, String[])
* @since 1.0
*/
public Collection<String> selectSubmissionParameter(Template template, String name, String[] values)
{
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.selectSubmissionParameter(template, name, values);
}
/**
* Sets a select box option, a radio button or a checkbox to selected or
* checked according to a submission parameter value.
* <p>This is simply a convenience method that calls <code>#selectSubmissionParameter(Template,
* String, String[])</code> with a single value string array.
*
* @param template the template instance where the selection should happen
* @param name the name of the parameter
* @param value the value that should selected or checked
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return a list with the identifiers of the template values that have
* been set, this is never <code>null</code>, when no values are set an
* empty list is returned
* @see #selectParameter(Template, String, String[])
* @see #selectInputParameter(Template, String, String[])
* @see #selectSubmissionParameter(Template, String, String[])
* @since 1.0
*/
public Collection selectSubmissionParameter(Template template, String name, String value)
{
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.selectSubmissionParameter(template, name, new String[] {value});
}
/**
* Sets the content of all values that correspond to bean property names
* to the data of the bean properties.
* <p>The data will be converted to strings and the template's encoder
* will be used to encode the string representations (for example, for
* HTML non-ascii characters will be replaced with HTML entities).
* <p>The identifiers of the values that will be filled in should have the
* following syntax:
* <pre>PARAM:propertyName</pre>
*
* @param template the template instance that contains the values that
* will be filled in
* @param beanInstance the bean instance whose property values will be set
* @exception com.uwyn.rife.template.exceptions.TemplateException when
* errors occurred during the introspection of the bean instance
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #setSubmissionBean(Template, Object, boolean)
* @since 1.0
*/
public void setSubmissionBean(Template template, Object beanInstance)
throws TemplateException, EngineException
{
setSubmissionBean(template, beanInstance, true);
}
/**
* Sets the content of all values that correspond to bean property names
* to the data of the bean properties.
* <p>The identifiers of the values that will be filled in should have the
* following syntax:
* <pre>PARAM:propertyName</pre>
*
* @param template the template instance that contains the values that
* will be filled in
* @param beanInstance the bean instance whose property values will be set
* @param encode <code>true</code> when the property values should be
* encoded according to the template type; or
* <p><code>false</code> otherwise
* @exception com.uwyn.rife.template.exceptions.TemplateException when
* errors occurred during the introspection of the bean instance
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @since 1.0
*/
public void setSubmissionBean(Template template, Object beanInstance, boolean encode)
throws TemplateException, EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == beanInstance) throw new IllegalArgumentException("beanInstance can't be null.");
mElementContext.setSubmissionBean(template, beanInstance, encode);
}
/**
* Retrieves an instance of a named submission bean for the current
* submission and populates the properties with the parameter values. The
* class of the bean is looked up through its name, as is the property
* prefix.
* <p>This bean is not serialized or deserialized, each property
* corresponds to a parameter and is individually sent by the client.
*
* @param beanName the name of the submission bean
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* submission bean is known with this name; or if an error occurred during
* the instantiation of the bean; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the populated submission bean instance; or
* <p><code>null</code> if no submission has been sent
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public <BeanType> BeanType getNamedSubmissionBean(String beanName)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == beanName) throw new IllegalArgumentException("beanName can't be null.");
if (0 == beanName.length()) throw new IllegalArgumentException("beanName can't be empty.");
String submission_name = mElementContext.getSubmission();
if (null == submission_name)
{
return null;
}
return (BeanType)mElementContext.getNamedSubmissionBean(submission_name, beanName);
}
/**
* Retrieves an instance of a named submission bean and populates the
* properties with the parameter values. The class of the bean is looked
* up through its name, as is the property prefix.
* <p>This bean is not serialized or deserialized, each property
* corresponds to a parameter and is individually sent by the client.
*
* @param submissionName the name of the submission bean
* @param beanName the name of the submission that contains the bean
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* submission bean is known with this name; or if no submission is know
* with the name; or if an error occurred during the instantiation or the
* population of the bean; or if you don't have access to the request data
* (eg. you're inside a child trigger); or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @return the populated submission bean instance; or
* <p><code>null</code> if the submission name doesn't correspond to the
* sent submission
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public <BeanType> BeanType getNamedSubmissionBean(String submissionName, String beanName)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == submissionName) throw new IllegalArgumentException("submissionName can't be null.");
if (0 == submissionName.length()) throw new IllegalArgumentException("submissionName can't be empty.");
if (null == beanName) throw new IllegalArgumentException("beanName can't be null.");
if (0 == beanName.length()) throw new IllegalArgumentException("beanName can't be empty.");
return (BeanType)mElementContext.getNamedSubmissionBean(submissionName, beanName);
}
/**
* Retrieves an instance of a submission bean and populates the properties
* with the parameter values.
* <p>This bean is not serialized or de-serialized, each property
* corresponds to a parameter and is individually sent by the client.
*
* @param beanClass the class of the submission bean
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurred during the instantiation or the population of the bean; or if
* you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the populated submission bean instance; or
* <p><code>null</code> if no submission has been sent
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public <BeanType> BeanType getSubmissionBean(Class<BeanType> beanClass)
throws EngineException
{
String submission_name = mElementContext.getSubmission();
if (null == submission_name)
{
return null;
}
return getSubmissionBean(submission_name, beanClass, null);
}
/**
* Retrieves an instance of a submission bean and populates the properties
* with the parameter values, taking the provided prefix into account.
* <p>This bean is not serialized or de-serialized, each property
* corresponds to a parameter and is individually sent by the client.
*
* @param beanClass the class of the submission bean
* @param prefix the prefix that will be put in front of each property
* name
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurred during the instantiation or the population of the bean; or if
* you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the populated submission bean instance; or
* <p><code>null</code> if no submission has been sent
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public <BeanType> BeanType getSubmissionBean(Class<BeanType> beanClass, String prefix)
throws EngineException
{
String submission_name = mElementContext.getSubmission();
if (null == submission_name)
{
return null;
}
return getSubmissionBean(submission_name, beanClass, prefix);
}
/**
* Retrieves an instance of a submission bean and populates the properties
* with the parameter values.
* <p>This bean is not serialized or de-serialized, each property
* corresponds to a parameter and is individually sent by the client.
*
* @param submissionName the name of the submission
* @param beanClass the class of the submission bean
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurred during the instantiation or the population of the bean; or if
* you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the populated submission bean instance; or
* <p><code>null</code> if the submission name doesn't correspond to the
* sent submission
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public <BeanType> BeanType getSubmissionBean(String submissionName, Class<BeanType> beanClass)
throws EngineException
{
return getSubmissionBean(submissionName, beanClass, null);
}
/**
* Retrieves an instance of a submission bean and populates the properties
* with the parameter values, taking the provided prefix into account.
* <p>This bean is not serialized or de-serialized, each property
* corresponds to a parameter and is individually sent by the client.
*
* @param submissionName the name of the submission
* @param beanClass the class of the submission bean
* @param prefix the prefix that will be put in front of each property
* name
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurred during the instantiation or the population of the bean; or if
* you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @return the populated submission bean instance; or
* <p><code>null</code> if the submission name doesn't correspond to the
* sent submission
* @see #getNamedSubmissionBean(String, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public <BeanType> BeanType getSubmissionBean(String submissionName, Class<BeanType> beanClass, String prefix)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == submissionName) throw new IllegalArgumentException("submissionName can't be null.");
if (0 == submissionName.length()) throw new IllegalArgumentException("submissionName can't be empty.");
if (null == beanClass) throw new IllegalArgumentException("beanClass can't be null.");
return mElementContext.getSubmissionBean(submissionName, beanClass, prefix);
}
/**
* Fills the properties of an existing bean with the parameter values of
* the submission that was sent.
*
* @param bean the submission bean instance that will be filled
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurred during the population of the bean; or if you don't have access
* to the request data (eg. you're inside a child trigger); or if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public void fillSubmissionBean(Object bean)
throws EngineException
{
String submission_name = mElementContext.getSubmission();
if (null == submission_name)
{
return;
}
fillSubmissionBean(submission_name, bean, null);
}
/**
* Fills the properties of an existing bean with the parameter values of a
* submission.
*
* @param submissionName the name of the submission
* @param bean the submission bean instance that will be filled
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurred during the population of the bean; or if you don't have access
* to the request data (eg. you're inside a child trigger); or if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public void fillSubmissionBean(String submissionName, Object bean)
throws EngineException
{
fillSubmissionBean(submissionName, bean, null);
}
/**
* Fills the properties of an existing bean with the parameter values of
* the submission that was sent, taking the provided prefix into account.
*
* @param bean the submission bean instance that will be filled
* @param prefix the prefix that will be put in front of each property
* name
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurred during the population of the bean; or if you don't have access
* to the request data (eg. you're inside a child trigger); or if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public void fillSubmissionBean(Object bean, String prefix)
throws EngineException
{
String submission_name = mElementContext.getSubmission();
if (null == submission_name)
{
return;
}
fillSubmissionBean(submission_name, bean, prefix);
}
/**
* Fills the properties of an existing bean with the parameter values of a
* submission, taking the provided prefix into account.
*
* @param submissionName the name of the submission
* @param bean the submission bean instance that will be filled
* @param prefix the prefix that will be put in front of each property
* name
* @exception com.uwyn.rife.engine.exceptions.EngineException if an error
* occurred during the population of the bean; or if you don't have access
* to the request data (eg. you're inside a child trigger); or if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public void fillSubmissionBean(String submissionName, Object bean, String prefix)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == submissionName) throw new IllegalArgumentException("submissionName can't be null.");
if (0 == submissionName.length()) throw new IllegalArgumentException("submissionName can't be empty.");
mElementContext.fillSubmissionBean(submissionName, bean, prefix);
}
/**
* Indicates whether this element received a submission.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return <code>true</code> if a submission was sent to this element; and
* <p><code>false</code> otherwise
* @see #hasSubmission(String)
* @see #getSubmission()
* @since 1.0
*/
public boolean hasSubmission()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.hasSubmission();
}
/**
* Indicates whether this element received a certain submission.
*
* @param submissionName the name of the submission
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return <code>true</code> if the submission was sent to this element;
* and
* <p><code>false</code> otherwise
* @see #hasSubmission()
* @see #getSubmission()
* @since 1.0
*/
public boolean hasSubmission(String submissionName)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == submissionName) throw new IllegalArgumentException("submissionName can't be null.");
if (0 == submissionName.length()) throw new IllegalArgumentException("submissionName can't be empty.");
return mElementContext.hasSubmission(submissionName);
}
/**
* Retrieves the name of the submission that was sent to this element
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return the name of the submission; or
* <p><code>null</code> if no submission was sent
* @see #hasSubmission()
* @see #hasSubmission(String)
* @since 1.0
*/
public String getSubmission()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getSubmission();
}
/**
* Checks whether a value has been provided to an parameter.
*
* @param name the name of the parameter
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return <code>true</code> if the parameter has a value; or
* <p><code>false</code> otherwise
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public boolean hasParameterValue(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.hasParameterValue(name);
}
/**
* Checks whether a parameter is empty.
*
* @param name the name of the parameter
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return <code>true</code> if the parameter is empty; or
* <p><code>false</code> otherwise
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public boolean isParameterEmpty(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.isParameterEmpty(name);
}
/**
* Retrieves the value of a parameter.
*
* @param name the name of the parameter
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the value of the parameter; or
* <p><code>null</code> if no value is present for this parameter
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public String getParameter(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.getParameter(name);
}
/**
* Retrieves the value of a parameter and returns a default value if no
* parameter value is present
*
* @param name the name of the parameter
* @param defaultValue the default value that will be used when no
* parameter value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the parameter value; or
* <p>the default value if no parameter value is present
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public String getParameter(String name, String defaultValue)
throws EngineException
{
String value = getParameter(name);
if (value == null)
{
return defaultValue;
}
return value;
}
/**
* Retrieves the names of all the parameters that are present.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return the list with the parameter names
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterNames(String)
* @since 1.0
*/
public ArrayList<String> getParameterNames()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getParameterNames(null);
}
/**
* Retrieves the names of all the parameters that are present and that
* match a regular expression.
*
* @param regexp the regular expression that will be used to filter the
* parameter names
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return the list with the parameter names
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterNames()
* @since 1.0
*/
public ArrayList<String> getParameterNames(String regexp)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getParameterNames(regexp);
}
/**
* Retrieves the values of a parameter.
*
* @param name the name of the parameter
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return a string array with all the parameter values; or
* <p><code>null</code> if no parameter values are present
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public String[] getParameterValues(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.getParameterValues(name);
}
/**
* Retrieves the value of a parameter and converts it to a boolean.
*
* @param name the name of the parameter
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted parameter value; or
* <p><code>false</code> if no parameter value is present or if the
* parameter value is not a valid boolean
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public boolean getParameterBoolean(String name)
throws EngineException
{
return getParameterBoolean(name, ElementInfo.DEFAULT_BOOLEAN);
}
/**
* Retrieves the value of a parameter and converts it to a boolean, using
* a default value if no parameter value is present.
*
* @param name the name of the parameter
* @param defaultValue the default value that will be used when no
* parameter value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted parameter value; or
* <p>the default value if no parameter value is present
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public boolean getParameterBoolean(String name, boolean defaultValue)
throws EngineException
{
String value = getParameter(name);
if (value == null)
{
return defaultValue;
}
return StringUtils.convertToBoolean(value);
}
/**
* Retrieves the value of a parameter and converts it to an integer.
*
* @param name the name of the parameter
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted parameter value; or
* <p><code>0</code> if no parameter value is present or if the parameter
* value is not a valid integer
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public int getParameterInt(String name)
throws EngineException
{
return getParameterInt(name, ElementInfo.DEFAULT_INTEGER);
}
/**
* Retrieves the value of a parameter and converts it to an integer, using
* a default value if no parameter value is present.
*
* @param name the name of the parameter
* @param defaultValue the default value that will be used when no
* parameter value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted parameter value; or
* <p>the default value if no parameter value is present
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public int getParameterInt(String name, int defaultValue)
throws EngineException
{
String value = getParameter(name);
if (value == null)
{
return defaultValue;
}
try
{
return Integer.parseInt(value);
}
catch (NumberFormatException e)
{
return defaultValue;
}
}
/**
* Retrieves the value of a parameter and converts it to a long.
*
* @param name the name of the parameter
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted parameter value; or
* <p><code>0L</code> if no parameter value is present or if the parameter
* value is not a valid long
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public long getParameterLong(String name)
throws EngineException
{
return getParameterLong(name, ElementInfo.DEFAULT_LONG);
}
/**
* Retrieves the value of a parameter and converts it to a long, using a
* default value if no parameter value is present.
*
* @param name the name of the parameter
* @param defaultValue the default value that will be used when no
* parameter value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted parameter value; or
* <p>the default value if no parameter value is present
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public long getParameterLong(String name, long defaultValue)
throws EngineException
{
String value = getParameter(name);
if (value == null)
{
return defaultValue;
}
try
{
return Long.parseLong(value);
}
catch (NumberFormatException e)
{
return defaultValue;
}
}
/**
* Retrieves the value of a parameter and converts it to a double.
*
* @param name the name of the parameter
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted parameter value; or
* <p><code>0.0d</code> if no parameter value is present or if the
* parameter value is not a valid double
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public double getParameterDouble(String name)
throws EngineException
{
return getParameterDouble(name, ElementInfo.DEFAULT_DOUBLE);
}
/**
* Retrieves the value of a parameter and converts it to a double, using a
* default value if no parameter value is present.
*
* @param name the name of the parameter
* @param defaultValue the default value that will be used when no
* parameter value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted parameter value; or
* <p>the default value if no parameter value is present
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public double getParameterDouble(String name, double defaultValue)
throws EngineException
{
String value = getParameter(name);
if (value == null)
{
return defaultValue;
}
try
{
return Double.parseDouble(value);
}
catch (NumberFormatException e)
{
return defaultValue;
}
}
/**
* Retrieves the value of a parameter and converts it to a float.
*
* @param name the name of the parameter
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted parameter value; or
* <p><code>0.0f</code> if no parameter value is present or if the
* parameter value is not a valid float
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public float getParameterFloat(String name)
throws EngineException
{
return getParameterFloat(name, ElementInfo.DEFAULT_FLOAT);
}
/**
* Retrieves the value of a parameter and converts it to a float, using a
* default value if no parameter value is present.
*
* @param name the name of the parameter
* @param defaultValue the default value that will be used when no
* parameter value is present
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the converted parameter value; or
* <p>the default value if no parameter value is present
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public float getParameterFloat(String name, float defaultValue)
throws EngineException
{
String value = getParameter(name);
if (value == null)
{
return defaultValue;
}
try
{
return Float.parseFloat(value);
}
catch (NumberFormatException e)
{
return defaultValue;
}
}
/**
* Retrieves the values of a parameter as an array of integers.
*
* @param name the name of the parameter
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return a integer array with all the parameter values; or
* <p><code>null</code> if no parameter values are present
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public int[] getParameterIntValues(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return ArrayUtils.createIntArray(mElementContext.getParameterValues(name));
}
/**
* Retrieves the values of a parameter as an array of longs.
*
* @param name the name of the parameter
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return a long array with all the parameter values; or
* <p><code>null</code> if no parameter values are present
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public long[] getParameterLongValues(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return ArrayUtils.createLongArray(mElementContext.getParameterValues(name));
}
/**
* Retrieves the values of a parameter as an array of floats.
*
* @param name the name of the parameter
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return a float array with all the parameter values; or
* <p><code>null</code> if no parameter values are present
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public float[] getParameterFloatValues(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return ArrayUtils.createFloatArray(mElementContext.getParameterValues(name));
}
/**
* Retrieves the values of a parameter as an array of doubles.
*
* @param name the name of the parameter
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* parameter is known with this name; or if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return a double array with all the parameter values; or
* <p><code>null</code> if no parameter values are present
* @see #getNamedSubmissionBean(String, String)
* @see #getSubmissionBean(String, Class, String)
* @see #fillSubmissionBean(String, Object, String)
* @see #hasParameterValue(String)
* @see #isParameterEmpty(String)
* @see #getParameter(String)
* @see #getParameter(String, String)
* @see #getParameterValues(String)
* @see #getParameterNames()
* @see #getParameterNames(String)
* @since 1.0
*/
public double[] getParameterDoubleValues(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return ArrayUtils.createDoubleArray(mElementContext.getParameterValues(name));
}
/**
* Retrieves the names of all the files that are present and that
* match a regular expression.
*
* @param regexp the regular expression that will be used to filter the
* file names
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return the list with the file names
* @see #getUploadedFileNames()
* @see #hasUploadedFile(String)
* @see #isFileEmpty(String)
* @see #getUploadedFile(String)
* @see #getUploadedFiles(String)
* @since 1.1
*/
public ArrayList<String> getUploadedFileNames(String regexp)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getUploadedFileNames(regexp);
}
/**
* Retrieves the list of uploaded file names.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return the list of uploaded file names
* @see #getUploadedFileNames(String)
* @see #hasUploadedFile(String)
* @see #isFileEmpty(String)
* @see #getUploadedFile(String)
* @see #getUploadedFiles(String)
* @since 1.0
*/
public ArrayList<String> getUploadedFileNames()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getUploadedFileNames();
}
/**
* Checks if a particular file has been uploaded during the last
* submission.
*
* @param name the name of the file, as declared in the submission
* @exception com.uwyn.rife.engine.exceptions.EngineException if no file
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return <code>true</code> if the file was uploaded; or
* <p><code>false</code> otherwise
* @see #getUploadedFileNames(String)
* @see #getUploadedFileNames()
* @see #isFileEmpty(String)
* @see #getUploadedFile(String)
* @see #getUploadedFiles(String)
* @since 1.0
*/
public boolean hasUploadedFile(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.hasUploadedFile(name);
}
/**
* Checks if an uploaded file wasn't sent or if it is empty.
*
* @param name the name of the file, as declared in the submission
* @exception com.uwyn.rife.engine.exceptions.EngineException if no file
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return <code>true</code> if the file wasn't uploaded or empty; or
* <p>false otherwise
* @see #getUploadedFileNames(String)
* @see #getUploadedFileNames()
* @see #hasUploadedFile(String)
* @see #getUploadedFile(String)
* @see #getUploadedFiles(String)
* @since 1.0
*/
public boolean isFileEmpty(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.isFileEmpty(name);
}
/**
* Retrieves an uploaded file.
*
* @param name the name of the file, as declared in the submission
* @exception com.uwyn.rife.engine.exceptions.EngineException if no file
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the uploaded file; or
* <p><code>null</code> if no file was uploaded
* @see #getUploadedFileNames(String)
* @see #getUploadedFileNames()
* @see #hasUploadedFile(String)
* @see #isFileEmpty(String)
* @see #getUploadedFiles(String)
* @since 1.0
*/
public UploadedFile getUploadedFile(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.getUploadedFile(name);
}
/**
* Retrieves all files that have been uploaded for a particular name.
*
* @param name the name of the file, as declared in the submission
* @exception com.uwyn.rife.engine.exceptions.EngineException if no file
* is known with this name; or if you don't have access to the request
* data (eg. you're inside a child trigger); or if there's no active
* element context (eg. you're using this method inside the constructor
* instead of inside the {@link #initialize()} method)
* @return the uploaded files; or
* <p><code>null</code> if no files were uploaded for that name
* @see #getUploadedFileNames(String)
* @see #getUploadedFileNames()
* @see #hasUploadedFile(String)
* @see #isFileEmpty(String)
* @see #getUploadedFile(String)
* @since 1.0
*/
public UploadedFile[] getUploadedFiles(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
return mElementContext.getUploadedFiles(name);
}
/**
* Generates a query URL for a submission.
*
* @param name the name of the submission
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* submission is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the generated URL as a character sequence
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public CharSequence getSubmissionQueryUrl(String name)
throws EngineException
{
return getSubmissionQueryUrl(name, null, null);
}
/**
* Generates a query URL for a submission and appends a pathinfo to the
* URL of the element.
*
* @param name the name of the submission
* @param pathinfo the pathinfo that will be appended; or
* <code>null</code> if no pathinfo should be appended
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* submission is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the generated URL as a character sequence
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public CharSequence getSubmissionQueryUrl(String name, String pathinfo)
throws EngineException
{
return getSubmissionQueryUrl(name, pathinfo, null);
}
/**
* Generates a query URL for a submission with default parameter values.
*
* @param name the name of the submission
* @param parameterValues an array of string pairs that will be used to
* set default parameter values; or <code>null</code> if no default
* parameter values should be used
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* submission is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the generated URL as a character sequence
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public CharSequence getSubmissionQueryUrl(String name, String[] parameterValues)
throws EngineException
{
return getSubmissionQueryUrl(name, null, parameterValues);
}
/**
* Generates a query URL for a submission and appends a pathinfo to the
* URL of the element, default parameter values can also be added.
* <p>This will take the current element context into account with the
* available inputs, global variables, ... and generate an URL that
* persists the data state according to the declared site structure.
* <p>The default parameter values are provided as an array of strings
* that should be structured in pairs. For example, if these output values
* should be used: <code>param1</code>:<code>value1</code> and
* <code>param2</code>:<code>value2</code>, you should define the
* following string array:
* <pre>new String[] {"param1", "value1", "param2", "value2"}</pre>
* <p>The generated URL with not contain a scheme, host or port. It will
* begin with the path part and be absolute, starting with the web
* application's root URL.
*
* @param name the name of the submission
* @param pathinfo the pathinfo that will be appended; or
* <code>null</code> if no pathinfo should be appended
* @param parameterValues an array of string pairs that will be used to
* set default parameter values; or <code>null</code> if no default
* parameter values should be used
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* submission is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the generated URL as a character sequence
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public CharSequence getSubmissionQueryUrl(String name, String pathinfo, String[] parameterValues)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null != parameterValues &&
parameterValues.length % 2 > 0) throw new IllegalArgumentException("parameterValues should be a series of key/value pairs.");
return mElementContext.getSubmissionQueryUrl(name, pathinfo, parameterValues);
}
/**
* Generates a form action URL for a submission.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return the generated URL as a character sequence
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public CharSequence getSubmissionFormUrl()
throws EngineException
{
return getSubmissionFormUrl(null);
}
/**
* Generates a form action URL for a submission and appends a pathinfo to
* the URL of the element.
* <p>This will take the current element context into account with the
* available inputs, global variables, ... and generate an URL that
* persists the data state according to the declared site structure.
* <p>The generated URL with not contain a scheme, host or port. It will
* begin with the path part and be absolute, starting with the web
* application's root URL.
* <p>This method goes together with the {@link
* #getSubmissionFormParameters(String, String[])} method since the state
* is tranferred as hidden form parameters that are part of the form.
*
* @param pathinfo the pathinfo that will be appended; or
* <code>null</code> if no pathinfo should be appended
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return the generated URL as a character sequence
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public CharSequence getSubmissionFormUrl(String pathinfo)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getSubmissionFormUrl(pathinfo);
}
/**
* Generates the hidden XHTML form parameters for a submission.
*
* @param name the name of the submission
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* submission is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the generated parameters as a character sequence
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public CharSequence getSubmissionFormParameters(String name)
throws EngineException
{
return getSubmissionFormParameters(name, null);
}
/**
* Generates the hidden XHTML form parameters for a submission and
* overrides the current output values only for this method.
* <p>This will take the current element context into account with the
* available inputs, global variables, ... and generate hidden XHTML form
* parameters that persist the data state according to the declared site
* structure.
* <p>The default parameter values are provided as an array of strings
* that should be structured in pairs. For example, if these output values
* should be used: <code>param1</code>:<code>value1</code> and
* <code>param2</code>:<code>value2</code>, you should define the
* following string array:
* <pre>new String[] {"param1", "value1", "param2", "value2"}</pre>
* <p>This method goes together with the {@link
* #getSubmissionFormUrl(String)} method since the URL needs to be
* provided in the action attribute of the form.
*
* @param name the name of the submission
* @param parameterValues an array of string pairs that will be used to
* set default parameter values; or <code>null</code> if no default
* parameter values should be used
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* submission is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the generated parameters as a character sequence
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParametersJavascript(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public CharSequence getSubmissionFormParameters(String name, String[] parameterValues)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null != parameterValues &&
parameterValues.length % 2 > 0) throw new IllegalArgumentException("parameterValues should be a series of key/value pairs.");
return mElementContext.getSubmissionFormParameters(name, parameterValues);
}
/**
* Generates Javascript that will generate hidden XHTML form parameters for
* a submission and overrides the current output values only for this method.
* <p>This will take the current element context into account with the
* available inputs, global variables, ... and generate hidden XHTML form
* parameters that persist the data state according to the declared site
* structure.
* <p>The default parameter values are provided as an array of strings
* that should be structured in pairs. For example, if these output values
* should be used: <code>param1</code>:<code>value1</code> and
* <code>param2</code>:<code>value2</code>, you should define the
* following string array:
* <pre>new String[] {"param1", "value1", "param2", "value2"}</pre>
* <p>This method goes together with the {@link
* #getSubmissionFormUrl(String)} method since the URL needs to be
* provided in the action attribute of the form.
*
* @param name the name of the submission
* @param parameterValues an array of string pairs that will be used to
* set default parameter values; or <code>null</code> if no default
* parameter values should be used
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* submission is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the generated parameters as a character sequence
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.6
*/
public CharSequence getSubmissionFormParametersJavascript(String name, String[] parameterValues)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null != parameterValues &&
parameterValues.length % 2 > 0) throw new IllegalArgumentException("parameterValues should be a series of key/value pairs.");
return mElementContext.getSubmissionFormParametersJavascript(name, parameterValues);
}
/**
* Generates a query URL for a submission sets it as the content of a
* template value.
*
* @param template the template that will be used to set the value
* @param name the name of the submission
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifier
* <code>SUBMISSION:QUERY:submissionname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* submission is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public void setSubmissionQuery(Template template, String name)
throws TemplateException, EngineException
{
setSubmissionQuery(template, name, null, null);
}
/**
* Generates a query URL for a submission with a pathinfo and sets it as
* the content of a template value.
*
* @param template the template that will be used to set the value
* @param name the name of the submission
* @param pathinfo the pathinfo that will be appended; or
* <code>null</code> if no pathinfo should be appended
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifier
* <code>SUBMISSION:QUERY:submissionname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* submission is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public void setSubmissionQuery(Template template, String name, String pathinfo)
throws TemplateException, EngineException
{
setSubmissionQuery(template, name, pathinfo, null);
}
/**
* Generates a query URL for a submission with default parameter values
* and sets it as the content of a template value.
*
* @param template the template that will be used to set the value
* @param name the name of the submission
* @param parameterValues an array of string pairs that will be used to
* set default parameter values; or <code>null</code> if no default
* parameter values should be used
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifier
* <code>SUBMISSION:QUERY:submissionname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* submission is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public void setSubmissionQuery(Template template, String name, String[] parameterValues)
throws TemplateException, EngineException
{
setSubmissionQuery(template, name, null, parameterValues);
}
/**
* Generates a query URL for a submission with pathinfo and default
* parameter values and sets it as the content of a template value.
* <p>The URL will be generated by calling the {@link
* #getSubmissionQueryUrl(String, String, String[])} method and it will be
* set to the value identifier with the syntax
* <code>SUBMISSION:QUERY:submissionname</code>.
* <p>Template content that is outputted with the
* <code>#print(Template)</code> method will automatically be scanned for
* value identifiers with this syntax and the submission query URLs will
* generated. You should only use this method if you need a submission URL
* to be generated in a certain context.
*
* @param template the template that will be used to set the value
* @param name the name of the submission
* @param pathinfo the pathinfo that will be appended; or
* <code>null</code> if no pathinfo should be appended
* @param parameterValues an array of string pairs that will be used to
* set default parameter values; or <code>null</code> if no default
* parameter values should be used
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifier
* <code>SUBMISSION:QUERY:submissionname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* submission is known with this name; if you don't have access to the
* request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public void setSubmissionQuery(Template template, String name, String pathinfo, String[] parameterValues)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null != parameterValues &&
parameterValues.length % 2 > 0) throw new IllegalArgumentException("parameterValues should be a series of key/value pairs.");
mElementContext.setSubmissionQuery(template, name, pathinfo, parameterValues);
}
/**
* Generates a form action URL for an submission and sets it as the
* content of a template value.
*
* @param template the template that will be used to set the value
* @param name the name of the submission
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifiers
* <code>SUBMISSION:FORM:submissionname</code> and
* <code>SUBMISSION:PARAMS:submissionname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public void setSubmissionForm(Template template, String name)
throws TemplateException, EngineException
{
setSubmissionForm(template, name, null, null);
}
/**
* Generates a form action URL for an submission with a pathinfo and sets
* it as the content of a template value.
*
* @param template the template that will be used to set the value
* @param name the name of the submission
* @param pathinfo the pathinfo that will be appended; or
* <code>null</code> if no pathinfo should be appended
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifiers
* <code>SUBMISSION:FORM:submissionname</code> and
* <code>SUBMISSION:PARAMS:submissionname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public void setSubmissionForm(Template template, String name, String pathinfo)
throws TemplateException, EngineException
{
setSubmissionForm(template, name, pathinfo, null);
}
/**
* Generates a form action URL for an submission with default parameter
* values and sets it as the content of a template value.
*
* @param template the template that will be used to set the value
* @param name the name of the submission
* @param parameterValues an array of string pairs that will be used to
* set default parameter values; or <code>null</code> if no default
* parameter values should be used
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifiers
* <code>SUBMISSION:FORM:submissionname</code> and
* <code>SUBMISSION:PARAMS:submissionname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @see #setSubmissionForm(Template, String, String)
* @since 1.0
*/
public void setSubmissionForm(Template template, String name, String[] parameterValues)
throws TemplateException, EngineException
{
setSubmissionForm(template, name, null, parameterValues);
}
/**
* Generates a form action URL for an submission with a pathinfo and
* default parameter values and sets it as the content of a template
* value.
* <p>The URL will be generated by calling the {@link
* #getSubmissionFormUrl(String)} and {@link
* #getSubmissionFormParameters(String, String[])} methods and it will be
* set the results to the value identifiers with the syntax
* <code>SUBMISSION:FORM:submissionname</code> and
* <code>SUBMISSION:PARAMS:submissionname</code>.
* <p>Template content that is outputted with the
* <code>#print(Template)</code> method will automatically be scanned for
* value identifiers with this syntax and the submission forms URLs and
* parameters will generated. You should only use this method if you need
* these to be generated in a certain context.
*
* @param template the template that will be used to set the value
* @param name the name of the submission
* @param pathinfo the pathinfo that will be appended; or
* <code>null</code> if no pathinfo should be appended
* @param parameterValues an array of string pairs that will be used to
* set default parameter values; or <code>null</code> if no default
* parameter values should be used
* @exception com.uwyn.rife.template.exceptions.TemplateException if the
* template doesn't contain the value identifiers
* <code>SUBMISSION:FORM:submissionname</code> and
* <code>SUBMISSION:PARAMS:submissionname</code>
* @exception com.uwyn.rife.engine.exceptions.EngineException if no exit
* is known with this name; if the exit hasn't got a destination element;
* if you don't have access to the request data (eg. you're inside a child
* trigger); or if there's no active element context (eg. you're using
* this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @see #getSubmissionQueryUrl(String, String, String[])
* @see #getSubmissionFormUrl(String)
* @see #getSubmissionFormParameters(String, String[])
* @see #setSubmissionQuery(Template, String, String, String[])
* @since 1.0
*/
public void setSubmissionForm(Template template, String name, String pathinfo, String[] parameterValues)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
if (null != parameterValues &&
parameterValues.length % 2 > 0) throw new IllegalArgumentException("parameterValues should be a series of key/value pairs.");
mElementContext.setSubmissionForm(template, name, pathinfo, parameterValues);
}
/**
* Processes an embedded element without a differentiator in a template.
* <p>Embedded elements are evaluated when value identifiers have the
* following syntax: <code>ELEMENT:elementId</code>.
* <p>All embedded elements are automatically processed when the template
* is instantiated, so this method should only be called if you need to
* re-process an embedded element in a particular context.
*
* @param template the template that will be used to process the embedded
* template
* @param elementId the identifier of the element
* @exception com.uwyn.rife.template.exceptions.TemplateException when an
* error occurs during the template processing
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* element is known with that identifier; or if you don't have access to
* the request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #processEmbeddedElement(Template, String, Object)
* @see #processEmbeddedElement(Template, String, String)
* @see #processEmbeddedElement(Template, String, String, Object)
* @since 1.0
*/
public void processEmbeddedElement(Template template, String elementId)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == elementId) throw new IllegalArgumentException("elementId can't be null.");
if (0 == elementId.length()) throw new IllegalArgumentException("elementId can't be empty.");
mElementContext.processEmbeddedElement(template, this, elementId, null, null);
}
/**
* Processes an embedded element without a differentiator in a template
* and pass on data to the processed embedded element.
* <p>See {@link #processEmbeddedElement(Template, String)} for more
* information.
*
* @param template the template that will be used to process the embedded
* template
* @param elementId the identifier of the element
* @param data the data that will be available from within the embedded
* element
* @exception com.uwyn.rife.template.exceptions.TemplateException when an
* error occurs during the template processing
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* element is known with that identifier; or if you don't have access to
* the request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #processEmbeddedElement(Template, String)
* @see #processEmbeddedElement(Template, String, String)
* @see #processEmbeddedElement(Template, String, String, Object)
* @since 1.5
*/
public void processEmbeddedElement(Template template, String elementId, Object data)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == elementId) throw new IllegalArgumentException("elementId can't be null.");
if (0 == elementId.length()) throw new IllegalArgumentException("elementId can't be empty.");
mElementContext.processEmbeddedElement(template, this, elementId, null, data);
}
/**
* Processes an embedded element with a differentiator in a template.
* <p>Embedded elements are evaluated when value identifiers have the
* following syntax: <code>ELEMENT:elementId:differentiator</code>.
* <p>All embedded elements are automatically processed when the template
* is instantiated, so this method should only be called if you need to
* re-process an embedded element in a particular context.
*
* @param template the template that will be used to process the embedded
* template
* @param elementId the identifier of the element
* @param differentiator the differentiator that will be used; or
* <code>null</code> if no differentiator should be used
* @exception com.uwyn.rife.template.exceptions.TemplateException when an
* error occurs during the template processing
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* element is known with that identifier; or if you don't have access to
* the request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #processEmbeddedElement(Template, String)
* @see #processEmbeddedElement(Template, String, Object)
* @see #processEmbeddedElement(Template, String, String, Object)
* @since 1.0
*/
public void processEmbeddedElement(Template template, String elementId, String differentiator)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == elementId) throw new IllegalArgumentException("elementId can't be null.");
if (0 == elementId.length()) throw new IllegalArgumentException("elementId can't be empty.");
mElementContext.processEmbeddedElement(template, this, elementId, differentiator, null);
}
/**
* Processes an embedded element with a differentiator in a template
* and pass on data to the processed embedded element.
* <p>See {@link #processEmbeddedElement(Template, String, String)} for more
* information.
*
* @param template the template that will be used to process the embedded
* template
* @param elementId the identifier of the element
* @param differentiator the differentiator that will be used; or
* @param data the data that will be available from within the embedded
* element
* <code>null</code> if no differentiator should be used
* @exception com.uwyn.rife.template.exceptions.TemplateException when an
* error occurs during the template processing
* @exception com.uwyn.rife.engine.exceptions.EngineException if no
* element is known with that identifier; or if you don't have access to
* the request data (eg. you're inside a child trigger); or if there's no
* active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #processEmbeddedElement(Template, String)
* @see #processEmbeddedElement(Template, String, Object)
* @see #processEmbeddedElement(Template, String, String)
* @since 1.5
*/
public void processEmbeddedElement(Template template, String elementId, String differentiator, Object data)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == elementId) throw new IllegalArgumentException("elementId can't be null.");
if (0 == elementId.length()) throw new IllegalArgumentException("elementId can't be empty.");
mElementContext.processEmbeddedElement(template, this, elementId, differentiator, data);
}
/**
* Evaluate the <code>ROLEUSER</code> expression tags in a template.
* <p>The {@link #print(Template)} method automatically evaluates all role
* user expression tags. This method should thus only be called when you
* need them to be evaluated in a specific context.
* <p>This block and value expression tag is evaluated through a method
* that's not part of the {@link com.uwyn.rife.template.Template} class
* since it only makes sense in an element context where a users can be
* identified.
* <p>The value tags have the following syntax
* <code>LANGUAGE:ROLEUSER:identifier</code> and the block tags have the
* following syntax
* <code>LANGUAGE:ROLEUSER:identifier:[[ boolean_expression ]]</code>.
* <p>Below is an example of roleuser expression tags in use:
* <pre><!--V 'OGNL:ROLEUSER:role1'-->User is not in role "admin"<!--/V-->
*<!--B 'OGNL:ROLEUSER:role1:[[ isInRole("admin") ]]'-->User is in role "admin"<!--/B--></pre>
*
* @param template the template instance where the evaluation should
* happen
* @param id the block and the value identifier
* @return the list of names of the template values that were generated
* @exception com.uwyn.rife.template.exceptions.TemplateException when an
* error occurs during the expression tags evaluation
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @since 1.0
*/
public List<String> evaluateExpressionRoleUserTags(Template template, String id)
throws TemplateException, EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
if (null == template) throw new IllegalArgumentException("template can't be null.");
if (null == id)
{
return Collections.emptyList();
}
List<String> set_values = new ArrayList<String>();
mElementContext.evaluateExpressionRoleUserTags(set_values, template, id);
return set_values;
}
/**
* Activates an exit.
* <p>This immediately breaks out of the element and notifies the engine
* that the next step of the flow must be looked up and executed.
*
* @param name the name of the exit
* @exception com.uwyn.rife.engine.exceptions.EngineException a runtime
* exception that is used to immediately interrupt the execution, don't
* catch this exception; or there's no active element context (eg. you're
* using this method inside the constructor instead of inside the {@link
* #initialize()} method)
* @since 1.0
*/
public void exit(String name)
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
if (null == name) throw new IllegalArgumentException("name can't be null.");
if (0 == name.length()) throw new IllegalArgumentException("name can't be empty.");
mElementContext.exit(name);
}
/**
* Interrupts the execution in this element and transfers the execution to
* the child element.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException a runtime
* exception that is used to immediately interrupt the execution, don't
* catch this exception; or you don't have access to the request data (eg.
* you're inside a child trigger); or there's no active element context
* (eg. you're using this method inside the constructor instead of inside
* the {@link #initialize()} method)
* @since 1.0
*/
public void child()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.child();
}
/**
* Interrupts the execution in RIFE completely and defers it to the
* servlet container.
* <p>If RIFE is being run as a filter, it will execute the next filter in
* the chain.
* <p>If RIFE is being run as a servlet, the status code <code>404: Not
* Found</code> will be sent to the client.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException a runtime
* exception that is used to immediately interrupt the execution, don't
* catch this exception; or you don't have access to the request data (eg.
* you're inside a child trigger); or there's no active element context
* (eg. you're using this method inside the constructor instead of inside
* the {@link #initialize()} method)
* @since 1.0
*/
public void defer()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.defer();
}
/**
* Interrupts the execution in this element and forwards the entire
* request to another URL.
* <p>The response of the forwarded request will be sent the to original
* client, as if the request was sent directly to the forwarded URL.
*
* @param url the URL to which the request will be forwarded
* @exception com.uwyn.rife.engine.exceptions.EngineException a runtime
* exception that is used to immediately interrupt the execution, don't
* catch this exception; or you don't have access to the request data (eg.
* you're inside a child trigger); or there's no active element context
* (eg. you're using this method inside the constructor instead of inside
* the {@link #initialize()} method)
* @since 1.0
*/
public void forward(String url)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.forward(url);
}
/**
* Interrupts the execution in this element and redirects the client to
* another URL.
*
* @param url the URL to which the request will be redirected
* @exception com.uwyn.rife.engine.exceptions.EngineException a runtime
* exception that is used to immediately interrupt the execution, don't
* catch this exception; or you don't have access to the request data (eg.
* you're inside a child trigger); or there's no active element context
* (eg. you're using this method inside the constructor instead of inside
* the {@link #initialize()} method)
* @since 1.0
*/
public void redirect(String url)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.redirect(url);
}
/**
* Returns the name of the character encoding (MIME charset) used for the
* body sent in this response. The character encoding may have been
* specified explicitly using the {@link #setContentType} method, or
* implicitly using the {@link #setResponseLocale} method. Explicit
* specifications take precedence over implicit specifications. If no
* character encoding has been specified, <code>ISO-8859-1</code> is
* returned.
* <p>See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) for more
* information about character encoding and MIME.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return a <code>String</code> specifying the name of the character
* encoding, for example, <code>UTF-8</code>
* @see #setContentType #setResponseLocale
* @since 1.0
*/
public String getResponseCharacterEncoding()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getResponse().getCharacterEncoding();
}
/**
* Sets the length of the content body in the response In HTTP servlets,
* this method sets the HTTP Content-Length header.
*
* @param length an integer specifying the length of the content being
* returned to the client; sets the Content-Length header
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @since 1.0
*/
public void setContentLength(int length)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().setContentLength(length);
}
/**
* Sets the content type of the response being sent to the client, if the
* response has not been committed yet. The given content type may include
* a character encoding specification, for example,
* <code>text/html;charset=UTF-8</code>. The response's character encoding
* is only set from the given content type if this method is called before
* <code>getWriter</code> is called.
* <p>This method may be called repeatedly to change content type and
* character encoding. This method has no effect if called after the
* response has been committed. It does not set the response's character
* encoding if it is called after <code>getWriter</code> has been called
* or after the response has been committed.
* <p>Containers must communicate the content type and the character
* encoding used for the servlet response's writer to the client if the
* protocol provides a way for doing so. In the case of HTTP, the
* <code>Content-Type</code> header is used.
*
* @param type a <code>String</code> specifying the MIME type of the
* content
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #setResponseLocale
* @see #getOutputStream
* @since 1.0
*/
public void setContentType(String type)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().setContentType(type);
}
/**
* Adds a response header with the given name and value. This method
* allows response headers to have multiple values.
*
* @param name the name of the header
* @param value the additional header value If it contains octet string,
* it should be encoded according to RFC 2047
* (http://www.ietf.org/rfc/rfc2047.txt)
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #setHeader
* @since 1.0
*/
public void addHeader(String name, String value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().addHeader(name, value);
}
/**
* Sets a response header with the given name and date-value. The date is
* specified in terms of milliseconds since the epoch. If the header had
* already been set, the new value overwrites the previous one. The
* <code>containsHeader</code> method can be used to test for the presence
* of a header before setting its value.
*
* @param name the name of the header to set
* @param date the assigned date value
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #setDateHeader
* @since 1.0
*/
public void addDateHeader(String name, long date)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().addDateHeader(name, date);
}
/**
* Adds a response header with the given name and integer value. This
* method allows response headers to have multiple values.
*
* @param name the name of the header
* @param value the assigned integer value
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #setIntHeader
* @since 1.0
*/
public void addIntHeader(String name, int value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().addIntHeader(name, value);
}
/**
* Returns a boolean indicating whether the named response header has
* already been set.
*
* @param name the header name
* @return <code>true</code> if the named response header has already been
* set; or
* <p><code>false</code> otherwise
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @since 1.0
*/
public boolean containsHeader(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getResponse().containsHeader(name);
}
/**
* Sends an error response to the client using the specified status code
* and clearing the buffer.
* <p>If the response has already been committed, this method throws an
* IllegalStateException. After using this method, the response should be
* considered to be committed and should not be written to.
*
* @param statusCode the error status code
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #sendError(int, String)
* @since 1.0
*/
public void sendError(int statusCode)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().sendError(statusCode);
}
/**
* Sends an error response to the client using the specified status. The
* server defaults to creating the response to look like an HTML-formatted
* server error page containing the specified message, setting the content
* type to "text/html", leaving cookies and other headers unmodified. If
* an error-page declaration has been made for the web application
* corresponding to the status code passed in, it will be served back in
* preference to the suggested msg parameter.
* <p>If the response has already been committed, this method throws an
* IllegalStateException. After using this method, the response should be
* considered to be committed and should not be written to.
*
* @param statusCode the error status code
* @param message the descriptive message
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #sendError(int)
* @since 1.0
*/
public void sendError(int statusCode, String message)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().sendError(statusCode, message);
}
/**
* Sends a temporary redirect response to the client using the specified
* redirect location URL. This method can accept relative URLs; the
* servlet container must convert the relative URL to an absolute URL
* before sending the response to the client. If the location is relative
* without a leading '/' the container interprets it as relative to the
* current request URI. If the location is relative with a leading '/' the
* container interprets it as relative to the servlet container root.
* <p>If the response has already been committed, this method throws an
* IllegalStateException. After using this method, the response should be
* considered to be committed and should not be written to.
*
* @param location the redirect location URL
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @since 1.0
*/
public void sendRedirect(String location)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().sendRedirect(location);
}
/**
* Sets up the current request to prevent all caching of the response by
* the client.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @since 1.0
*/
public void preventCaching()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
ServletUtils.preventCaching(mElementContext.getResponse());
}
/**
* Sets a response header with the given name and date-value. The date is
* specified in terms of milliseconds since the epoch. If the header had
* already been set, the new value overwrites the previous one. The
* <code>containsHeader</code> method can be used to test for the presence
* of a header before setting its value.
*
* @param name the name of the header to set
* @param date the assigned date value
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #containsHeader
* @see #addDateHeader
* @since 1.0
*/
public void setDateHeader(String name, long date)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().setDateHeader(name, date);
}
/**
* Sets a response header with the given name and value. If the header had
* already been set, the new value overwrites the previous one. The
* <code>containsHeader</code> method can be used to test for the presence
* of a header before setting its value.
*
* @param name the name of the header
* @param value the header value If it contains octet string, it should be
* encoded according to RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt)
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #containsHeader
* @see #addHeader
* @since 1.0
*/
public void setHeader(String name, String value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().setHeader(name, value);
}
/**
* Sets a response header with the given name and integer value. If the
* header had already been set, the new value overwrites the previous one.
* The <code>containsHeader</code> method can be used to test for the
* presence of a header before setting its value.
*
* @param name the name of the header
* @param value the assigned integer value
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #containsHeader
* @see #addIntHeader
* @since 1.0
*/
public void setIntHeader(String name, int value)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().setIntHeader(name, value);
}
/**
* Sets the status code for this response. This method is used to set the
* return status code when there is no error (for example, for the status
* codes SC_OK or SC_MOVED_TEMPORARILY). If there is an error, and the
* caller wishes to invoke an error-page defined in the web application,
* the <code>sendError</code> method should be used instead.
* <p>The container clears the buffer and sets the Location header,
* preserving cookies and other headers.
*
* @param statusCode the status code
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #sendError
* @since 1.0
*/
public void setStatus(int statusCode)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().setStatus(statusCode);
}
/**
* Sets the locale of the response, if the response has not been committed
* yet. It also sets the response's character encoding appropriately for
* the locale, if the character encoding has not been explicitly set using
* {@link #setContentType} and the response hasn't been committed yet. If
* the deployment descriptor contains a
* <code>locale-encoding-mapping-list</code> element, and that element
* provides a mapping for the given locale, that mapping is used.
* Otherwise, the mapping from locale to character encoding is container
* dependent.
* <p>This method may be called repeatedly to change locale and character
* encoding. The method has no effect if called after the response has
* been committed. It does not set the response's character encoding if it
* is called after {@link #setContentType} has been called with a charset
* specification, or after the response has been committed.
* <p>Containers must communicate the locale and the character encoding
* used for the servlet response's writer to the client if the protocol
* provides a way for doing so. In the case of HTTP, the locale is
* communicated via the <code>Content-Language</code> header, the
* character encoding as part of the <code>Content-Type</code> header for
* text media types. Note that the character encoding cannot be
* communicated via HTTP headers if the servlet does not specify a content
* type; however, it is still used to encode text written via the servlet
* response's writer.
*
* @param locale the locale of the response
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @see #getResponseLocale
* @see #setContentType
* @since 1.0
*/
public void setResponseLocale(Locale locale)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getResponse().setLocale(locale);
}
/**
* Returns the locale specified for this response using the {@link
* #setResponseLocale} method. Calls made to
* <code>setResponseLocale</code> after the response is committed have no
* effect. If no locale has been specified, the container's default locale
* is returned.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return the locale of the response
* @see #setResponseLocale
* @since 1.0
*/
public Locale getResponseLocale()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getResponse().getLocale();
}
/**
* Returns the root URL of the server that is running this web
* applications.
* <p>This includes the protocol, the server name and the server port, for
* example: <code>http://www.somehost.com:8080</code>.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return the server's root url
* @since 1.0
*/
public String getServerRootUrl()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getServerRootUrl(-1);
}
/**
* Returns the root URL of this web applications.
* <p>This includes the protocol, the server name, the server port and the
* URL of RIFE's gateway, for example:
* <code>http://www.somehost.com:8080/my/webapp/</code>.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return the web application's root url
* @since 1.0
*/
public String getWebappRootUrl()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getWebappRootUrl(-1);
}
/**
* Returns the name of the character encoding used in the body of this
* request. This method returns <code>null</code> if the request does not
* specify a character encoding
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return a <code>String</code> containing the name of the character
* encoding; or
* <p><code>null</code> if the request does not specify a character
* encoding
* @since 1.0
*/
public String getRequestCharacterEncoding()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getCharacterEncoding();
}
/**
* Returns the MIME type of the body of the request, or <code>null</code>
* if the type is not known. For HTTP servlets, same as the value of the
* CGI variable CONTENT_TYPE.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return a <code>String</code> containing the name of the MIME type of
* the request; or
* <p><code>null</code> if the type is not known
* @since 1.0
*/
public String getContentType()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getContentType();
}
/**
* Returns the value of the specified request header as a
* <code>long</code> value that represents a <code>Date</code> object. Use
* this method with headers that contain dates, such as
* <code>If-Modified-Since</code>.
* <p>The date is returned as the number of milliseconds since January 1,
* 1970 GMT. The header name is case insensitive.
* <p>If the request did not have a header of the specified name, this
* method returns -1. If the header can't be converted to a date, the
* method throws an <code>IllegalArgumentException</code>.
*
* @param name a <code>String</code> specifying the name of the header
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return a <code>long</code> value representing the date specified in
* the header expressed as the number of milliseconds since January 1,
* 1970 GMT, or -1 if the named header was not included with the request
* @since 1.0
*/
public long getDateHeader(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getDateHeader(name);
}
/**
* Returns the value of the specified request header as a
* <code>String</code>. If the request did not include a header of the
* specified name, this method returns <code>null</code>. If there are
* multiple headers with the same name, this method returns the first head
* in the request. The header name is case insensitive. You can use this
* method with any request header.
*
* @param name a <code>String</code> specifying the header name
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return a <code>String</code> containing the value of the requested
* header; or
* <p><code>null</code> if the request does not have a header of that name
* @since 1.0
*/
public String getHeader(String name)
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getHeader(name);
}
/**
* Returns an enumeration of all the header names this request contains.
* If the request has no headers, this method returns an empty
* enumeration.
* <p>Some servlet containers do not allow servlets to access headers
* using this method, in which case this method returns <code>null</code>
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return an enumeration of all the header names sent with this request;
* if the request has no headers, an empty enumeration; if the servlet
* container does not allow servlets to use this method, <code>null</code>
* @since 1.0
*/
public Enumeration getHeaderNames()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getHeaderNames();
}
/**
* Returns all the values of the specified request header as an
* <code>Enumeration</code> of <code>String</code> objects.
* <p>Some headers, such as <code>Accept-Language</code> can be sent by
* clients as several headers each with a different value rather than
* sending the header as a comma separated list.
* <p>If the request did not include any headers of the specified name,
* this method returns an empty <code>Enumeration</code>. The header name
* is case insensitive. You can use this method with any request header.
*
* @param name a <code>String</code> specifying the header name
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return an <code>Enumeration</code> containing the values of the
* requested header. If the request does not have any headers of that name
* return an empty enumeration. If the container does not allow access to
* header information, it returns <code>null</code>.
* @since 1.0
*/
public Enumeration getHeaders(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getHeaders(name);
}
/**
* Retrieves initialization configuration of this web application.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return the initialization configuration instance of this web
* application
* @see InitConfig
* @since 1.0
*/
public InitConfig getInitConfig()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getInitConfig();
}
/**
* Returns the value of the specified request header as an
* <code>int</code>. If the request does not have a header of the
* specified name, this method returns -1. If the header cannot be
* converted to an integer, this method throws a
* <code>NumberFormatException</code>.
* <p>The header name is case insensitive.
*
* @param name a <code>String</code> specifying the name of a request
* header
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return an integer expressing the value of the request header; or
* <p><code>-1</code> if the request doesn't have a header of this name
* @since 1.0
*/
public int getIntHeader(String name)
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getIntHeader(name);
}
/**
* Returns the preferred <code>Locale</code> that the client will accept
* content in, based on the Accept-Language header. If the client request
* doesn't provide an Accept-Language header, this method returns the
* default locale for the server.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return the preferred <code>Locale</code> for the client
* @since 1.0
*/
public Locale getRequestLocale()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getLocale();
}
/**
* Returns an <code>Enumeration</code> of <code>Locale</code> objects
* indicating, in decreasing order starting with the preferred locale, the
* locales that are acceptable to the client based on the Accept-Language
* header. If the client request doesn't provide an Accept-Language
* header, this method returns an <code>Enumeration</code> containing one
* <code>Locale</code>, the default locale for the server.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return an <code>Enumeration</code> of preferred <code>Locale</code>
* objects for the client
* @since 1.0
*/
public Enumeration getRequestLocales()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getLocales();
}
/**
* Returns any extra path information associated with the URL the client
* sent when it made this request. The extra path information follows the
* element URL but precedes the query string and will start with a "/"
* character.
* <p>The URL of an element that should support pathinfo, has to end with
* an asterisk (for example: <code>/my/url/*</code>).
* <p>This method returns an empty string if there was no extra path
* information.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return a <code>String</code>, decoded by the web engine, specifying
* extra path information that comes after the element URL but before the
* query string in the request URL; or
* <p>or an empty string if the URL does not have any extra path
* information
* @since 1.0
*/
public String getPathInfo()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getElementState().getPathInfo();
}
/**
* Returns the method of this request.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return the method of this request
* @since 1.0
*/
public RequestMethod getMethod()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getElementState().getMethod();
}
/**
* Returns the name and version of the protocol the request uses in the
* form <i>protocol/majorVersion.minorVersion</i>, for example, HTTP/1.1.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return a <code>String</code> containing the protocol name and version
* number
* @since 1.0
*/
public String getProtocol()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getProtocol();
}
/**
* Returns the Internet Protocol (IP) address of the client or last proxy
* that sent the request.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return a <code>String</code> containing the IP address of the client
* that sent the request
* @since 1.0
*/
public String getRemoteAddr()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getRemoteAddr();
}
/**
* Returns the login of the user making this request, if the user has been
* authenticated, or <code>null</code> if the user has not been
* authenticated. Whether the user name is sent with each subsequent
* request depends on the browser and type of authentication.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return a <code>String</code> specifying the login of the user making
* this request; or
* <p><code>null</code> if the user login is not known
* @since 1.0
*/
public String getRemoteUser()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getRemoteUser();
}
/**
* Returns the fully qualified name of the client or the last proxy that
* sent the request. If the engine cannot or chooses not to resolve the
* hostname (to improve performance), this method returns the
* dotted-string form of the IP address.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return a <code>String</code> containing the fully qualified name of
* the client
* @since 1.0
*/
public String getRemoteHost()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getRemoteHost();
}
/**
* Returns the port number to which the request was sent. It is the value
* of the part after ":" in the <code>Host</code> header value, if any, or
* the server port where the client connection was accepted on.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return an integer specifying the port number
* @since 1.0
*/
public int getServerPort()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getServerPort();
}
/**
* Returns the name of the scheme used to make this request, for example,
* <code>http</code>, <code>https</code>, or <code>ftp</code>. Different
* schemes have different rules for constructing URLs, as noted in RFC
* 1738.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return a <code>String</code> containing the name of the scheme used to
* make this request
* @since 1.0
*/
public String getScheme()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getScheme();
}
/**
* Returns the host name of the server to which the request was sent. It
* is the value of the part before ":" in the <code>Host</code> header
* value, if any, or the resolved server name, or the server IP address.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return a <code>String</code> containing the name of the server
* @since 1.0
*/
public String getServerName()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getServerName();
}
/**
* Returns a boolean indicating whether this request was made using a
* secure channel, such as HTTPS.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have access to the request data (eg. you're inside a child trigger); or
* if there's no active element context (eg. you're using this method
* inside the constructor instead of inside the {@link #initialize()}
* method)
* @return a boolean indicating if the request was made using a secure
* channel
* @since 1.0
*/
public boolean isSecure()
throws EngineException
{
if (!mRequestAccessEnabled) throw new RequestAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().isSecure();
}
/**
* Returns the value of the named attribute as an <code>Object</code>, or
* <code>null</code> if no attribute of the given name exists.
* <p>Attributes can be set two ways. The servlet container may set
* attributes to make available custom information about a request. For
* example, for requests made using HTTPS, the attribute
* <code>javax.servlet.request.X509Certificate</code> can be used to
* retrieve information on the certificate of the client. Attributes can
* also be set programatically using {@link #setRequestAttribute}. This allows
* information to be embedded into a request an communicate amongst
* elements.
* <p>Attribute names should follow the same conventions as package names.
* This specification reserves names matching <code>java.*</code>,
* <code>javax.*</code>, and <code>sun.*</code>.
*
* @param name a <code>String</code> specifying the name of the attribute
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return an <code>Object</code> containing the value of the attribute,
* or <code>null</code> if the attribute does not exist
* @see #hasRequestAttribute
* @see #getRequestAttributeNames
* @see #removeRequestAttribute
* @see #setRequestAttribute
* @since 1.0
*/
public Object getRequestAttribute(String name)
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getRequestAttribute(name);
}
/**
* Checks if a request attribute exists.
*
* @param name a <code>String</code> specifying the name of the attribute
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return <code>true</code> if the attribute exists; or
* <p><code>false</code> otherwise
* @see #getRequestAttribute
* @see #getRequestAttributeNames
* @see #removeRequestAttribute
* @see #setRequestAttribute
* @since 1.0
*/
public boolean hasRequestAttribute(String name)
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().hasRequestAttribute(name);
}
/**
* Returns an <code>Enumeration</code> containing the names of the
* attributes available to this request. This method returns an empty
* <code>Enumeration</code> if the request has no attributes available to
* it.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return an <code>Enumeration</code> of strings containing the names of
* the request's attributes
* @see #getRequestAttribute
* @see #hasRequestAttribute
* @see #removeRequestAttribute
* @see #setRequestAttribute
* @since 1.0
*/
public Enumeration getRequestAttributeNames()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getRequestAttributeNames();
}
/**
* Removes an attribute from this request. This method is not generally
* needed as attributes only persist as long as the request is being
* handled.
* <p>Attribute names should follow the same conventions as package names.
* Names beginning with <code>java.*</code>, <code>javax.*</code>, and
* <code>com.sun.*</code>, are reserved for use by Sun Microsystems.
*
* @param name a <code>String</code> specifying the name of the attribute
* to remove
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getRequestAttribute
* @see #hasRequestAttribute
* @see #getRequestAttributeNames
* @see #setRequestAttribute
* @since 1.0
*/
public void removeRequestAttribute(String name)
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getRequestState().removeRequestAttribute(name);
}
/**
* Stores an attribute in this request. Attributes are reset between
* requests.
* <p>Attribute names should follow the same conventions as package names.
* Names beginning with <code>java.*</code>, <code>javax.*</code>, and
* <code>com.sun.*</code>, are reserved for use by Sun Microsystems. <br>
* If the object passed in is null, the effect is the same as calling
* {@link #removeRequestAttribute}.
*
* @param name a <code>String</code> specifying the name of the attribute
* @param object the <code>Object</code> to be stored
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @see #getRequestAttribute
* @see #hasRequestAttribute
* @see #getRequestAttributeNames
* @see #removeRequestAttribute
* @since 1.0
*/
public void setRequestAttribute(String name, Object object)
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
mElementContext.getRequestState().setRequestAttribute(name, object);
}
/**
* Retrieves the context of this element.
* <p>By default, this method will throw an exception since it gives raw
* access to web engine features that aren't managed. See {@link
* #setProhibitRawAccess} for more information about activating it.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have raw access to the web engine; or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @return the context that belongs to this element instance
* @see ElementContext
* @see #setProhibitRawAccess
* @since 1.0
*/
public ElementContext getElementContext()
throws EngineException
{
if (prohibitRawAccess()) throw new RawAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext;
}
/**
* Returns the current <code>HttpServletRequest</code>.
* <p>By default, this method will throw an exception since it gives raw
* access to web engine features that aren't managed. See {@link
* #setProhibitRawAccess} for more information about activating it.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have raw access to the web engine; or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @return the current <code>HttpServletRequest</code>
* @see #setProhibitRawAccess
* @since 1.0
*/
public HttpServletRequest getHttpServletRequest()
throws EngineException
{
if (prohibitRawAccess()) throw new RawAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getRequest().getHttpServletRequest();
}
/**
* Returns the current <code>HttpServletResponse</code>.
* <p>By default, this method will throw an exception since it gives raw
* access to web engine features that aren't managed. See {@link
* #setProhibitRawAccess} for more information about activating it.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if you don't
* have raw access to the web engine; or if there's no active element
* context (eg. you're using this method inside the constructor instead of
* inside the {@link #initialize()} method)
* @return the current <code>HttpServletResponse</code>
* @see #setProhibitRawAccess
* @since 1.0
*/
public HttpServletResponse getHttpServletResponse()
throws EngineException
{
if (prohibitRawAccess()) throw new RawAccessDeniedException();
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getResponse().getHttpServletResponse();
}
/**
* Returns the <code>ServletContext</code> of this web application.
* <p>By default, this method will throw an exception since it gives raw
* access to web engine features that aren't managed. See {@link
* #setProhibitRawAccess} for more information about activating it.
*
* @exception com.uwyn.rife.engine.exceptions.EngineException if there's
* no active element context (eg. you're using this method inside the
* constructor instead of inside the {@link #initialize()} method)
* @return the <code>ServletContext</code>
* @see #setProhibitRawAccess
* @since 1.0
*/
public ServletContext getServletContext()
throws EngineException
{
if (null == mElementContext) throw new ElementContextMissingException();
return mElementContext.getRequestState().getInitConfig().getServletContext();
}
void setElementAware(ElementAware elementAware)
{
mElementAware = elementAware;
elementAware.noticeElement(this);
}
ElementAware getElementAware()
{
return mElementAware;
}
ElementContext _getElementContext()
{
return mElementContext;
}
public void setElementContext(ElementContext elementContext)
{
mElementContext = elementContext;
}
void setElementInfo(ElementInfo elementInfo)
{
assert elementInfo != null;
mElementInfo = elementInfo;
}
void enableRequestAccess(boolean enabled)
{
mRequestAccessEnabled = enabled;
}
public Object clone()
throws CloneNotSupportedException
{
ElementSupport new_elementsupport = (ElementSupport)super.clone();
new_elementsupport.mElementContext = null;
if (mElementAware != null)
{
// prevent a self-referencing clone
if (this == mElementAware)
{
new_elementsupport.mElementAware = (ElementAware)new_elementsupport;
}
// clone it since the ElementAware instance is not the same as
// the ElementSupport instance
else
{
new_elementsupport.mElementAware = ObjectUtils.genericClone(mElementAware);
if (null == new_elementsupport.mElementAware)
{
throw new CloneNotSupportedException();
}
}
new_elementsupport.mElementAware.noticeElement(new_elementsupport);
}
return new_elementsupport;
}
}
|