commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject cvs commit: jakarta-commons-sandbox/contract/xdocs quickstart.xml navigation.xml
Date Fri, 15 Oct 2004 17:57:27 GMT
dflorey     2004/10/15 10:57:27

  Modified:    contract/xdocs quickstart.xml navigation.xml
  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 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
  +type of tbe return value. This is how a method might look like that calcalutes speed:</p>
   	public float calculateSpeed(float distance, float time, String unit) {
   		...calculate speed...
  @@ -26,10 +26,67 @@
   <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
  +	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
  +		will be donated by handling all the rest. Let's have a look at the sources of the SpeedCalculator
  +		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
  +	is provided. This means, that the parameter is optional.</p>
  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&#xA0;Contract">
  -        <menu name="Commons&#xA0;Transaction">
  +        <menu name="Commons&#xA0;Contract">
               <item name="Overview" href="/index.html" />
               <item name="Getting started" href="/quickstart.html" />	
   <!--            <item name="Configuration"                 href="/configuration.html"
/> -->

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message