• An Observation:
  • In Java, a method can only return a single primitive value or reference and this can be inconvenient
• An Example:
  • A method that needs to return the minimum and maximum of an array
• Obvious Solutions:
  • Return an array
  • Create a Range class that has two attributes and return an instance of it
• An Alternative Solution:
  • Use a parameter instead

• Variable Types:
  • Primitive types
  • Reference types
• Parameter Passing:
  • All parameters in Java are passed by value (i.e., a copy is made)

• A First (Incorrect) Thought:
  • Since parameters are passed by value it is impossible to have outbound parameters
• A Deeper Thought:
  • A copy of a reference is an alias, so mayber reference types can be used

• Three Situations:
  • The parameter is a mutable reference type
  • The parameter is a primitive type
  • The parameter is an immutable reference type
• Handling These Situations:
  • When the parameter is mutable, the method can change its attributes to "return" information
  • When the parameter is a primitive type or immutable, you can wrap it

javaexamples/programmingpatterns/outboundparameters/Range.java

/**
 * An encapsulation of a range of doubles.
 *
 * @author  Prof. David Bernstein, James Madison University
 * @version 1.0
 */
public class Range {
    
    private   double max, min;
    
    /**
     * Construct the Range (-infinity, infinity).
     */
    public Range() {
        set(Double.NEGATIVE_INFINITY, Double.POSITIVE_INFINITY);
    }
    
    /**
     * Construct a Range.
     *
     * @param min  The minimum value in the Range
     * @param max  The maximum value in the Range
     */
    public Range(double min, double max) {
        set(min, max);
    }

    /**
     * Get the maximum value in this Range.
     *
     * @return  The maximum value
     */
    public double getMax() {
        return max;
    }

    /**
     * Get the minimum value in this Range.
     *
     * @return  The minimum value
     */
    public double getMin() {
        return min;
    }

    /**
     * Set this Range. Note that, if the min and max are reversed,
     * this method will swap the two.
     *
     * @param min  The minimum value
     * @param max  The maximum value
     */
    public void set(double min, double max) {
        this.min = min;
        this.max = max;
    }
}
        

javaexamples/programmingpatterns/outboundparameters/ColorWrapper.java

import java.awt.Color;

/**
 * A mutable wrapper for Color objects.
 *
 * @author  Prof. David Bernstein, James Madison University
 * @version 1.0
 */
public class ColorWrapper {
    
    private Color   wrapped;
    
    /**
     * Default Constructor.
     */
    public ColorWrapper() {
        set(null);
    }
    
    /**
     * Explicit Value Constructor.
     *
     * @param c  The initial Color
     */
    public ColorWrapper(Color c) {
        set(c);
    }

    /**
     * Get the wrapped Color.
     *
     * @return  The value
     */
    public Color get() {
        return wrapped;
    }

    /**
     * Set the wrapped Color.
     *
     * @param  c   The value
     */
    public void set(Color c) {
        wrapped = c;        
    }
}
        

• The Simplest Version:
  • 1. Create a wrapper class if necessary
  • 2. Declare a method with an appropriate signature
  • 4. Perform the necessary operations in the body of the method
  • 5. Modify the attributes of the outbound parameter
• Using this Version:
  • The invoker of the method must then construct an "empty" instance of the outbound parameter and pass it to the method

• An Improvement:
  • Allow the invoker to indicate whether the method should construct the outbound parameters
• The Improved Version:
  • 3. At the top of the method, check to see if the outbound parameter is null and, if it is, construct an instance of the outbound parameter
  • 6. Return the outbound parameter
• Using this Version:
  • The invoker of the method must then construct an "empty" instance of the outbound parameter and pass it to the method

javaexamples/programmingpatterns/outboundparameters/OutboundParameters.java (Fragment: extremes)

    /**
     * Calculate minimum and maximum values in an array.
     *
     * @param data    The data
     * @param range   An outbound parameter containing the min and max (or null)
     * @return        The range
     */
    public static double[] extremes(double[] data, double[] range) {
        if (range == null) range = new double[2];

        range[0] = Double.POSITIVE_INFINITY;
        range[1] = Double.NEGATIVE_INFINITY;
        
        for (int i = 0; i < data.length; i++) {
            if (data[i] < range[0]) range[0] = data[i];
            if (data[i] > range[1]) range[1] = data[i];
        }
        return range;
    }
        

javaexamples/programmingpatterns/outboundparameters/OutboundParameters.java (Fragment: extrema)

    /**
     * Calculate minimum and maximum values in an array.
     *
     * @param data    The data
     * @param range   An outbound parameter containing the min and max (or null)
     * @return        The range
     */
    public static Range extrema(double[] data, Range range) {
        if (range == null) range = new Range();
        double  max, min;

        min = Double.POSITIVE_INFINITY;
        max = Double.NEGATIVE_INFINITY;
        
        for (int i = 0; i < data.length; i++) {
            if (data[i] < min) min = data[i];
            if (data[i] > max) max = data[i];
        }
        range.set(min, max);
        return range;
    }
        

javaexamples/programmingpatterns/outboundparameters/OutboundParameters.java (Fragment: summarize)

    /**
     * Sumamrize the properties of an array.
     *
     * @param data  The data array
     * @param positives An outbound parameter for the count of positive elements
     * @param negatives An outbound parameter for the count of negative elements
     * @param zeroes    An outbound parameter for the count fo zero elements
     */
    public static void summarize(int[] data, 
                                 IntWrapper positives, 
                                 IntWrapper negatives,
                                 IntWrapper zeroes) {
        int neg = 0, pos = 0, zer = 0;

        for (int i = 0; i < data.length; i++) {
            if      (data[i] < 0) neg++;
            else if (data[i] > 0) pos++;
            else                  zer++;
        }
        positives.set(pos);
        negatives.set(neg);
        zeroes.set(zer);
    }
        

javaexamples/programmingpatterns/outboundparameters/OutboundParameters.java (Fragment: purpleOut)

    /**
     * A method that converts any Color to JMU purple and.
     *
     * @param wrapper The outbound wrapped Color
     * @return        The outbound wrapped Color
     */
    public static ColorWrapper purpleOut(ColorWrapper wrapper) {
        if (wrapper == null) wrapper = new ColorWrapper();

        wrapper.set(new Color(69, 0, 132));
        return wrapper;
    }