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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
