org.hd.d.pg2k.webSvr.location
Class LocationUtils

java.lang.Object
  org.hd.d.pg2k.webSvr.location.LocationUtils

public class LocationUtils
extends java.lang.Object

Utilities to support Location display in Web pages.

LOC_TN_WIDTH

public static final int LOC_TN_WIDTH

Width of (raw and modified) Estd thumbnail in pixels as returned by getEstdLocationThumbnailURL().

See Also:

Constant Field Values

LOC_TN_HEIGHT

public static final int LOC_TN_HEIGHT

Height of (raw and modified) Estd thumbnail in pixels as returned by getEstdLocationThumbnailURL().

See Also:

Constant Field Values

DYN_LOC_TN_IMG_TYPE

static final int DYN_LOC_TN_IMG_TYPE

Type of thumbnail image that we dynamically generate. Need not be the same as the raw thumbnail image, as long as it can (efficiently) encode the modified thumbnail in a byte-indexed format.

Good types to use are PNG and GIF (when the LZW patent expires).

See Also:

Constant Field Values

ETP

static final ExhibitMIME.ExhibitTypeParameters ETP

ExhibitMIME entry for the chosen output type.

DYN_LOC_TN_CROSSHAIR_RGB_COLOUR

public static final int DYN_LOC_TN_CROSSHAIR_RGB_COLOUR

Colour of cross-hairs to show location of item in RGB format. Since the icon is usually rendered in green (land) and blue (sea) this should probably be red or some other high-contrast colour. This should probably also be fully opaque to minimise encoded image size (eg 0xffff0000 for opaque red).

Make this available to (for example) Aloha Earth, so that we can use a common colour/style throughout.

See Also:

Constant Field Values

BASE_ESTD_LOC_TN_URL

static final java.lang.String BASE_ESTD_LOC_TN_URL

Basic root-relative URL for base thumbnail icon. This has to be an image type that we can decode, modify, and encode on the fly.

Assumed to be low-colour suitable for an index/palette representation such as GIF or PNG.

By default rendered n green (land) and blue (sea).

ON OE is assumed to be centered in the image, nominally between pixels for an even-pixel dimension.

See Also:

Constant Field Values

DYN_LOC_TN_MOUNT_POINT

private static final java.lang.String DYN_LOC_TN_MOUNT_POINT

Mount point for servlet, including usual suffix for given image type. May mount this in the "/_static/" area to help clients cache the modified thumbnails and thus reducing redundant requests for them.

This must correspond with where the servlet is actually mounted. (The servlet can be mounted to serve a tree that includes this.)

_gLTWC_cache

private static final java.lang.ref.SoftReference<byte[]>[][] _gLTWC_cache

Private cache for getLocTNWithCrosshairs() accessed under the class lock. Arranged as (x,y)-crosshair-centre array of SoftReference to byte[] encoded images.

LocationUtils

public LocationUtils()

getTNCrosshairCentre

private static java.awt.Dimension getTNCrosshairCentre(Location.Estd loc)

Get cross-hair X,Y pixel centre on thumbnail given Estd location. Since the dimension values are integral, this rounds to the nearest correct pixel value.

The result is contrained to valid pixel coordinates [0, width[ and [0, height[.

getEstdLocationThumbnailURL

public static java.lang.String getEstdLocationThumbnailURL(Location.Estd loc,
                                                           boolean embedInHTML)

Return root-relative (starting with "/") URL for Estd location thumbnail. May be fixed, or may depend on actual location.

Parameters:

loc - the location on Earth to link to the map for; never null

embedInHTML - if true, result will be embedded in HTML so we will separate parameters with '&' rather than an unprotected '&'

getLocTNWithCrosshairs

static byte[] getLocTNWithCrosshairs(javax.servlet.ServletContext context,
                                     int x,
                                     int y)
                              throws java.lang.IllegalArgumentException,
                                     java.lang.RuntimeException,
                                     java.io.IOException

Returns a modified location thumbnail with crosshairs centred on x,y; never null. This will create an image on first use, and cache it (via a SoftReference).

The byte[] returned is not copied and so must not be altered. This routine is only package-visible.

This routine is synchronized primarily to make the cache thread-safe, but has the side-effect of ensuring that only one thumbnail can be generated at once, thus limiting peak CPU and memory demands.

Parameters:

context - context of current WAR; must not be null

x - x coordinate of crosshair centre within thumbnail

y - x coordinate of crosshair centre within thumbnail

Returns:

encoded image for modeified thumbnail; this is a shared copy and must not be altered by the caller which is one reason that the routine is only package-visible

Throws:

java.lang.IllegalArgumentException - if context is null

java.lang.RuntimeException - if x or y not valid pixel coords within the thumbnail, ie where the crosshair could be centred.

java.io.IOException - if difficulty generating modified thumbnail for example because the site is too busy

makeLocTNImgHTML

public static java.lang.String makeLocTNImgHTML(Location.Estd location)

Make HTML img for correct Estd location thumbnail with E/N crosshairs. If there is no location then return the empty string.

The returned img has the alignment "top" and alt text "Aloha Earth!" and no spaces round it.