FileDocCategorySizeDatePackage
ZoneView.javaAPI DocJava SE 5 API21010Fri Aug 26 14:58:16 BST 2005javax.swing.text

ZoneView

public class ZoneView extends BoxView
ZoneView is a View implementation that creates zones for which the child views are not created or stored until they are needed for display or model/view translations. This enables a substantial reduction in memory consumption for situations where the model being represented is very large, by building view objects only for the region being actively viewed/edited. The size of the children can be estimated in some way, or calculated asynchronously with only the result being saved.

ZoneView extends BoxView to provide a box that implements zones for it's children. The zones are special View implementations (the children of an instance of this class) that represent only a portion of the model that an instance of ZoneView is responsible for. The zones don't create child views until an attempt is made to display them. A box shaped view is well suited to this because:

  • Boxes are a heavily used view, and having a box that provides this behavior gives substantial opportunity to plug the behavior into a view hierarchy from the view factory.
  • Boxes are tiled in one direction, so it is easy to divide them into zones in a reliable way.
  • Boxes typically have a simple relationship to the model (i.e. they create child views that directly represent the child elements).
  • Boxes are easier to estimate the size of than some other shapes.

The default behavior is controled by two properties, maxZoneSize and maxZonesLoaded. Setting maxZoneSize to Integer.MAX_VALUE would have the effect of causing only one zone to be created. This would effectively turn the view into an implementation of the decorator pattern. Setting maxZonesLoaded to a value of Integer.MAX_VALUE would cause zones to never be unloaded. For simplicity, zones are created on boundaries represented by the child elements of the element the view is responsible for. The zones can be any View implementation, but the default implementation is based upon AsyncBoxView which supports fairly large zones efficiently.

author
Timothy Prinzing
version
1.17 12/19/03
see
View
since
1.3

Fields Summary
int
maxZoneSize
int
maxZonesLoaded
Vector
loadedZones
Constructors Summary
public ZoneView(Element elem, int axis)
Constructs a ZoneView.

param
elem the element this view is responsible for
param
axis either View.X_AXIS or View.Y_AXIS


                           
         
	super(elem, axis);
	loadedZones = new Vector();
    
Methods Summary
protected javax.swing.text.ViewcreateZone(int p0, int p1)
Create a view to represent a zone for the given range within the model (which should be within the range of this objects responsibility). This is called by the zone management logic to create new zones. Subclasses can provide a different implementation for a zone by changing this method.

param
p0 the start of the desired zone. This should be >= getStartOffset() and < getEndOffset(). This value should also be < p1.
param
p1 the end of the desired zone. This should be > getStartOffset() and <= getEndOffset(). This value should also be > p0.

	Document doc = getDocument();
	View zone = null;
	try {
	    zone = new Zone(getElement(), 
			    doc.createPosition(p0),
			    doc.createPosition(p1));
	} catch (BadLocationException ble) {
	    // this should puke in some way.
	    throw new StateInvariantError(ble.getMessage());
	}
	return zone;
    
intgetDesiredZoneEnd(int pos)
Returns the zone position to use for the end of a zone that starts at the given position. By default this returns something close to half the max zone size.

	Element elem = getElement();
	int index = elem.getElementIndex(pos + (maxZoneSize / 2));
	Element child = elem.getElement(index);
	int offs0 = child.getStartOffset();
	int offs1 = child.getEndOffset();
	if ((offs1 - pos) > maxZoneSize) {
	    if (offs0 > pos) {
		return offs0;
	    }
	}
	return offs1;
    
public intgetMaxZonesLoaded()
Get the current setting of the number of zones allowed to be loaded at the same time.

	return maxZonesLoaded;
    
public intgetMaximumZoneSize()
Get the current maximum zone size.

	return maxZoneSize;
    
protected intgetViewIndexAtPosition(int pos)
Returns the child view index representing the given position in the model.

param
pos the position >= 0
return
index of the view representing the given position, or -1 if no view represents that position

	// PENDING(prinz) this could be done as a binary
	// search, and probably should be.
	int n = getViewCount();
	if (pos == getEndOffset()) {
	    return n - 1;
	}
	for(int i = 0; i < n; i++) {
	    View v = getView(i);
	    if(pos >= v.getStartOffset() &&
	       pos < v.getEndOffset()) {
		return i;
	    }
	}
	return -1;
    
voidhandleInsert(int pos, int length)

	int index = getViewIndex(pos, Position.Bias.Forward);
	View v = getView(index);
	int offs0 = v.getStartOffset();
	int offs1 = v.getEndOffset();
	if ((offs1 - offs0) > maxZoneSize) {
	    splitZone(index, offs0, offs1);
	}
    
voidhandleRemove(int pos, int length)

	// IMPLEMENT
    
public voidinsertUpdate(javax.swing.event.DocumentEvent changes, java.awt.Shape a, javax.swing.text.ViewFactory f)
Gives notification that something was inserted into the document in a location that this view is responsible for. This is largely delegated to the superclass, but is reimplemented to update the relevant zone (i.e. determine if a zone needs to be split into a set of 2 or more zones).

param
changes the change information from the associated document
param
a the current allocation of the view
param
f the factory to use to rebuild if the view has children
see
View#insertUpdate

	handleInsert(changes.getOffset(), changes.getLength());
	super.insertUpdate(changes, a, f);
    
protected booleanisZoneLoaded(javax.swing.text.View zone)
Determine if a zone is in the loaded state. The zones are expected to represent a subset of the child elements of the element this view is responsible for. Therefore, the default implementation is to return true if the view has children.

	return (zone.getViewCount() > 0);
    
protected voidloadChildren(javax.swing.text.ViewFactory f)
Loads all of the children to initialize the view. This is called by the setParent method. This is reimplemented to not load any children directly (as they are created by the zones). This method creates the initial set of zones. Zones don't actually get populated however until an attempt is made to display them or to do model/view coordinate translation.

param
f the view factory

	// build the first zone.
	Document doc = getDocument();
	int offs0 = getStartOffset();
	int offs1 = getEndOffset();
	append(createZone(offs0, offs1));
	handleInsert(offs0, offs1 - offs0);
    
public voidremoveUpdate(javax.swing.event.DocumentEvent changes, java.awt.Shape a, javax.swing.text.ViewFactory f)
Gives notification that something was removed from the document in a location that this view is responsible for. This is largely delegated to the superclass, but is reimplemented to update the relevant zones (i.e. determine if zones need to be removed or joined with another zone).

param
changes the change information from the associated document
param
a the current allocation of the view
param
f the factory to use to rebuild if the view has children
see
View#removeUpdate

	handleRemove(changes.getOffset(), changes.getLength());
	super.removeUpdate(changes, a, f);
    
public voidsetMaxZonesLoaded(int mzl)
Sets the current setting of the number of zones allowed to be loaded at the same time. This will throw an IllegalArgumentException if mzl is less than 1.

param
mzl the desired maximum number of zones to be actively loaded, must be greater than 0
exception
IllegalArgumentException if mzl is < 1

        if (mzl < 1) {
            throw new IllegalArgumentException("ZoneView.setMaxZonesLoaded must be greater than 0.");
        }
	maxZonesLoaded = mzl;
	unloadOldZones();
    
public voidsetMaximumZoneSize(int size)
Set the desired maximum zone size. A zone may get larger than this size if a single child view is larger than this size since zones are formed on child view boundaries.

param
size the number of characters the zone may represent before attempting to break the zone into a smaller size.

	maxZoneSize = size;
    
voidsplitZone(int index, int offs0, int offs1)
Break up the zone at the given index into pieces of an acceptable size.

	// divide the old zone into a new set of bins
	Element elem = getElement();
	Document doc = elem.getDocument();
	Vector zones = new Vector();
	int offs = offs0;
	do {
	    offs0 = offs;
	    offs = Math.min(getDesiredZoneEnd(offs0), offs1);
	    zones.addElement(createZone(offs0, offs));
	} while (offs < offs1);
	View oldZone = getView(index);
	View[] newZones = new View[zones.size()];
	zones.copyInto(newZones);
	replace(index, 1, newZones);
    
voidunloadOldZones()

	while (loadedZones.size() > getMaxZonesLoaded()) {
	    View zone = (View) loadedZones.elementAt(0);
	    loadedZones.removeElementAt(0);
	    unloadZone(zone);
	}
    
protected voidunloadZone(javax.swing.text.View zone)
Unload a zone (Convert the zone to its memory saving state). The zones are expected to represent a subset of the child elements of the element this view is responsible for. Therefore, the default implementation is to simple remove all the children.

param
zone the child view desired to be set to an unloaded state.

	//System.out.println("unloading: " + zone.getStartOffset() + "," + zone.getEndOffset());
	zone.removeAll();
    
protected booleanupdateChildren(javax.swing.event.DocumentEvent$ElementChange ec, javax.swing.event.DocumentEvent e, javax.swing.text.ViewFactory f)
The superclass behavior will try to update the child views which is not desired in this case, since the children are zones and not directly effected by the changes to the associated element. This is reimplemented to do nothing and return false.

	return false;
    
protected voidzoneWasLoaded(javax.swing.text.View zone)
Called by a zone when it gets loaded. This happens when an attempt is made to display or perform a model/view translation on a zone that was in an unloaded state. This is imlemented to check if the maximum number of zones was reached and to unload the oldest zone if so.

param
zone the child view that was just loaded.

	//System.out.println("loading: " + zone.getStartOffset() + "," + zone.getEndOffset());
	loadedZones.addElement(zone);
	unloadOldZones();