tutorials/composites/src/main/java/org/apache/zest/tutorials/composites/tutorial5/package.html - polygene-java - Git at Google

 <!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 -->
 <body>
 <h1>Tutorial 5 - Constraints</h1>
 <p>
 In this tutorial we will look at how to use Constraints. When we pass parameters to
 methods in regular Java code the only restriction we can make is to denote a type.
 Any other constraints on the input value, such as whether the parameter is optional, integer ranges,
 string regular expressions, and so on, cannot be expressed, and so we have to put this into Javadoc, and
 then manually add these checks in the implementation class.
 </p>
 <p>
 In Zest™ there is the option to use Constraints, which are further restrictions on the parameters.
 This is implemented by having an annotation that describes what the Constraint does, and then
 an implementation class that checks whether a specific value fulfills the Constraint or not.
 </p>
 <p>
 There are a number of pre-written constraints in Zest™ which you can use. The null check of the original
 HelloWorld version is already handled by default since Zest™ considers method parameters to be mandatory if not
 explicitly marked with the @Optional annotation. So, instead of doing that check we will add
 other checks that are useful to make, such as ensuring that the passed in string is not empty.
 </p>
 <p>
 The only thing you have to do is add the annotation @NotEmpty to the method parameters you want to
 constrain in this way. The annotation has a default implementation declared in it by using the @Constraints
 annotation. You can either just use this, which is the common case, or override it by declaring your
 own @Constraints annotation in the TransientComposite type.
 </p>
 <p>
 You can add as many Constraint annotations you want to a parameter. All of them will be checked whenever a method is
 called.
 </p>
 <p>
 Steps for this tutorial:
 </p>
 <ol>
     <li>Add @NotEmpty to the state parameters.</li>
 </ol>
 <p><em>Note:</em></p>
 <p>
     The previous steps had a dependency to the <code>org.qi4j.core.api</code> only. The constraints
     you've used in this step, introduce a new dependency to the <code>org.qi4j.library.constraints</code>
     library, where all the constraint related classes reside. So update your classpath settings
     accordingly.
 </p>
 </body>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<body>
	<h1>Tutorial 5 - Constraints</h1>
	<p>
	In this tutorial we will look at how to use Constraints. When we pass parameters to
	methods in regular Java code the only restriction we can make is to denote a type.
	Any other constraints on the input value, such as whether the parameter is optional, integer ranges,
	string regular expressions, and so on, cannot be expressed, and so we have to put this into Javadoc, and
	then manually add these checks in the implementation class.
	</p>
	<p>
	In Zest™ there is the option to use Constraints, which are further restrictions on the parameters.
	This is implemented by having an annotation that describes what the Constraint does, and then
	an implementation class that checks whether a specific value fulfills the Constraint or not.
	</p>
	<p>
	There are a number of pre-written constraints in Zest™ which you can use. The null check of the original
	HelloWorld version is already handled by default since Zest™ considers method parameters to be mandatory if not
	explicitly marked with the @Optional annotation. So, instead of doing that check we will add
	other checks that are useful to make, such as ensuring that the passed in string is not empty.
	</p>
	<p>
	The only thing you have to do is add the annotation @NotEmpty to the method parameters you want to
	constrain in this way. The annotation has a default implementation declared in it by using the @Constraints
	annotation. You can either just use this, which is the common case, or override it by declaring your
	own @Constraints annotation in the TransientComposite type.
	</p>
	<p>
	You can add as many Constraint annotations you want to a parameter. All of them will be checked whenever a method is
	called.
	</p>
	<p>
	Steps for this tutorial:
	</p>
	<ol>
	<li>Add @NotEmpty to the state parameters.</li>
	</ol>
	<p><em>Note:</em></p>
	<p>
	The previous steps had a dependency to the <code>org.qi4j.core.api</code> only. The constraints
	you've used in this step, introduce a new dependency to the <code>org.qi4j.library.constraints</code>
	library, where all the constraint related classes reside. So update your classpath settings
	accordingly.
	</p>
	</body>