You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by bu...@apache.org on 2014/01/18 19:21:06 UTC
svn commit: r894647 [2/9] - in /websites/production/tapestry/content: ./
cache/
Modified: websites/production/tapestry/content/bean-validation.html
==============================================================================
--- websites/production/tapestry/content/bean-validation.html (original)
+++ websites/production/tapestry/content/bean-validation.html Sat Jan 18 18:21:05 2014
@@ -29,6 +29,8 @@
<link href='http://cxf.apache.org/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' />
<script src='http://cxf.apache.org/resources/highlighter/scripts/shCore.js' type='text/javascript'></script>
<script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script>
+ <script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script>
+ <script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushJScript.js' type='text/javascript'></script>
<script type="text/javascript">
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -81,8 +83,7 @@
</div>
<div style="border-right: 20px solid #D8E4F1;border-left: 20px solid #D8E4F1;">
-</div>
-<div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
+<p> </p></div><div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
<h3>Related Articles</h3>
<ul class="content-by-label"><li>
<div>
@@ -103,23 +104,8 @@
</div>
</li></ul>
-</div>
-
-<h1 id="BeanValidation-IntegrateJSR303-BeanValidationAPI">Integrate JSR 303 - Bean Validation API</h1>
-
-<p>Tapestry provides a powerful validation mechanism (see <a shape="rect" href="forms-and-validation.html">Forms and Validation</a>). Among other things this mechanism allows you to annotate your domain model classes with the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html">@Validate</a> annotation. This annotation is problematic if your domain model is used in non-Tapestry applications as well as in Tapestry applications. Your non-Tapestry application becomes dependent on <em>tapestry5-annotations</em> module. To make your domain model independent from Tapestry you can use the <a shape="rect" class="external-link" href="http://jcp.org/en/jsr/detail?id=303" >JSR 303: Bean Validation</a>. This library provides integration between Tapestry and JSR-303.</p>
-
-<h2 id="BeanValidation-Configuration">Configuration</h2>
-
-<p>The Tapestry's JSR 303 - Bean Validation Library is responsible for configuring and bootstrapping the <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html" >Validator</a> for you. In order to use this library you have to choose an implementation of the JSR-303 specification like <a shape="rect" class="external-link" href="https://www.hibernate.org/412.html" >Hibernate Validator 4.x</a>. This library is not specific to any implementation of JSR-303 and will work with any implementation of your choice.</p>
-
-<h3 id="BeanValidation-BootstrapingtheBeanValidator">Bootstraping the Bean Validator</h3>
-
-<p>The <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/BeanValidatorSource.html">BeanValidatorSource</a> service is responsible for bootstrapping the <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html" >Validator</a>. You can contribute a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/BeanValidatorConfigurer.html">BeanValidatorConfigurer</a> to the configuration of this service in order to participate on the configuration of <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html" >Validator</a>.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-@Contribute(BeanValidatorSource.class)
+</div><h1 id="BeanValidation-IntegrateJSR303-BeanValidationAPI">Integrate JSR 303 - Bean Validation API</h1><p>Tapestry provides a powerful validation mechanism (see <a shape="rect" href="forms-and-validation.html">Forms and Validation</a>). Among other things this mechanism allows you to annotate your domain model classes with the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html">@Validate</a> annotation. This annotation is problematic if your domain model is used in non-Tapestry applications as well as in Tapestry applications. Your non-Tapestry application becomes dependent on <em>tapestry5-annotations</em> module. To make your domain model independent from Tapestry you can use the <a shape="rect" class="external-link" href="http://jcp.org/en/jsr/detail?id=303" >JSR 303: Bean Validation</a>. This library provides integration between Tapestry and JSR-303.</p><h2 id="BeanValidation-Configuration">Co
nfiguration</h2><p>The Tapestry's JSR 303 - Bean Validation Library is responsible for configuring and bootstrapping the <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html" >Validator</a> for you. In order to use this library you have to choose an implementation of the JSR-303 specification like <a shape="rect" class="external-link" href="https://www.hibernate.org/412.html" >Hibernate Validator 4.x</a>. This library is not specific to any implementation of JSR-303 and will work with any implementation of your choice.</p><h3 id="BeanValidation-BootstrapingtheBeanValidator">Bootstraping the Bean Validator</h3><p>The <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/BeanValidatorSource.html">BeanValidatorSource</a> service is responsible for bootstrapping the <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/val
idation/Validator.html" >Validator</a>. You can contribute a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/BeanValidatorConfigurer.html">BeanValidatorConfigurer</a> to the configuration of this service in order to participate on the configuration of <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html" >Validator</a>.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@Contribute(BeanValidatorSource.class)
public static void provideBeanValidatorConfigurer(OrderedConfiguration<BeanValidatorConfigurer> configuration)
{
configuration.add("MyConfigurer", new BeanValidatorConfigurer()
@@ -130,21 +116,8 @@ public static void provideBeanValidatorC
}
});
}]]></script>
-</div></div>
-
-<h3 id="BeanValidation-Validationgroups">Validation groups</h3>
-
-<p>In JSR-303 validation groups are used to define a subset of the constraints validated at a given time. If no validation group is specified the <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/groups/Default.html" >Default</a> group is taken. By default, Tapestry passes only this group to <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html" >Validator</a>. You can tell Tapestry to pass more groups by contributing group classes into the configuration of the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/BeanValidatorSource.html">BeanValidatorSource</a> service.</p>
-
-<h2 id="BeanValidation-Usage">Usage</h2>
-
-<h3 id="BeanValidation-ValidatingInputFields">Validating Input Fields</h3>
-
-<p>Once you included this library and its dependencies into your web app, you may use the JSR-303 annotations to validate the user's input.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public class Login
+</div></div><h3 id="BeanValidation-Validationgroups">Validation groups</h3><p>In JSR-303 validation groups are used to define a subset of the constraints validated at a given time. If no validation group is specified the <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/groups/Default.html" >Default</a> group is taken. By default, Tapestry passes only this group to <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html" >Validator</a>. You can tell Tapestry to pass more groups by contributing group classes into the configuration of the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/BeanValidatorSource.html">BeanValidatorSource</a> service.</p><h2 id="BeanValidation-Usage">Usage</h2><h3 id="BeanValidation-ValidatingInputFields">Validating Input Fields</h3><p>Once you included this library and its dep
endencies into your web app, you may use the JSR-303 annotations to validate the user's input.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class Login
{
@NotNull
@Size(max=10)
@@ -162,13 +135,8 @@ public class Login
// Login the user here
}
}]]></script>
-</div></div>
-
-<p>You can even mix JSR-303 annotations and Tapestry's @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html">Validate</a> annotation.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public class Login
+</div></div><p>You can even mix JSR-303 annotations and Tapestry's @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html">Validate</a> annotation.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class Login
{
@NotNull
@Validate("maxlength=10")
@@ -186,13 +154,8 @@ public class Login
// Login the user here
}
}]]></script>
-</div></div>
-
-<p>Next you have to pass the object to validate into the Form's <em>validate</em> parameter. In the following example the Form's fields are bound to the properties of the <em>Login</em> page. That's why we pass <em>this</em>, thus the page instance, to the  <em>validate</em> parameter.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd">
+</div></div><p>Next you have to pass the object to validate into the Form's <em>validate</em> parameter. In the following example the Form's fields are bound to the properties of the <em>Login</em> page. That's why we pass <em>this</em>, thus the page instance, to the  <em>validate</em> parameter.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd">
<body>
<t:form validate="this">
@@ -212,18 +175,8 @@ public class Login
<t:form>
</body>
</html>]]></script>
-</div></div>
-
-<p>Since the <em>validate</em> parameter defaults to the container of the Form component, we could also remove <em>validate="this"</em> in the example above.</p>
-
-<h3 id="BeanValidation-ValidatingBeanswithBeanEditForm">Validating Beans with BeanEditForm</h3>
-
-<p>If you use the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/BeanEditForm.html">BeanEditForm</a> component it's even easier to validate your beans. The only thing you have to do is to annotate your beans with JSR-303 annotations. If you are migrating from Tapestry's built-in validation mechanism to JSR-303 Bean Validation, you don't have to change your template at all.</p>
-
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public class User
+</div></div><p>Since the <em>validate</em> parameter defaults to the container of the Form component, we could also remove <em>validate="this"</em> in the example above.</p><h3 id="BeanValidation-ValidatingBeanswithBeanEditForm">Validating Beans with BeanEditForm</h3><p>If you use the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/BeanEditForm.html">BeanEditForm</a> component it's even easier to validate your beans. The only thing you have to do is to annotate your beans with JSR-303 annotations. If you are migrating from Tapestry's built-in validation mechanism to JSR-303 Bean Validation, you don't have to change your template at all.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class User
{
@NotNull
private String userName;
@@ -234,23 +187,8 @@ public class User
...
}]]></script>
-</div></div>
-
-<h3 id="BeanValidation-Client-sideValidation">Client-side Validation</h3>
-
-<p>Unfortunately JSR-303 doesn’t cover client-side validation, so web frameworks supporting this JSR need to come up with proprietary client-side solutions. Tapestry provides client-side validation for the following JSR-303 constraints:</p>
-
-<div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> JSR-303 constraint </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Tapestry' JavaScript function </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Max.html" >@Max</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Tapestry.Validator.maxnumber </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Min.html" >@Min</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Tapestry.Validator.minnumber </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/const
raints/NotNull.html" >@NotNull</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Tapestry.Validator.notnull </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Null.html" >@Null</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Tapestry.Validator.isnull </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Pattern.html" >@Pattern</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Tapestry.Validator.pattern </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Size.html" >@Size</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Tapestry.V
alidator.size </p></td></tr></tbody></table></div>
-
-
-
-<h3 id="BeanValidation-Providingownclient-sidevalidators">Providing own client-side validators</h3>
-
-<p>Now let's see how to provide own client-side validation for JSR-303 constraints. Imagine you created the following constraint definition. The server-side implementation of the constraint is implemented by RangeValidator. I suppose you are familiar with JSR-303, so I don’t explain how to implement RangeValidator.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-@Documented
+</div></div><h3 id="BeanValidation-Client-sideValidation">Client-side Validation</h3><p>Unfortunately JSR-303 doesn’t cover client-side validation, so web frameworks supporting this JSR need to come up with proprietary client-side solutions. Tapestry provides client-side validation for the following JSR-303 constraints:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>JSR-303 constraint</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Tapestry' JavaScript function</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Max.html" >@Max</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Tapestry.Validator.maxnumber</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6
/api/javax/validation/constraints/Min.html" >@Min</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Tapestry.Validator.minnumber</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/NotNull.html" >@NotNull</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Tapestry.Validator.notnull</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Null.html" >@Null</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Tapestry.Validator.isnull</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Pattern.html" >@Pattern</a></p></td><td colspan="1" rowspan="1" class="confluenceTd">
<p>Tapestry.Validator.pattern</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a shape="rect" class="external-link" href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Size.html" >@Size</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Tapestry.Validator.size</p></td></tr></tbody></table></div><h3 id="BeanValidation-Providingownclient-sidevalidators">Providing own client-side validators</h3><p>Now let's see how to provide own client-side validation for JSR-303 constraints. Imagine you created the following constraint definition. The server-side implementation of the constraint is implemented by RangeValidator. I suppose you are familiar with JSR-303, so I don’t explain how to implement RangeValidator.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@Documented
@Constraint(validatedBy = RangeValidator.class)
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
@@ -265,36 +203,16 @@ public @interface Range {
Class[] payload() default {};
}]]></script>
-</div></div>
-
-<p>To provide client-side validation of a constraint you have to add a JavaScript function to the built-in <em>Tapestry.Validator</em> JavaScript-object. The function should contain exactly three parameters:</p>
-
-<ol><li>Field being validated</li><li>Validation message</li><li>JSON object with values from the constraint annotation</li></ol>
-
-
-<p>Here is an example:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: javascript; gutter: false" type="syntaxhighlighter"><![CDATA[
-Tapestry.Validator.range = function(field, message, spec) {
+</div></div><p>To provide client-side validation of a constraint you have to add a JavaScript function to the built-in <em>Tapestry.Validator</em> JavaScript-object. The function should contain exactly three parameters:</p><ol><li>Field being validated</li><li>Validation message</li><li>JSON object with values from the constraint annotation</li></ol><p>Here is an example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: js; gutter: false" type="syntaxhighlighter"><![CDATA[Tapestry.Validator.range = function(field, message, spec) {
field.addValidator(function(value) {
if (value < spec.min || value > spec.max) {
throw message;
}
});
};]]></script>
-</div></div>
-
-<p>Now you have to tell Tapestry to call the function <em>Tapestry.Validator.range</em> when client-side validation of <em>@Range</em> should be executed. This is accomplished by a contribution to the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/ClientConstraintDescriptorSource.html">ClientConstraintDescriptorSource</a> service. The configuration of this service is a collection of <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/ClientConstraintDescriptor.html">ClientConstraintDescriptor</a>. Each <em>ClientConstraintDescriptor</em> represents a client-side validation constraint. The constructor of <em>ClientConstraintDescriptor</em> has three parameters:</p>
-
-<ol><li>Class of the constraint annotation.</li><li>Name of the JavaScript function.</li><li>The last parameter is a varargs. It is used to pass the attribute names of the constraint annotation to be passed (along with their values) to the JavaScript function as an JSON object.</li></ol>
-
-
-<p>The last step is to make the contribution, which links the <em>@Range</em> annotation with the JavaScript function <em>range</em>. The attributes <em>max</em> and <em>min</em> and their values are passed to the function.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-@Contribute(ClientConstraintDescriptorSource.class)
+</div></div><p>Now you have to tell Tapestry to call the function <em>Tapestry.Validator.range</em> when client-side validation of <em>@Range</em> should be executed. This is accomplished by a contribution to the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/ClientConstraintDescriptorSource.html">ClientConstraintDescriptorSource</a> service. The configuration of this service is a collection of <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/ClientConstraintDescriptor.html">ClientConstraintDescriptor</a>. Each <em>ClientConstraintDescriptor</em> represents a client-side validation constraint. The constructor of <em>ClientConstraintDescriptor</em> has three parameters:</p><ol><li>Class of the constraint annotation.</li><li>Name of the JavaScript function.</li><li>The last parameter is a varargs. It is used to pass the attribute names of
the constraint annotation to be passed (along with their values) to the JavaScript function as an JSON object.</li></ol><p>The last step is to make the contribution, which links the <em>@Range</em> annotation with the JavaScript function <em>range</em>. The attributes <em>max</em> and <em>min</em> and their values are passed to the function.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@Contribute(ClientConstraintDescriptorSource.class)
public static void provideClientConstraintDescriptors(Configuration<ClientConstraintDescriptor> config) {
config.add(new ClientConstraintDescriptor(Range.class, "range", "min", "max"));
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/component-events.html
==============================================================================
--- websites/production/tapestry/content/component-events.html (original)
+++ websites/production/tapestry/content/component-events.html Sat Jan 18 18:21:05 2014
@@ -29,6 +29,7 @@
<link href='http://cxf.apache.org/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' />
<script src='http://cxf.apache.org/resources/highlighter/scripts/shCore.js' type='text/javascript'></script>
<script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script>
+ <script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script>
<script type="text/javascript">
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -69,9 +70,7 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><h1 id="ComponentEvents-ComponentEvents">Component Events</h1>
-
-<div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
+<div id="ConfluenceContent"><h1 id="ComponentEvents-ComponentEvents">Component Events</h1><div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
<h3>Related Articles</h3>
<ul class="content-by-label"><li>
<div>
@@ -114,7 +113,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="component-events.html">Component Events</a>
+ <a shape="rect" href="component-rendering.html">Component Rendering</a>
</div>
@@ -123,58 +122,27 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="component-rendering.html">Component Rendering</a>
+ <a shape="rect" href="component-events.html">Component Events</a>
</div>
</li></ul>
-</div>
-
-<p><strong>Component events</strong> are Tapestry's way of conveying a user's interactions with the web page, such as clicking links and submitting forms, to designated methods in your page and component classes. When a component event occurs, Tapestry calls the event handler method you've provided, if any, in the containing component's class.</p>
-
-<p>Let's review a simple example. Here's a portion of the template for a page (let's call it "Chooser") that lets the user choose a number between 1 and 10:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<p> Choose a number from 1 to 10:
+</div><p><strong>Component events</strong> are Tapestry's way of conveying a user's interactions with the web page, such as clicking links and submitting forms, to designated methods in your page and component classes. When a component event occurs, Tapestry calls the event handler method you've provided, if any, in the containing component's class.</p><p>Let's review a simple example. Here's a portion of the template for a page (let's call it "Chooser") that lets the user choose a number between 1 and 10:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<p> Choose a number from 1 to 10:
<t:count end="10" value="index">
<a t:id="select" t:type="actionlink" context="index">${index}</t:comp>
</t:count>
</p>
]]></script>
-</div></div>
-
-<p>Notice that Chooser.tml contains an ActionLink component. When rendered on the page, the ActionLink component creates a component event request URL, with the event type set to "action". In this case the URL might look like <code><a shape="rect" class="external-link" href="http://localhost:8080/chooser.select/3" >http://localhost:8080/chooser.select/3</a></code></p>
-
-<p>This URL identifies the page that contains the component ("chooser"), the type of event (unless it is "action", the default and most common event type), the id of the component within the page ("select"), plus the additional context value ("3"). <em>Additional context values, if any, are appended to the path.</em></p>
-
-<p>There's no direct mapping from URL to a piece of code. Instead, when the user clicks on the link, the ActionLink component emits events. And then Tapestry ensures that the correct bit of code (your event handler method, see below) gets invoked for those events.</p>
-
-<p>This demonstrates a critical difference between Tapestry and a more traditional, action oriented framework. The URL doesn't say what happens when the link is clicked, it identifies <em>which component is responsible</em> when the link is clicked.</p>
-
-<p>Often, a navigation request (originating with the user) will spawn a number of flow-of-control requests. For example, an action event will trigger a form component, which will then emit notification events to announce when the form submission is about to be processed, and whether it was successful or not, and those event could be further handled by the page component.</p>
-
-<h1 id="ComponentEvents-EventHandlerMethods">Event Handler Methods</h1>
-
-<p>When a component event occurs, Tapestry invokes any event handler methods that you have identified for that event. You can identify your event handler methods via a naming convention (see Method Naming Convention below), or via the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/OnEvent.html">OnEvent</a> annotation.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- @OnEvent(component = "select")
+</div></div><p>Notice that Chooser.tml contains an ActionLink component. When rendered on the page, the ActionLink component creates a component event request URL, with the event type set to "action". In this case the URL might look like <code><a shape="rect" class="external-link" href="http://localhost:8080/chooser.select/3" >http://localhost:8080/chooser.select/3</a></code></p><p>This URL identifies the page that contains the component ("chooser"), the type of event (unless it is "action", the default and most common event type), the id of the component within the page ("select"), plus the additional context value ("3"). <em>Additional context values, if any, are appended to the path.</em></p><p>There's no direct mapping from URL to a piece of code. Instead, when the user clicks on the link, the ActionLink component emits events. And then Tapestry ensures that the correct bit of code (your event handler method, see below) gets invoked for those events.</p><p>This demonstrates a cr
itical difference between Tapestry and a more traditional, action oriented framework. The URL doesn't say what happens when the link is clicked, it identifies <em>which component is responsible</em> when the link is clicked.</p><p>Often, a navigation request (originating with the user) will spawn a number of flow-of-control requests. For example, an action event will trigger a form component, which will then emit notification events to announce when the form submission is about to be processed, and whether it was successful or not, and those event could be further handled by the page component.</p><h1 id="ComponentEvents-EventHandlerMethods">Event Handler Methods</h1><p>When a component event occurs, Tapestry invokes any event handler methods that you have identified for that event. You can identify your event handler methods via a naming convention (see Method Naming Convention below), or via the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidoc
s/org/apache/tapestry5/annotations/OnEvent.html">OnEvent</a> annotation.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @OnEvent(component = "select")
void valueChosen(int value)
{
this.value = value;
}
]]></script>
-</div></div>
-
-<p>Tapestry does two things here:</p>
-
-<ul><li>Because of the annotation, it identifies method valueChosen() as the method to invoke.</li><li>When the link is clicked, it converts the context value from a string to an integer and passes it into the method.</li></ul>
-
-
-
+</div></div><p>Tapestry does two things here:</p><ul><li>Because of the annotation, it identifies method valueChosen() as the method to invoke.</li><li>When the link is clicked, it converts the context value from a string to an integer and passes it into the method.</li></ul>
<div class="aui-message hint shadowed information-macro">
<p class="title">Added in 5.3</p>
@@ -186,148 +154,34 @@
</div>
<div style="border-right: 20px solid #D8E4F1;border-left: 20px solid #D8E4F1;">
-
<p>Starting in release 5.3, Tapestry will validate that the component, if any, identified for the event handler method actually exists in the containing component's template. This helps with typos in annotations (or in the naming conventions identified below).</p>
-</div>
-
-<p>In the above example, the valueChosen() method will be invoked when the default event, "action", occurs in the <code>select</code> component (and has at least one context value).</p>
-
-<p>For some components, more than one type of event can occur, in which case you will want to be more specific:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- @OnEvent(value = "action", component = "select")
+</div><p>In the above example, the valueChosen() method will be invoked when the default event, "action", occurs in the <code>select</code> component (and has at least one context value).</p><p>For some components, more than one type of event can occur, in which case you will want to be more specific:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @OnEvent(value = "action", component = "select")
void valueChosen(int value)
{
this.value = value;
}
]]></script>
-</div></div>
-
-<p>The <code>value</code> attribute of the OnEvent annotation is the name of the event to match. The default event type is "action"; the ActionLink and Form components each use this event type. Alternatively, we could have used an EventLink component, in which case the name of the event is determined by the element's ID, rather than being "action".</p>
-
-<p>If you omit the <code>component</code> part of the OnEvent annotation, then you'll receive notifications from <em>all</em> contained components, possibly including nested components (due to event bubbling).</p>
-
- <div class="aui-message success shadowed information-macro">
+</div></div><p>The <code>value</code> attribute of the OnEvent annotation is the name of the event to match. The default event type is "action"; the ActionLink and Form components each use this event type. Alternatively, we could have used an EventLink component, in which case the name of the event is determined by the element's ID, rather than being "action".</p><p>If you omit the <code>component</code> part of the OnEvent annotation, then you'll receive notifications from <em>all</em> contained components, possibly including nested components (due to event bubbling).</p> <div class="aui-message success shadowed information-macro">
<span class="aui-icon icon-success">Icon</span>
<div class="message-content">
-
-<p>You should usually specify exactly which component(s) you wish to receive events from. Using @OnEvent on a method and not specifying a specific component id means that the method will be invoked for events from <em>any</em> component.</p>
+ <p>You should usually specify exactly which component(s) you wish to receive events from. Using @OnEvent on a method and not specifying a specific component id means that the method will be invoked for events from <em>any</em> component.</p>
</div>
</div>
-
-
-<p>Event handler methods are normally given package-private visibility, to support testing, although technically they may have any visibility (even private).</p>
-
-<p>A single event handler method may receive notifications from many different components.</p>
-
-<p>As elsewhere, the comparison of event type and component id is case-insensitive.</p>
-
-<h2 id="ComponentEvents-MethodNamingConvention">Method Naming Convention</h2>
-
-<p>As an alternative to the use of annotations, you may name your event handling methods following a certain convention, and Tapestry will find and invoke your methods just as if they were annotated.</p>
-
-<p>This style of event handler methods start with the prefix "on", followed by the name of the action. You may then continue by adding "From" and a capitalized component id (remember that Tapestry is case insensitive about event names and component ids). So, for example, a method named onActionFromSelect(), if it exists, is invoked whenever an <code>Action</code> event is emitted by the <code>select</code> component.</p>
-
-<p>The previous example may be rewritten as:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- void onActionFromSelect(int value)
+<p>Event handler methods are normally given package-private visibility, to support testing, although technically they may have any visibility (even private).</p><p>A single event handler method may receive notifications from many different components.</p><p>As elsewhere, the comparison of event type and component id is case-insensitive.</p><h2 id="ComponentEvents-MethodNamingConvention">Method Naming Convention</h2><p>As an alternative to the use of annotations, you may name your event handling methods following a certain convention, and Tapestry will find and invoke your methods just as if they were annotated.</p><p>This style of event handler methods start with the prefix "on", followed by the name of the action. You may then continue by adding "From" and a capitalized component id (remember that Tapestry is case insensitive about event names and component ids). So, for example, a method named onActionFromSelect(), if it exists, is invoked whenever an <code>Action</code> event is
emitted by the <code>select</code> component.</p><p>The previous example may be rewritten as:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ void onActionFromSelect(int value)
{
this.value = value;
}
]]></script>
-</div></div>
-
- <div class="aui-message hint shadowed information-macro">
+</div></div> <div class="aui-message hint shadowed information-macro">
<span class="aui-icon icon-hint">Icon</span>
<div class="message-content">
-
-<p>Note from Howard: I've found that I prefer the naming convention approach, and reserve the annotation just for situations that don't otherwise fit.</p>
+ <p>Note from Howard: I've found that I prefer the naming convention approach, and reserve the annotation just for situations that don't otherwise fit.</p>
</div>
</div>
-
-
-<h2 id="ComponentEvents-MethodReturnValues">Method Return Values</h2>
-
-<p>Main Article: <a shape="rect" href="page-navigation.html">Page Navigation</a></p>
-
-<p>For page navigation events (originating in components such as EventLink, ActionLink and Form), the value returned from an event handler method determines how Tapestry will render a response.</p>
-
-<ul><li><strong>Null</strong>: For no value, or null, the current page (the page containing the component) will render the response.</li><li><strong>Page</strong>: For the name of a page, or a page class or page instance, a render request URL will be constructed and sent to the client as a redirect to that page.</li><li><strong>URL</strong>: For a java.net.URL, a redirect will be sent to the client. (In Tapestry 5.3.x and earlier, this only works for non-Ajax requests.)</li><li><strong>Zone body</strong>: In the case of an Ajax request to update a zone, the component event handler will return the new zone body, typically via an injected component or block.</li><li><strong>HttpError</strong>: For an <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/HttpError.html">HttpError</a>, an error response is sent to the client.</li><li><strong>Link</strong>: For a <a shape="rect" class="external-link" href="http://tapestry.apa
che.org/current/apidocs/org/apache/tapestry5/Link.html">Link</a>, a redirect is sent to the client.</li><li><strong>Stream</strong>: For a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/StreamResponse.html">StreamResponse</a>, a stream of data is sent to the client</li></ul>
-
-
-<p>See <a shape="rect" href="page-navigation.html">Page Navigation</a> for more details.</p>
-
-<h2 id="ComponentEvents-MultipleMethodMatches">Multiple Method Matches</h2>
-
-<p>In some cases, there may be multiple event handler methods matching a single event. In that case, Tapestry invokes them in the following order:</p>
-
-<ul><li>Base class methods before sub-class methods.</li><li>Matching methods within a class in alphabetical order.</li><li>For a single method name with multiple overrides, by number of parameters, descending.</li></ul>
-
-
-<p>Of course, ordinarily would you <em>not</em> want to create more than one method to handle an event.</p>
-
-<p>When a sub-class overrides an event handler method of a base class, the event handler method is only invoked once, along with any other base class methods. The subclass can change the <em>implementation</em> of the base class method via an override, but can't change the <em>timing</em> of when that method is invoked. See <a shape="rect" class="external-link" href="https://issues.apache.org/jira/browse/TAP5-51">issue TAP5-51</a>.</p>
-
-<h1 id="ComponentEvents-EventContext">Event Context</h1>
-
-<p>The context values (the context parameter to the EventLink or ActionLink component) can be any object. However, only a simple conversion to string occurs. (This is in contrast to Tapestry 4, which had an elaborate type mechanism with the odd name "DataSqueezer".)</p>
-
-<p>Again, whatever your value is (string, number, date), it is converted into a plain string. This results in a more readable URL.</p>
-
-<p>If you have multiple context values (by binding a list or array of objects to the <em>context</em> parameter of the EventLink or ActionLink), then each one, in order, will be added to the URL.</p>
-
-<p>When an event handler method is invoked, the strings are converted back into values, or even objects. A <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ValueEncoder.html">ValueEncoder</a> is used to convert between client-side strings and server-side objects. The <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ValueEncoderSource.html">ValueEncoderSource</a> service provides the necessary value encoders.</p>
-
-<p>As shown in the example above, most of the parameters passed to the event handler method are derived from the values provided in the event context. Each successive method parameter matches against a value provided in the event context (the context parameter of the ActionLink component; though many components have a similar context parameter).</p>
-
-<p>In some cases, it is desirable to have direct access to the context (for example, to adapt to cases where there are a variable number of context values). The context values may be passed to an event handler method as parameter of the following types:</p>
-
-<ul><li><a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/EventContext.html">EventContext</a></li><li>Object[]</li><li>List<Object></li></ul>
-
-
-<p>The latter two should be avoided, they may be removed in a future release. In all of these cases, the context parameter acts as a freebie; it doesn't match against a context value as it represents <em>all</em> context values.</p>
-
-<h2 id="ComponentEvents-AccessingRequestQueryParameters">Accessing Request Query Parameters</h2>
-
-<p>A parameter may be annotated with the @RequestParameter annotation; this allows a query parameter to be extracted from the request, converted to the correct type, and passed to the method. Again, this doesn't count against the event context values.</p>
-
-
-<h2 id="ComponentEvents-MethodMatching">Method Matching</h2>
-
-<p>An event handler method will only be invoked <em>if the context contains at least as many values as the method has parameters</em>. Methods with too many parameters will be silently skipped.</p>
-
-<p>Tapestry will silently skip over a method if there are insufficient values in the context to satisfy the number of parameters requested.</p>
-
-<p>EventContext parameters, and parameters annotated with @RequestParameter, do not count against this limit.</p>
-
-<h2 id="ComponentEvents-MethodOrdering">Method Ordering</h2>
-
-<p>When multiple methods match within the same class, Tapestry will invoke them in ascending alphabetical order. When there are multiple overrides of the same method name, Tapestry invokes them in descending order by number of parameters. In general, these situations don't happen ... in most cases, only a single method is required to handle a specific event form a specific component.</p>
-
-<p>An event handler method may return the value <code>true</code> to indicate that the event has been handled; this immediately stops the search for additional methods in the same class (or in base classes) or in containing components.</p>
-
-<h1 id="ComponentEvents-EventBubbling">Event Bubbling</h1>
-
-<p>The event will bubble up the hierarchy, until it is aborted. The event is aborted when an event handler method returns a non-null value.</p>
-
-<p>Returning a boolean value from an event handler method is special. Returning true will abort the event with no result; use this when the event is fully handled without a return value and no further event handlers (in the same component, or in containing components) should be invoked.</p>
-
-<p>Returning false is the same as returning null; event processing will continue to look for more event handlers, in the same component or its parent.</p>
-
-<p>When an event bubbles up from a component to its container, the origin of the event is changed to be the component. For example, a Form component inside a BeanEditForm component may fire a success event. The page containing the BeanEditForm may listen for that event, but it will be from the BeanEditForm component (which makes sense, because the id of the Form inside the BeanEditForm is part of the BeanEditForm's implementation, not its public interface).</p>
-
-<h1 id="ComponentEvents-EventMethodExceptions">Event Method Exceptions</h1>
-
-<p>Event methods are allowed to throw any exception (not just runtime exceptions). If an event method does throw an exception, Tapestry will catch the thrown exception and ultimately display the exception report page.</p>
-
-<p>In other words, there's no need to do this:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- void onActionFromRunQuery()
+<h2 id="ComponentEvents-MethodReturnValues">Method Return Values</h2><p>Main Article: <a shape="rect" href="page-navigation.html">Page Navigation</a></p><p>For page navigation events (originating in components such as EventLink, ActionLink and Form), the value returned from an event handler method determines how Tapestry will render a response.</p><ul><li><strong>Null</strong>: For no value, or null, the current page (the page containing the component) will render the response.</li><li><strong>Page</strong>: For the name of a page, or a page class or page instance, a render request URL will be constructed and sent to the client as a redirect to that page.</li><li><strong>URL</strong>: For a java.net.URL, a redirect will be sent to the client. (In Tapestry 5.3.x and earlier, this only works for non-Ajax requests.)</li><li><strong>Zone body</strong>: In the case of an Ajax request to update a zone, the component event handler will return the new zone body, typically via an injected co
mponent or block.</li><li><strong>HttpError</strong>: For an <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/HttpError.html">HttpError</a>, an error response is sent to the client.</li><li><strong>Link</strong>: For a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Link.html">Link</a>, a redirect is sent to the client.</li><li><strong>Stream</strong>: For a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/StreamResponse.html">StreamResponse</a>, a stream of data is sent to the client</li></ul><p>See <a shape="rect" href="page-navigation.html">Page Navigation</a> for more details.</p><h2 id="ComponentEvents-MultipleMethodMatches">Multiple Method Matches</h2><p>In some cases, there may be multiple event handler methods matching a single event. In that case, Tapestry invokes them in the following orde
r:</p><ul><li>Base class methods before sub-class methods.</li><li>Matching methods within a class in alphabetical order.</li><li>For a single method name with multiple overrides, by number of parameters, descending.</li></ul><p>Of course, ordinarily would you <em>not</em> want to create more than one method to handle an event.</p><p>When a sub-class overrides an event handler method of a base class, the event handler method is only invoked once, along with any other base class methods. The subclass can change the <em>implementation</em> of the base class method via an override, but can't change the <em>timing</em> of when that method is invoked. See <a shape="rect" class="external-link" href="https://issues.apache.org/jira/browse/TAP5-51">issue TAP5-51</a>.</p><h1 id="ComponentEvents-EventContext">Event Context</h1><p>The context values (the context parameter to the EventLink or ActionLink component) can be any object. However, only a simple conversion to string occurs. (This is in
contrast to Tapestry 4, which had an elaborate type mechanism with the odd name "DataSqueezer".)</p><p>Again, whatever your value is (string, number, date), it is converted into a plain string. This results in a more readable URL.</p><p>If you have multiple context values (by binding a list or array of objects to the <em>context</em> parameter of the EventLink or ActionLink), then each one, in order, will be added to the URL.</p><p>When an event handler method is invoked, the strings are converted back into values, or even objects. A <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ValueEncoder.html">ValueEncoder</a> is used to convert between client-side strings and server-side objects. The <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ValueEncoderSource.html">ValueEncoderSource</a> service provides the necessary value encoders.</p><p>As shown in the ex
ample above, most of the parameters passed to the event handler method are derived from the values provided in the event context. Each successive method parameter matches against a value provided in the event context (the context parameter of the ActionLink component; though many components have a similar context parameter).</p><p>In some cases, it is desirable to have direct access to the context (for example, to adapt to cases where there are a variable number of context values). The context values may be passed to an event handler method as parameter of the following types:</p><ul><li><a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/EventContext.html">EventContext</a></li><li>Object[]</li><li>List<Object></li></ul><p>The latter two should be avoided, they may be removed in a future release. In all of these cases, the context parameter acts as a freebie; it doesn't match against a context value as it represents <em>a
ll</em> context values.</p><h2 id="ComponentEvents-AccessingRequestQueryParameters">Accessing Request Query Parameters</h2><p>A parameter may be annotated with the @RequestParameter annotation; this allows a query parameter to be extracted from the request, converted to the correct type, and passed to the method. Again, this doesn't count against the event context values.</p><h2 id="ComponentEvents-MethodMatching">Method Matching</h2><p>An event handler method will only be invoked <em>if the context contains at least as many values as the method has parameters</em>. Methods with too many parameters will be silently skipped.</p><p>Tapestry will silently skip over a method if there are insufficient values in the context to satisfy the number of parameters requested.</p><p>EventContext parameters, and parameters annotated with @RequestParameter, do not count against this limit.</p><h2 id="ComponentEvents-MethodOrdering">Method Ordering</h2><p>When multiple methods match within the same
class, Tapestry will invoke them in ascending alphabetical order. When there are multiple overrides of the same method name, Tapestry invokes them in descending order by number of parameters. In general, these situations don't happen ... in most cases, only a single method is required to handle a specific event form a specific component.</p><p>An event handler method may return the value <code>true</code> to indicate that the event has been handled; this immediately stops the search for additional methods in the same class (or in base classes) or in containing components.</p><h1 id="ComponentEvents-EventBubbling">Event Bubbling</h1><p>The event will bubble up the hierarchy, until it is aborted. The event is aborted when an event handler method returns a non-null value.</p><p>Returning a boolean value from an event handler method is special. Returning true will abort the event with no result; use this when the event is fully handled without a return value and no further event handle
rs (in the same component, or in containing components) should be invoked.</p><p>Returning false is the same as returning null; event processing will continue to look for more event handlers, in the same component or its parent.</p><p>When an event bubbles up from a component to its container, the origin of the event is changed to be the component. For example, a Form component inside a BeanEditForm component may fire a success event. The page containing the BeanEditForm may listen for that event, but it will be from the BeanEditForm component (which makes sense, because the id of the Form inside the BeanEditForm is part of the BeanEditForm's implementation, not its public interface).</p><h1 id="ComponentEvents-EventMethodExceptions">Event Method Exceptions</h1><p>Event methods are allowed to throw any exception (not just runtime exceptions). If an event method does throw an exception, Tapestry will catch the thrown exception and ultimately display the exception report page.</p><p>I
n other words, there's no need to do this:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ void onActionFromRunQuery()
{
try
{
@@ -339,47 +193,21 @@
}
}
]]></script>
-</div></div>
-
-<p>Instead, you may simply say:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- void onActionFromRunQuery() throws JDBCException
+</div></div><p>Instead, you may simply say:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ void onActionFromRunQuery() throws JDBCException
{
dao.executeQuery();
}
]]></script>
-</div></div>
-
-<p>Your event handler method may even declare that it "throws Exception" if that is more convenient.</p>
-
-<h1 id="ComponentEvents-InterceptingEventExceptions">Intercepting Event Exceptions</h1>
-
-<p>When an event handler method throws an exception (checked or runtime), Tapestry gives the component and its containing page a chance to handle the exception, before continuing on to report the exception.</p>
-
-<p>Tapestry emits a new event, of type "exception", passing the thrown exception as the context. In fact, the exception is wrapped inside a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/runtime/ComponentEventException.html">ComponentEventException</a>, from which you may extract the event type and context.</p>
-
-<p>Thus:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- Object onException(Throwable cause)
+</div></div><p>Your event handler method may even declare that it "throws Exception" if that is more convenient.</p><h1 id="ComponentEvents-InterceptingEventExceptions">Intercepting Event Exceptions</h1><p>When an event handler method throws an exception (checked or runtime), Tapestry gives the component and its containing page a chance to handle the exception, before continuing on to report the exception.</p><p>Tapestry emits a new event, of type "exception", passing the thrown exception as the context. In fact, the exception is wrapped inside a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/runtime/ComponentEventException.html">ComponentEventException</a>, from which you may extract the event type and context.</p><p>Thus:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ Object onException(Throwable cause)
{
message = cause.getMessage();
return this;
}
]]></script>
-</div></div>
-
-<p>The return value of the exception event handler <em>replaces</em> the return value of original event handler method. For the typical case (an exception thrown by an "activate" or "action" event), this will be a <a shape="rect" href="page-navigation.html">navigational response</a> such as a page instance or page name.</p>
-
-<p>This can be handy for handling cases where the data in the URL is incorrectly formatted.</p>
-
-<p>In the above example, the navigational response is the page itself.</p>
-
-<p>If there is no exception event handler, or the exception event handler returns null (or is void), then the exception will be passed to the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/RequestExceptionHandler.html">RequestExceptionHandler</a> service, which (in the default configuration) will render the exception page.</p></div>
+</div></div><p>The return value of the exception event handler <em>replaces</em> the return value of original event handler method. For the typical case (an exception thrown by an "activate" or "action" event), this will be a <a shape="rect" href="page-navigation.html">navigational response</a> such as a page instance or page name.</p><p>This can be handy for handling cases where the data in the URL is incorrectly formatted.</p><p>In the above example, the navigational response is the page itself.</p><p>If there is no exception event handler, or the exception event handler returns null (or is void), then the exception will be passed to the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/RequestExceptionHandler.html">RequestExceptionHandler</a> service, which (in the default configuration) will render the exception page.</p></div>
</div>
<div class="clearer"></div>