dflorey 2004/10/15 10:57:27
Modified: contract/xdocs quickstart.xml navigation.xml
Log:
Revision Changes Path
1.2 +63 -6 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- quickstart.xml 15 Oct 2004 17:34:12 -0000 1.1
+++ quickstart.xml 15 Oct 2004 17:57:27 -0000 1.2
@@ -16,8 +16,8 @@
</section>
<section name="What is contract based programming?">
<p>You already know contract based programming if you've ever implemented a java
method: You specify
-a contract that defines which types of parameters are accepted by your method. This
is how a method
-might look like:</p>
+a contract that defines which types of parameters are accepted by your method and
you specify the
+type of tbe return value. This is how a method might look like that calcalutes
speed:</p>
<source>
public float calculateSpeed(float distance, float time, String unit) {
...calculate speed...
@@ -26,10 +26,67 @@
</source>
<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. But you cannot declare, which value
ranges are valid for your
- method. You might only accept values larger than zero for the time and only
"s", "min" and "h" for the
- unit.</p>
- <p>To get started you need at least the jar of this component and the
dependent i18n.jar in your classpath.</p>
+ types, that reflect the desired values.</p>
+<p>But 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
+ 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>
+ <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
+ 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>
+public class SpeedCalculator implements Processor {
+ public final static String SPEED = "speed";
+
+ private final static String DISTANCE = "distance";
+ private final static String TIME = "time";
+ private final static String UNIT = "unit";
+ private final static String SECONDS = "s";
+ private final static String MINUTES = "min";
+ private final static String HOURS = "h";
+
+ ParameterDescriptor[] parameterDescriptors = new ParameterDescriptor[]{
+ new ParameterDescriptor(DISTANCE, new
ParameterMessage("computeSpeed/parameter/distance"),
+ new NumberConstraints(
+ new Integer(0), null, true)),
+ new ParameterDescriptor(UNIT, new
ParameterMessage("computeSpeed/parameter/unit"),
+ new StringConstraints(
+ new String[]{SECONDS, MINUTES, HOURS})),
+ new ParameterDescriptor(TIME, new
ParameterMessage("computeSpeed/parameter/time"),
+ NumberConstraints.POSITIVE)};
+
+ ResultDescriptor[] resultDescriptors = new ResultDescriptor[]{new
ResultDescriptor(
+ StateDescriptor.OK_DESCRIPTOR,
+ new ResultEntryDescriptor[]{new ResultEntryDescriptor(SPEED,
+ new LocalizedMessage("computeSpeed/result/speed"),
+ new NumberConstraints(new Float(0.1), new
Integer(Integer.MAX_VALUE)))})};
+
+ public Result process(Map parameters, Context context) {
+ float distance = ((Number)parameters.get(DISTANCE)).floatValue();
+ float time = ((Number)parameters.get(TIME)).floatValue();
+ String timeUnit = (String)parameters.get(UNIT);
+ float speed;
+ if (timeUnit.equals("s")) speed = distance / time;
+ else if (timeUnit.equals("min")) speed = distance*60 / time;
+ else speed = distance*3600 / time;
+ return new Result(StateDescriptor.OK, SPEED, new Float(speed));
+ }
+
+ public ParameterDescriptor[] getParameterDescriptors() {
+ return parameterDescriptors;
+ }
+
+ public ResultDescriptor[] getResultDescriptors() {
+ return resultDescriptors;
+ }
+}
+ </source>
+<p>As you can see, 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>
</section>
</body>
1.4 +1 -1 jakarta-commons-sandbox/contract/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/contract/xdocs/navigation.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- navigation.xml 15 Oct 2004 17:34:12 -0000 1.3
+++ navigation.xml 15 Oct 2004 17:57:27 -0000 1.4
@@ -3,7 +3,7 @@
<project name="Commons Contract">
<title>Commons Contrac</title>
<body>
- <menu name="Commons Transaction">
+ <menu name="Commons Contract">
<item name="Overview" href="/index.html" />
<item name="Getting started" href="/quickstart.html" />
<!-- <item name="Configuration"
href="/configuration.html" /> -->
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
