org.hd.d.pg2k.webSvr.virtualHosts.AlohaEarth
Class AlohaEarthMapCache

java.lang.Object
  org.hd.d.pg2k.webSvr.virtualHosts.AlohaEarth.AlohaEarthMapCache

public final class AlohaEarthMapCache
extends java.lang.Object

This class caches Estd-located exhibits and map fragments for Aloha Earth.

MEMORY_SENSITIVE_CACHE

private static final boolean MEMORY_SENSITIVE_CACHE

If true, use SoftReference memory-sensitive cache; use if memory-starved. We will always cache the top couple of levels which are likely to be small in number but relatively expensive to recompute.

See Also:

Constant Field Values

NO_EXHIBITS

private static final java.util.List<Name.ExhibitFull> NO_EXHIBITS

Empty exhibits list.

efh

private final AlohaEarthMapCache.EFHook efh

Emergency-free hook, never null. Reference has to be maintained to prevent instant expiry.

aep

public final AllExhibitProperties aep

Underlying AEP; never null.

allEstdExhibits

private final java.util.List<Name.ExhibitFull> allEstdExhibits

Unmodifiable smart-sorted list of all exhibits with Estd location; never null.

CACHEING

private static final boolean CACHEING

If true, we attempt to cache images and exhibit sub-sets by area. If false, everything is created on demand (which may be slow).

We only attempt to cache where the constrained offsets of AEParams are forced to tile increments, ensuring that only a relatively small number of distinct areas can be seen by the viewer, reducing the maximum number of distinct cached items and increasing the potential hit rate.

See Also:

Constant Field Values

RECURSIVE_SELECT

private static final boolean RECURSIVE_SELECT

If true, we attempt to select exhibits from the zoom-out set. This is an optimisation to attempt to filter exhibits of an area from the same offset but zoomed out one step rather than from the base set of exhibits, which will probably save a lot of time on all but the outermost view.

This only make sense if we are cacheing results of lookups, and if we are constraining lookups to tile boundaries.

See Also:

Constant Field Values

TOP_LEVEL_ESTD_FILTER

public static final boolean TOP_LEVEL_ESTD_FILTER

If false, the entire set of exhibits selected by the master filter appears at top level; we may sort but we will not further filter. This should save time for the critical top-level view by avoiding performing a redundant second check that all values are Estd values, at least with the default filter in place.

See Also:

Constant Field Values

_sVLVP_cache

private final java.util.Hashtable<java.lang.String,java.lang.Object> _sVLVP_cache

Private cache for selectViewLocationVirtualPrefix(); never null. A map from AEParams-synthesised key to (possibly SoftReference to) LocationMap lookup key for area for which title is generated.

_sVLL_cache

private final java.util.Hashtable<java.lang.String,java.lang.Object> _sVLL_cache

Private cache for selectViewLocationVirtualPrefix(); never null. A map from AEParams-synthesised key to (possibly SoftReference to) LocationMap lookup key for area for which title is generated.

_sCE_cache

private final java.util.Hashtable<java.lang.String,java.lang.Object> _sCE_cache

Private cache for selectContainedExhibits(); never null. A map from AEParams-synthesised key to (possibly SoftReference to) immutable String List of exhibits with centres in the current map view.

All access is synchronised on this object.

A Hashtable is used as inherently thread-safe.

Start this small; let it grow if needed.

_sMEI_cache

private final java.util.Hashtable<java.lang.String,java.lang.Object> _sMEI_cache

Private cache for selectMapEncodedImage(); never null. A map from AEParams-synthesised key to (possibly SoftReference to) byte[] image.

All access is synchronised on this object.

This can be clear()ed by clearCache().

A Hashtable is used as inherently thread-safe.

Start this small; let it grow if needed.

MARKER_EXTRA_PIXELS

private static final int MARKER_EXTRA_PIXELS

Number of extra pixels to draw the marker in each direction; non-negative.

See Also:

Constant Field Values

TITLE_AREA_BOUNDARY_STEP

private static final int TITLE_AREA_BOUNDARY_STEP

Pixel step for title area boundaries, 1 means solid; strictly positive.

See Also:

Constant Field Values

TITLE_AREA_EG

private static final int TITLE_AREA_EG

Extra size of corner guides on marker title area in pixels, larger than exhibit marker for emphasis; strictly positive.

See Also:

Constant Field Values

AlohaEarthMapCache

AlohaEarthMapCache(DataSourceBean dsb)
             throws java.io.IOException

Default constructor. Sets the filter to be one on location (exhibits with Estd location).

We expect its lazy computation to take lots of CPU in total, so we try to hang onto some of the base/expensive cached state, but we do have an emergency-free hook to release everything in case of emergency.

Only package-visible since only AlohaEarth utility methods need to construct this.

Throws:

java.io.IOException

_extractCacheEntry

private static java.lang.Object _extractCacheEntry(java.util.Map cache,
                                                   java.lang.Object key)

Routine to extract cache entry from given cache; null if no cached entry. If not CACHEING then always return null, else if raw cache entry is a SoftReference then it is de-referenced, else the raw entry is returned (null if no entry).

_insertCacheEntry

private static void _insertCacheEntry(java.util.Map cache,
                                      java.lang.Object key,
                                      java.lang.Object item,
                                      boolean strongRef)

Insert item in given cache, forcing non-SoftReference if need be. If is a memory-sensitive cache and strongRef is false or we've not got lots of free memory, then the item will be cached via a SoftReference, else a strong reference will be used.

To avoid ambiguity, the item to be cached must not itself be a SoftReference.

If not CACHEING, this does nothing.

selectViewLocationVirtualPrefixAsTitle

public java.lang.CharSequence selectViewLocationVirtualPrefixAsTitle(AEParams aeps,
                                                                     javax.servlet.ServletContext context)

Get selectViewLocationVirtualPrefix() value suitable for use as title; "" if none available.

_extractMainWordPrefixFromVirtualPrefix

private static java.lang.CharSequence _extractMainWordPrefixFromVirtualPrefix(Name virtPrefix)

Extract main-word-prefix portion from LocationMap virtual prefix. Eg, from "x/y-z-" return "y-z-".

selectViewLocationVirtualPrefix

public Name selectViewLocationVirtualPrefix(AEParams aeps,
                                            LocationMap lm)

Get best-match prefix of form "section/main-words-" from LocationMap for current view, or "" if none; never null.

selectViewLocationLabels

public java.lang.String selectViewLocationLabels(DataSourceBean dsb,
                                                 AEParams aeps)

Create HTML label text to overlay the map; returns "" if none, never null. This creates an unnumbered list with one or more absolutely-positioned (within the encompassing relatively positioned parent element). If there are no labels to show then this does not create the UL element and the result is "".

The first view labels may be rendered more strongly.

selectContainedExhibits

public java.util.List<Name.ExhibitFull> selectContainedExhibits(AEParams aeps)

Selects an immutable List of exhibits whose centres lie in the current map view; never null. If we are using tile encoding, then this caches its results via a SoftReference based on the constrained/canonicalised AEParams value set from the current request. The cache is cleared when the exhibit set changes. The very top result or results at the outermost zooms (that a typical visitor is likely to encounter first) may be cached with strong references to ensure that they remain in cache for fast access.

If we are not using a tile encoding then this does not cache at all, but just generates everything on demand.

This routine tries to avoid drawing each distinct point on the map more than once to save time on the assumptions that:

• The marker is idempotent, so redrawing does not add anything.
• Drawing is relatively expensive.

Parameters:

aeps - parameters with which map to display is chosen; not null

Returns:

immutable List of full names of exhibits in current map view; not null

_getRawInputSetForFilter

private Name.ExhibitFull[] _getRawInputSetForFilter(AEParams aeps)

Returns the String[] set of full exhibit names to filter; never null. This is nominally the entire set filtered by the base filter bean, but may instead be a subset thereof from an area enclosing the current view, eg from a zoomed-out view.

Parameters:

aeps - parameters for current view of map; never null

_chooseLocationFilter

private static FilterExpr _chooseLocationFilter(AEParams aeps)

Choose the filter to apply to the source data set of null if not filter is to be applied. This may return null on the outermost zoom level to return all the input data, else it will return a filter to select exhibits within the current view area only.

Parameters:

aeps - current properties (zoom, etc); never null

Returns:

filter expression

selectMapEncodedImage

public ROByteArray selectMapEncodedImage(AEParams aeps,
                                         javax.servlet.ServletContext context)
                                  throws java.io.IOException

Create an encoded map fragment for display; never null. If we are using tile encoding, then this caches its images via a SoftReference based on the constrained/canonicalised AEParams value set from the current request. The cache is cleared when the exhibit set changes. The very top result or results at the outermost zooms (that a typical visitor is likely to encounter first) may be cached with strong references to ensure that they remain in cache for fast access.

If we are not using a tile encoding then this does not cache at all, but just generates everything on demand.

Access is synchronized (on a private lock) so as to:

• Protect the cache if one is used.
• Limit peak resource consumption (CPU and memory).

However, a different lock may be held while a new image is being created to the normal cache-access lock in order that the creation of new images does not block retrieval of already-generated ones.

Draws a (red) marker cross at the centre of every exhibit within the current area, and zero-or-more titles/labels to highlight the selected area.

Parameters:

aeps - parameters with which map to display is chosen; not null

Throws:

java.io.IOException

_drawTitleMarkers

private void _drawTitleMarkers(LocationMap lm,
                               AEParams aeps,
                               java.awt.image.BufferedImage bi)

Draw the marker(s) corresponding to the title location, if any. If there is no title then this may draw nothing.

This may draw crosshairs for the centroid.

_drawVLine

private static void _drawVLine(java.awt.image.BufferedImage bi,
                               int colour,
                               int x,
                               int minY,
                               int maxY)

Draw vertical line of given colour at x from minY to maxY. This is careful not to attempt to draw pixels out of the image.

_drawHLine

private static void _drawHLine(java.awt.image.BufferedImage bi,
                               int colour,
                               int y,
                               int minX,
                               int maxX)

Draw horizontal line of given colour at y from minX to maxX. This is careful not to attempt to draw pixels out of the image.

_drawExhibitMarkers

private static void _drawExhibitMarkers(java.util.List<Name.ExhibitFull> exhibits,
                                        AllExhibitProperties aep,
                                        AEParams aeps,
                                        java.awt.image.BufferedImage bi)

Draw the markers for individual exhibits.

Parameters:

exhibits - List of exhibits; never null

aep - exhibit properties; nevr null

aeps - current view; never null

bi - BufferedImage to draw markers on; never null

_drawExhibitMarker

private static void _drawExhibitMarker(java.awt.Point p,
                                       java.awt.image.BufferedImage bi)

Draw marker on map image fragment to indicate location of an exhibit. The point argument is itself guaranteed to be within the supplied image area, but not all pixels adjacent to it are, ie it might be on an edge.

Parameters:

p - location to centre the exhibit market

bi - image to draw the marker on