Java Doc for ElementSupport.java in  » Web-Framework » rife-1.6.1 » com » uwyn » rife » engine » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The ElementSupport 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 Also:   ElementAware
since:
   1.0

The default implementation executes the ElementChildTrigger that has been registered with ElementSupport.setChildTrigger .
Parameters:
  name - the name of the variable that initiated the child trigger
Parameters:
  values - the values of the variable that initiated the childtrigger true if the execution should be interrupted andstep down the inheritance stack (ie.

If no text buffer is active, this method doesn't do anything.
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if you don'thave access to the request data (eg.

Instead of using the ElementSupport.setCloneContinuations(boolean) method, one can also overload this method to configure the cloning.

false otherwise
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if you don'thave access to the request data (eg.

If RIFE is being run as a filter, it will execute the next filter in the chain.

If RIFE is being run as a servlet, the status code 404: Not Found will be sent to the client.
exception:
  com.uwyn.rife.engine.exceptions.EngineException - a runtimeexception that is used to immediately interrupt the execution, don'tcatch 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.

The ElementSupport.print(Template) method automatically evaluates all role user expression tags.

This immediately breaks out of the element and notifies the engine that the next step of the flow must be looked up and executed.
Parameters:
  name - the name of the exit
exception:
  com.uwyn.rife.engine.exceptions.EngineException - a runtimeexception that is used to immediately interrupt the execution, don'tcatch this exception; or there's no active element context (eg.

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 erroroccurs during the output of the content; or if you don't have access tothe request data (eg.

The response of the forwarded request will be sent the to original client, as if the request was sent directly to the forwarded URL.
Parameters:
  url - the URL to which the request will be forwarded
exception:
  com.uwyn.rife.engine.exceptions.EngineException - a runtimeexception that is used to immediately interrupt the execution, don'tcatch 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.

An 'empty' 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.

This method delegates all logic to the com.uwyn.rife.site.FormBuilder.generateForm(TemplateClassMapString) method of the provided template instance.
Parameters:
  template - the template instance where the generation shouldhappen
Parameters:
  beanClass - the class of the bean that should be used to generatethe form
Parameters:
  prefix - the prefix that will be prepended to all bean propertynames
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if errorsoccurred during the introspection of the bean; or if there's no activeelement context (eg.

This method delegates all logic to the com.uwyn.rife.site.FormBuilder.generateForm(TemplateObjectMapString) method of the provided template instance.
Parameters:
  template - the template instance where the generation shouldhappen
Parameters:
  beanInstance - the instance of the bean that should be used togenerate the form
Parameters:
  prefix - the prefix that will be prepended to all bean propertynames
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if errorsoccurred during the introspection of the bean instance; or if there'sno active element context (eg.

null if no deployment class has been declared
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if theelement information hasn't been provided yet (eg.

By default, this method will throw an exception since it gives raw access to web engine features that aren't managed.

null if no data was provided or if the current element isnot embedded
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if there'sno active element context (eg.

null if this embedded element didn't have a differentiator
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if there'sno active element context (eg.

The content of the embed value will be parsed as a property list according to the format described in java.util.Properties.load(java.io.InputStream) .

For instance:

<!--V 'ELEMENT:my.element'-->
 key1 = value1
 key2 = value1
 <!--/V-->

Will return a property list where the key 'key1' is associated to 'value1' and 'key2' to 'value2'. the embed value parsed as a property list; or

null if no default value was provided, if the current element is notembedded
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if there'sno active element context (eg.

For example:

<!--V 'ELEMENT:my.element'-->this is the embed value<!--/V-->

Will return:

this is the embed value

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.

null if this element is not embedded
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if there'sno active element context (eg.

null if this element is not embedded
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if there'sno active element context (eg.

This will take the current element context into account with the available outputs, global variables, ...

This will take the current element context into account with the available outputs, global variables, ...

This will take the current element context into account with the available outputs, global variables, ...

Some servlet containers do not allow servlets to access headers using this method, in which case this method returns null
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if you don'thave access to the request data (eg.

Some headers, such as Accept-Language can be sent by clients as several headers each with a different value rather than sending the header as a comma separated list.

If the request did not include any headers of the specified name, this method returns an empty Enumeration.

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 anerror occurred during the retrieval, parsing or compilation of thetemplate
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if an erroroccurs during the initialization of the template in the elementcontext; or if you don't have access to the request data (eg.

The special engine template types contain additional block and value filters to offer the following features:

• embedded elements
  (eg.: <!--V 'ELEMENT:my.elementid'/-->)
• role user context for scripted block assignment to values
  (eg.: <!--V 'OGNL:ROLEUSER:rolecheck'-->User is not in role "admin"<!--/V-->
<!--B 'OGNL:ROLEUSER:rolecheck:[[ isInRole("admin") ]]'-->User is in role "admin"<!--/B-->)

Non-engine versions of the same template types are not able to provide these functionalities.
Parameters:
  name - the name of the template.

By default, this method will throw an exception since it gives raw access to web engine features that aren't managed.

By default, this method will throw an exception since it gives raw access to web engine features that aren't managed.

This bean is not serialized or de-serialized, each property corresponds to an input and is individually sent by the client.
Parameters:
  beanClass - the class of the input bean
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if an erroroccurred during the instantiation of the bean; or if you don't haveaccess to the request data (eg.

This bean is not serialized or de-serialized, each property corresponds to an input and is individually sent by the client.
Parameters:
  beanClass - the class of the input bean
Parameters:
  prefix - the prefix that will be put in front of each propertyname
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if an erroroccurred during the instantiation of the bean; or if you don't haveaccess to the request data (eg.

Note that the text output is written to the same output stream.

Note that there are two types of properties, fixed value properties ( com.uwyn.rife.ioc.PropertyValueObject string literals ) and dynamic value properties ( com.uwyn.rife.ioc.PropertyValueParticipant participant objects , com.uwyn.rife.ioc.PropertyValueTemplate template instances , ...).

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.
Parameters:
  name - the name of the property
Parameters:
  type - the class you want the property to be converted to
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if theelement information hasn't been provided yet (eg.

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.
Parameters:
  name - the name of the property
Parameters:
  type - the class you want the property to be converted to
Parameters:
  defaultValue - the object that should be used if theproperty can't be found
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if theelement information hasn't been provided yet (eg.

Attributes can be set two ways.

This includes the protocol, the server name and the server port, for example: http://www.somehost.com:8080.
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if you don'thave access to the request data (eg.

By default, this method will throw an exception since it gives raw access to web engine features that aren't managed.

This bean is not serialized or de-serialized, each property corresponds to a parameter and is individually sent by the client.
Parameters:
  beanClass - the class of the submission bean
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if an erroroccurred during the instantiation or the population of the bean; or ifyou don't have access to the request data (eg.

This bean is not serialized or de-serialized, each property corresponds to a parameter and is individually sent by the client.
Parameters:
  beanClass - the class of the submission bean
Parameters:
  prefix - the prefix that will be put in front of each propertyname
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if an erroroccurred during the instantiation or the population of the bean; or ifyou don't have access to the request data (eg.

This bean is not serialized or de-serialized, each property corresponds to a parameter and is individually sent by the client.
Parameters:
  submissionName - the name of the submission
Parameters:
  beanClass - the class of the submission bean
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if an erroroccurred during the instantiation or the population of the bean; or ifyou don't have access to the request data (eg.

This bean is not serialized or de-serialized, each property corresponds to a parameter and is individually sent by the client.
Parameters:
  submissionName - the name of the submission
Parameters:
  beanClass - the class of the submission bean
Parameters:
  prefix - the prefix that will be put in front of each propertyname
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if an erroroccurred during the instantiation or the population of the bean; or ifyou don't have access to the request data (eg.

This will take the current element context into account with the available inputs, global variables, ...

This will take the current element context into account with the available inputs, global variables, ...

This will take the current element context into account with the available inputs, global variables, ...

This will take the current element context into account with the available inputs, global variables, ...

This can be different from the current element due to precedence, behavioural inheritance, child triggers, element embedding, ... the request's target element information
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if there'sno active element context (eg.

The special engine template types contain additional block and value filters to offer the following features:

• embedded elements
  (eg.: [!V 'ELEMENT:my.elementid'/])
• role user context for scripted block assignment to values
  (eg.: [!V 'OGNL:ROLEUSER:rolecheck']User is not in role "admin"[!/V]
[!B 'OGNL:ROLEUSER:rolecheck:[[ isInRole("admin") ]]']User is in role "admin"[!/B])

Non-engine versions of the same template types are not able to provide these functionalities.
Parameters:
  name - the name of the template.

This includes the protocol, the server name, the server port and the URL of RIFE's gateway, for example: http://www.somehost.com:8080/my/webapp/.
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if you don'thave access to the request data (eg.

The special engine template types contain additional block and value filters to offer the following features:

• embedded elements
  (eg.: <!--V 'ELEMENT:my.elementid'/-->)
• role user context for scripted block assignment to values
  (eg.: <!--V 'OGNL:ROLEUSER:rolecheck'-->User is not in role "admin"<!--/V-->
<!--B 'OGNL:ROLEUSER:rolecheck:[[ isInRole("admin") ]]'-->User is in role "admin"<!--/B-->)

Non-engine versions of the same template types are not able to provide these functionalities.
Parameters:
  name - the name of the template.

The special engine template types contain additional block and value filters to offer the following features:

• embedded elements
  (eg.: <!--V 'ELEMENT:my.elementid'/-->)
• role user context for scripted block assignment to values
  (eg.: <!--V 'OGNL:ROLEUSER:rolecheck'-->User is not in role "admin"<!--/V-->
<!--B 'OGNL:ROLEUSER:rolecheck:[[ isInRole("admin") ]]'-->User is in role "admin"<!--/B-->)

Non-engine versions of the same template types are not able to provide these functionalities.
Parameters:
  name - the name of the template.

false otherwise
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if there'sno active element context (eg.

false otherwise
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if there'sno active element context (eg.

false otherwise
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if there'sno active element context (eg.

false if it is disabled
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if you don'thave access to the request data (eg.

Embedded elements are evaluated when value identifiers have the following syntax: ELEMENT:elementId.

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.
Parameters:
  template - the template that will be used to process the embeddedtemplate
Parameters:
  elementId - the identifier of the element
exception:
  com.uwyn.rife.template.exceptions.TemplateException - when anerror occurs during the template processing
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if noelement is known with that identifier; or if you don't have access tothe request data (eg.

See ElementSupport.processEmbeddedElement(Template,String) for more information.
Parameters:
  template - the template that will be used to process the embeddedtemplate
Parameters:
  elementId - the identifier of the element
Parameters:
  data - the data that will be available from within the embeddedelement
exception:
  com.uwyn.rife.template.exceptions.TemplateException - when anerror occurs during the template processing
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if noelement is known with that identifier; or if you don't have access tothe request data (eg.

Embedded elements are evaluated when value identifiers have the following syntax: ELEMENT:elementId:differentiator.

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.
Parameters:
  template - the template that will be used to process the embeddedtemplate
Parameters:
  elementId - the identifier of the element
Parameters:
  differentiator - the differentiator that will be used; ornull if no differentiator should be used
exception:
  com.uwyn.rife.template.exceptions.TemplateException - when anerror occurs during the template processing
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if noelement is known with that identifier; or if you don't have access tothe request data (eg.

See ElementSupport.processEmbeddedElement(Template,String,String) for more information.
Parameters:
  template - the template that will be used to process the embeddedtemplate
Parameters:
  elementId - the identifier of the element
Parameters:
  differentiator - the differentiator that will be used; or
Parameters:
  data - the data that will be available from within the embeddedelementnull if no differentiator should be used
exception:
  com.uwyn.rife.template.exceptions.TemplateException - when anerror occurs during the template processing
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if noelement is known with that identifier; or if you don't have access tothe request data (eg.

This performs the following value replacements if they haven't already been set.

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).

Instead of using the ElementSupport.setProhibitRawAccess(boolean) method, one can also overload this method to allow raw access.

This method delegates all logic to the com.uwyn.rife.site.FormBuilder.removeForm(TemplateClassString) method of the provided template instance.
Parameters:
  template - the template instance where the form should be removedfrom
Parameters:
  beanClass - the class of the bean that should be used to removethe form
Parameters:
  prefix - the prefix that will be prepended to all bean propertynames
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if errorsoccurred during the introspection of the bean; or if there's no activeelement context (eg.

The actual logic is performed by the ElementSupport.selectParameter(Template,String,String[]) method.

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.

The actual logic is performed by the ElementSupport.selectParameter(Template,String,String[]) method.

This is simply a convenience method that calls #selectSubmissionParameter(Template, String, String[]) with a single value string array.
Parameters:
  template - the template instance where the selection should happen
Parameters:
  name - the name of the parameter
Parameters:
  value - the value that should selected or checked
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if there'sno active element context (eg.

If the response has already been committed, this method throws an IllegalStateException.

By default, the active continuation is cloned when a new step needs to be created.

Cookies are handles outside of the web engine's data flow management.

An instance of this class will be created when the element is deployed within a site.

The URL will be generated by calling the ElementSupport.getExitFormUrl(String,String) and ElementSupport.getExitFormParameters(String,String[]) methods and it will be set the results to the value identifiers with the syntax EXIT:FORM:exitname and EXIT:PARAMS:exitname.

Template content that is outputted with the #print(Template) method will automatically be scanned for value identifiers with this syntax and the exit forms URLs and parameters will generated.

The URL will be generated by calling the ElementSupport.getExitQueryUrl(String,String,String[]) method and it will be set to the value identifier with the syntax EXIT:QUERY:exitname.

Template content that is outputted with the #print(Template) method will automatically be scanned for value identifiers with this syntax and the exit query URLs will generated.

This bean is not serialized or deserialized, each output corresponds to a property and is individually sent to the client.
Parameters:
  bean - the bean instance that should be used to set the outputs
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if you don'thave access to the request data (eg.

This bean is not serialized or deserialized, each output corresponds to a property and is individually sent to the client.
Parameters:
  bean - the bean instance that should be used to set the outputs
Parameters:
  prefix - the prefix that will be put in front of each propertyname
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if you don'thave access to the request data (eg.

By default, RIFE shields you away from raw access to the servlet API and controls all incoming and outgoing data.

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).

The identifiers of the values that will be filled in should have the following syntax:

PARAM:propertyName

The identifiers of the values that will be filled in should have the following syntax:

PARAM:propertyName

false otherwise
exception:
  com.uwyn.rife.template.exceptions.TemplateException - whenerrors occurred during the introspection of the bean instance
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if there'sno active element context (eg.

The URL will be generated by calling the ElementSupport.getSubmissionFormUrl(String) and ElementSupport.getSubmissionFormParameters(String,String[]) methods and it will be set the results to the value identifiers with the syntax SUBMISSION:FORM:submissionname and SUBMISSION:PARAMS:submissionname.

Template content that is outputted with the #print(Template) method will automatically be scanned for value identifiers with this syntax and the submission forms URLs and parameters will generated.

The URL will be generated by calling the ElementSupport.getSubmissionQueryUrl(String,String,String[]) method and it will be set to the value identifier with the syntax SUBMISSION:QUERY:submissionname.

Template content that is outputted with the #print(Template) method will automatically be scanned for value identifiers with this syntax and the submission query URLs will generated.

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 runtimeexception that is used to immediately interrupt the execution, don'tcatch this exception
See Also:   ElementSupport.call(String)
See Also:   ElementSupport.answer(Object)
since:
   1.0

The execution in the active element will be interrupted immediately and the call continuation will be resumed exactly where is was paused before.
Parameters:
  answer - the object that will be answered to the calling element
exception:
  com.uwyn.rife.engine.exceptions.EngineException - a runtimeexception that is used to immediately interrupt the execution, don'tcatch this exception
See Also:   ElementSupport.call(String)
See Also:   ElementSupport.answer()
since:
   1.0

As soon as the called element returns or executes ElementSupport.answer() , the execution will resume in the calling element with a completely restored call stack and variable stack.
Parameters:
  exit - the name of the exit whose target element will be called the object that was provided through the ElementSupport.answer(Object)method in the called element; or

null if no answer was provided
See Also:   ElementSupport.answer()
See Also:   ElementSupport.answer(Object)
since:
   1.0

The default implementation executes the ElementChildTrigger that has been registered with ElementSupport.setChildTrigger .
Parameters:
  name - the name of the variable that initiated the child trigger
Parameters:
  values - the values of the variable that initiated the childtrigger true if the execution should be interrupted andstep down the inheritance stack (ie. when the activation of the childhas been triggered); or

false if the execution should just continue
See Also:   ElementSupport.setChildTrigger(ElementChildTrigger)
since:
   1.0

If no text buffer is active, this method doesn't do anything.
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if you don'thave access to the request data (eg. you're inside a child trigger); orif there's no active element context (eg. you're using this methodinside the constructor instead of inside the ElementSupport.initialize()method)
See Also:   ElementSupport.isTextBufferEnabled()
See Also:   ElementSupport.enableTextBuffer(boolean)
See Also:   ElementSupport.flush()
since:
   1.0

Instead of using the ElementSupport.setCloneContinuations(boolean) method, one can also overload this method to configure the cloning. By default, cloning is active. true to make the engine clone continuations; or

false to disable the cloning
See Also:   ElementSupport.setCloneContinuations(boolean)
since:
   1.0

false otherwise
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if you don'thave access to the request data (eg. you're inside a child trigger); orif there's no active element context (eg. you're using this methodinside the constructor instead of inside the ElementSupport.initialize()method)
since:
   1.0

If RIFE is being run as a filter, it will execute the next filter in the chain.

If RIFE is being run as a servlet, the status code 404: Not Found will be sent to the client.
exception:
  com.uwyn.rife.engine.exceptions.EngineException - a runtimeexception that is used to immediately interrupt the execution, don'tcatch 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 insidethe ElementSupport.initialize() method)
since:
   1.0

false otherwise
See Also:   ElementSupport.stepBack
since:
   1.5

Disabling an enabled text buffer, flushes the already buffered content first.

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.

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.
Parameters:
  enabled - true to enable the text buffer; or

false to disable it
exception:
  com.uwyn.rife.engine.exceptions.EngineException - if an erroroccurred during the modification of the text buffer presence; or if youdon't have access to the request data (eg. you're inside a childtrigger); or if there's no active element context (eg. you're usingthis method inside the constructor instead of inside the ElementSupport.initialize() method)
See Also:   ElementSupport.isTextBufferEnabled()
See Also:   ElementSupport.flush()
See Also:   ElementSupport.clearBuffer()
since:
   1.0

The ElementSupport.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.

This block and value expression tag is evaluated through a method that's not part of the com.uwyn.rife.template.Template class since it only makes sense in an element context where a users can be identified.

The value tags have the following syntax LANGUAGE:ROLEUSER:identifier and the block tags have the following syntax LANGUAGE:ROLEUSER:identifier:[[ boolean_expression ]].

Below is an example of roleuser expression tags in use:

<!--V 'OGNL:ROLEUSER:role1'-->User is not in role "admin"<!--/V-->
 <!--B 'OGNL:ROLEUSER:role1:[[ isInRole("admin") ]]'-->User is in role "admin"<!--/B-->

This immediately breaks out of the element and notifies the engine that the next step of the flow must be looked up and executed.
Parameters:
  name - the name of the exit
exception:
  com.uwyn.rife.engine.exceptions.EngineException - a runtimeexception that is used to immediately interrupt the execution, don'tcatch this exception; or there's no active element context (eg. you'reusing this method inside the constructor instead of inside the ElementSupport.initialize() method)
since:
   1.0