You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by df...@apache.org on 2004/10/30 12:20:06 UTC
cvs commit: jakarta-commons-sandbox/contract/xdocs quickstart.xml index.xml
dflorey 2004/10/30 03:20:06
Modified: contract/xdocs quickstart.xml index.xml
Log:
Improved documentation
Revision Changes Path
1.4 +16 -5 jakarta-commons-sandbox/contract/xdocs/quickstart.xml
Index: quickstart.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/contract/xdocs/quickstart.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- quickstart.xml 17 Oct 2004 17:03:56 -0000 1.3
+++ quickstart.xml 30 Oct 2004 10:20:06 -0000 1.4
@@ -30,14 +30,20 @@
<p>So your method will accept two floats that pass the distance and the time to the method. Additionally
the method requires the unit in which the time was measured. You can tell this by using the appropriated
types, that reflect the desired values.</p>
-<p>But you cannot declare, which value ranges are valid for the parameters of your method.
+<p>This example is incomplete, as no error handling is done. What happens if the method will be called
+ with time=0? What if the user enters an invalid unit? As this part is not much fun, many programmers
+ don't care much about handling errors in an appropriate way and by doing so cause much pain.</p>
+<p>In the java world, you cannot declare which value ranges are valid for the parameters of your method.
You might only accept values larger than zero for the time and only "s", "min" and "h" for the
- measuring unit. Imagine that you want to provide a simple program, that allows the user to enter
+ measuring unit.</p>
+ <p>Imagine that you want to provide a simple program, that allows the user to enter
these three parameters and you want to provide the calculated speed. To calculate the speed is
the very easy task, but as you might already know it is a lot more work to handle all possible errors,
to display the user in a localized way which values are accepted and so on.</p>
+</section>
+<section name="The speed calculator example">
<p>This is the moment where the contract component comes into play! You have to declare the possible
- values that are accepted by your method and the result that will be provided, but this effort
+ values that are accepted by your method and the result that will be provided. This additional effort
will be donated by handling all the rest. Let's have a look at the sources of the SpeedCalculator that
is provided as an example in the sources of this component:</p>
<source>
@@ -91,10 +97,15 @@
of code than in the classical java method example. But on the other hand you'll gain
a lot! Launch the example that is included in this component by invoking the contrac-example.jar:</p>
<source>java -jar contract-example.jar</source>
-<p>As you can see, you have to define constraints for all the parameters that your method will accept.
+<p>This example is using the InteractiveMailWrapper to build a multilingual application that
+ handles the user input and ensures that the implemented method will only be called,
+ when all input parameters match the defined needs.</p>
+</section>
+<section name="Constraints">
+<p>As you can see in the example, you have to define constraints for all the parameters that your method will accept.
You even have the possibility to provide a default value that will be used when no parameter value
is provided. This means, that the parameter is optional.</p>
+<p>You also provide constraints for the results that your processor provides.</p>
</section>
-
</body>
</document>
1.3 +1 -1 jakarta-commons-sandbox/contract/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/contract/xdocs/index.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- index.xml 15 Oct 2004 17:34:12 -0000 1.2
+++ index.xml 30 Oct 2004 10:20:06 -0000 1.3
@@ -16,7 +16,7 @@
</p>
<p>
This component makes all the nice features available to the java programming language that
-come along with contract based programming.
+come along with contract based programming. To get started go <a href="quickstart.html">here</a>.
</p>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org