sos.reports
Interface BreakWeightRecorder

All Known Implementing Classes:
ArrayBreakWeightRecorder

public interface BreakWeightRecorder

A mechanism to record where an object prefers to be broken. An implementation of this interface is passed to report element views for them to record the break weight at certain indices.

At each index, the object sets its preferred break weight. If multiple weights are recorded at the same index, then the minimum weight prevails. The weights have the following meanings:

WeightMeaning
UNDEFINED_BREAK_WEIGHTThe weight has yet to be set for the index.
BAD_BREAK_WEIGHTThe object cannot be broken at the index.
FORCED_BREAK_WEIGHTThe object requests to be broken at the index.
GOOD_BREAK_WEIGHTThe index is a good break position.
EXCELLENT_BREAK_WEIGHTThe index is an excellent break position.

Clients can change the range of indices for which to record break weights via the methods setRange and createView. The former establishes a clip range such that any index outside of the range is ignored. The latter establishes a clip range but additionally resets the beginning of this range to index 0.

After the weights have been set, use getBreakIndex to determine the best break position.

Since:
1.0
See Also:
View.gatherBreakWeights(int, sos.reports.BreakWeightRecorder), ArrayBreakWeightRecorder

Field Summary
static int BAD_BREAK_WEIGHT
          A constant signaling a bad break (1).
static int EXCELLENT_BREAK_WEIGHT
          A constant signaling an excellent break (4).
static int FORCED_BREAK_WEIGHT
          A constant signaling that a break is required (2).
static int GOOD_BREAK_WEIGHT
          A constant signaling a good break (3).
static int UNDEFINED_BREAK_WEIGHT
          A constant signaling that the break weight has not been specified (0).
 
Method Summary
 BreakWeightRecorder createView(int index, int length)
          Returns a view of this recorder.
 void fill(int weight)
          Fills the entire clip range with the specified weight.
 void fill(int index, int length, int weight)
          Fills the specified range with the specified weight.
 void fillEnd(int index, int weight)
          Fills the end portion with the specified weight.
 int getBestWeight()
          Returns the best, or highest, break weight in the clip range.
 int getBreakIndex()
          Returns the best place to break within the clip range, or -1 if such a place does not exist.
 int getFirstIndexOfWeight(int weight)
          Returns the index of the first bit in the clip range with the specified weight.
 int getFirstIndexOfWeightAtLeast(int weight)
          Returns the index of the first bit in the clip range with a weight greater than or equal to the specified weight.
 int getLastIndexOfWeight(int weight)
          Returns the index of the last bit in the clip range with the specified weight.
 int getLastIndexOfWeightAtLeast(int weight)
          Returns the index of the last bit in the clip range with a weight greater than or equal to the specified weight.
 int getRangeLength()
          Returns the length of the clip range.
 int getRangeStart()
          Returns the starting index of the clip range.
 int getWeight(int index)
          Returns the weight at the specified index.
 void setRange(int index, int length)
          Sets this recorder's clip range.
 void setWeight(int index, int weight)
          Sets the weight at the specified index.
 

Field Detail

UNDEFINED_BREAK_WEIGHT

public static final int UNDEFINED_BREAK_WEIGHT
A constant signaling that the break weight has not been specified (0).

See Also:
Constant Field Values

BAD_BREAK_WEIGHT

public static final int BAD_BREAK_WEIGHT
A constant signaling a bad break (1).

See Also:
Constant Field Values

FORCED_BREAK_WEIGHT

public static final int FORCED_BREAK_WEIGHT
A constant signaling that a break is required (2).

See Also:
Constant Field Values

GOOD_BREAK_WEIGHT

public static final int GOOD_BREAK_WEIGHT
A constant signaling a good break (3).

See Also:
Constant Field Values

EXCELLENT_BREAK_WEIGHT

public static final int EXCELLENT_BREAK_WEIGHT
A constant signaling an excellent break (4).

See Also:
Constant Field Values
Method Detail

createView

public BreakWeightRecorder createView(int index,
                                      int length)
Returns a view of this recorder. The view's indexing starts at 0 and ends at length - 1. Index 0 in the view corresponds to index in this recorder, and index length - 1 corresponds to index + length - 1. Operations on the view within its range propagate to this recorder.

The specified index and length are bound by this recorder's current range. That is, they are adjusted so that the view cannot operate outside this recorder's range.

Parameters:
index - index of this recorder to get mapped to index 0 of the returned view
length - number of indices to be in the view
Returns:
a sub-view restricted to length indices and translated by index
Throws:
java.lang.IllegalArgumentException - if length < 0
java.lang.IndexOutOfBoundsException - if index < 0

fill

public void fill(int weight)
Fills the entire clip range with the specified weight. The resulting weight of a bit is the minimum of the current weight and the specified weight.

Parameters:
weight - maximum weight that each bit in the clip range should have

fill

public void fill(int index,
                 int length,
                 int weight)
Fills the specified range with the specified weight. The resulting weight of a bit is the minimum of the current weight and the specified weight.

The range is bound by this recorder's current clip range. That is, bits outside the clip range are ignored.

Parameters:
index - start index at which to set the weight
length - number of bits for which to set the wieght
weight - maximum weight that each bit in the specified range should have
Throws:
java.lang.IllegalArgumentException - if length < 0
java.lang.IndexOutOfBoundsException - if index < 0
See Also:
fill(int), fillEnd(int, int)

fillEnd

public void fillEnd(int index,
                    int weight)
Fills the end portion with the specified weight.

The range is bound by this recorder's current clip range. That is, bits outside the clip range are ignored.

Parameters:
index - start index at which to set the weight
weight - maximum weight that each bit in the specified range should have
Throws:
java.lang.IndexOutOfBoundsException - if index < 0

getBestWeight

public int getBestWeight()
Returns the best, or highest, break weight in the clip range.

Returns:
the best weight

getBreakIndex

public int getBreakIndex()
Returns the best place to break within the clip range, or -1 if such a place does not exist. The implementation is free to decide what constitutes best, as long as the weight at the returned index is not BAD_BREAK_WEIGHT.

Returns:
the recommended break index, or -1 if one does not exist

getFirstIndexOfWeight

public int getFirstIndexOfWeight(int weight)
Returns the index of the first bit in the clip range with the specified weight.

Parameters:
weight - weight to seek
Returns:
the index of the first bit in the clip range with the specified weight, or -1 if no such bit exists

getFirstIndexOfWeightAtLeast

public int getFirstIndexOfWeightAtLeast(int weight)
Returns the index of the first bit in the clip range with a weight greater than or equal to the specified weight.

Parameters:
weight - minimum weight to seek
Returns:
the index of the first bit in the clip range with a weight greater than or equal to the specified weight, or -1 if no such bit exists

getLastIndexOfWeight

public int getLastIndexOfWeight(int weight)
Returns the index of the last bit in the clip range with the specified weight.

Parameters:
weight - weight to seek
Returns:
the index of the last bit in the clip range with the specified weight, or -1 if no such bit exists

getLastIndexOfWeightAtLeast

public int getLastIndexOfWeightAtLeast(int weight)
Returns the index of the last bit in the clip range with a weight greater than or equal to the specified weight.

Parameters:
weight - minimum weight to seek
Returns:
the index of the last bit in the clip range with a weight greater than or equal to the specified weight, or -1 if no such bit exists

getRangeStart

public int getRangeStart()
Returns the starting index of the clip range.

Returns:
the starting index of the clip range
See Also:
getRangeLength(), setRange(int, int)

getRangeLength

public int getRangeLength()
Returns the length of the clip range.

Returns:
the length of the clip range
See Also:
getRangeStart(), setRange(int, int)

getWeight

public int getWeight(int index)
Returns the weight at the specified index.

Parameters:
index - index at which to fetch the weight
Returns:
the weight at index
Throws:
java.lang.IndexOutOfBoundsException - if index < 0 or index is outside the clip range

setRange

public void setRange(int index,
                     int length)
Sets this recorder's clip range. Future operations outside this range will be ignored.

The range is bound by this recorder's current clip range. That is, bits outside the clip range are ignored.

Parameters:
index - start index of range to clip
length - length of range to clip
Throws:
java.lang.IllegalArgumentException - if length < 0
java.lang.IndexOutOfBoundsException - if index < 0

setWeight

public void setWeight(int index,
                      int weight)
Sets the weight at the specified index. The method does nothing if the index is outside of the clip range. The resulting weight at index is the minimum of the current weight and the specified weight.

Parameters:
index - index at which to set the weight
weight - weight of a potential break at index
Throws:
java.lang.IndexOutOfBoundsException - if index < 0


Copyright 2003, 2004 Side of Software (SOS). All rights reserved.