org.hd.d.pg2k.webSvr.util
Class HTMLThumbnailInsertGenerators

java.lang.Object
  org.hd.d.pg2k.webSvr.util.HTMLThumbnailInsertGenerators

public final class HTMLThumbnailInsertGenerators
extends java.lang.Object

Utility functions to generate HTML inserts for showing batches of thumbnails/links. One advantage of having a method here rather than in-line in a JSP is that this code is pre-compiled off-line for speed and robustness.

COLDISP_MIN_WIDTH_PIXELS

public static final int COLDISP_MIN_WIDTH_PIXELS

Minimum width for column display in pixels; strictly positive.

See Also:

Constant Field Values

COLDISP_MIN_HEIGHT_PIXELS

public static final int COLDISP_MIN_HEIGHT_PIXELS

Minimum height for column display in pixels; strictly positive. Taken to be the height of display for one exhibit with a small thumbnail.

See Also:

Constant Field Values

COLDISP_MEAN_CHAR_WIDTH_PIXELS

public static final int COLDISP_MEAN_CHAR_WIDTH_PIXELS

Assumed approximate mean pixels wide per (small) character; strictly positive.

See Also:

Constant Field Values

COLDISP_MEAN_CHAR_HEIGHT_PIXELS

public static final int COLDISP_MEAN_CHAR_HEIGHT_PIXELS

Assumed approximate mean pixels wide per (small) character; strictly positive.

See Also:

Constant Field Values

MAX_THUMBNAIL_EXHIBITS_TO_RETAIN_FOR_DISPLAY

private static final int MAX_THUMBNAIL_EXHIBITS_TO_RETAIN_FOR_DISPLAY

Cap number of items cached for thumbnail generators for efficiency; strictly positive. Somewhat more than just the "first page" of 'best exhibit' results so that we can show some exhibits beyond it.

See Also:

Constant Field Values

rndKey

private static final DataSourceBean.AEPLinkedKey rndKey

Key to retrieve AEP-linked set of 'random JPEG' exhibits.

bestKey

private static final DataSourceBean.AEPLinkedKey bestKey

Key to retrieve AEP-linked set of 'best' exhibits.

_bestE_update_lock

private static final java.util.concurrent.locks.ReentrantLock _bestE_update_lock

Lock to prevent more than one update run on _bestE at once.

_bestE_dontUpdateBefore

private static volatile long _bestE_dontUpdateBefore

Time before which we will not attempt incremental update of _bestE set. Set so as to limit fraction of system CPU spent recomputing/updating.

Is volatile so as to allow access without a lock.

Private to getBestExhibitsSelection().

NO_RESULTS

private static final Name.ExhibitFull[] NO_RESULTS

Empty (immutable) array to return to indicate no results.

newKey

private static final DataSourceBean.AEPLinkedKey newKey

Key to retrieve AEP-linked set of 'new' exhibits.

CHECK_ALL_FOR_STALE

private static final boolean CHECK_ALL_FOR_STALE

If true then invalidate "best" collection if any stale value is found. Otherwise, only invalidate if there is a significant value change. (If not then we can survive until the next periodic re-sort.) This is may be pretty aggressive on CPU and other resources if true.

See Also:

Constant Field Values

BEST_EPSILON

private static final int BEST_EPSILON

Out-of-order tolerance we will allow before forcing "best" selection to be recomputed. This corresponds to an insignificantly small difference that will rarely be noticed by a (non-obsessive!) human, so need not force us to invalidate and re-sort the entire collection.

See Also:

Constant Field Values

_CS_ALWAYS_ONLY_SHOW_THUMBNAILS

private static final boolean _CS_ALWAYS_ONLY_SHOW_THUMBNAILS

If true then always omit from the contact sheet any items that do not immediately/ever have a thumbnail.

See Also:

Constant Field Values

CS_CACHE_FOR_CAT_PAGES

public static final boolean CS_CACHE_FOR_CAT_PAGES

If true then try to cache cat page contact sheets; this may require minor cosmetic changes in generated HTML for efficiency.

See Also:

Constant Field Values

_CSCacheKey

private static final DataSourceBean.AEPLinkedKey _CSCacheKey

Private key used by getContactSheetHTML(); never null.

REQ_ATTR_NAME_LOAD_HOVERBOX_CCS

private static final java.lang.String REQ_ATTR_NAME_LOAD_HOVERBOX_CCS

Request-level attribute set non-null before creating the header to load Hoverbox CSS.

See Also:

Constant Field Values

CS_INCOMPLETE

public static final java.lang.String CS_INCOMPLETE

Comment tag at end of HTML for contact sheet if we ran out of time or it is otherwise incomplete.

See Also:

Constant Field Values

MAX_HOVERBOX_OVERSPILL_PX

private static final int MAX_HOVERBOX_OVERSPILL_PX

Maximum that 'Hoverbox' overlay thumbnail may extend outside the table containing small thumbnails, in pixels; strictly positive. This should match up with the Hoverbox CSS targets and possibly a fudge-factor for various browsers' rendering quirks.

See Also:

Constant Field Values

LIGHTBOX_PADDING_POP_LINKS

private static final boolean LIGHTBOX_PADDING_POP_LINKS

If padding a lightbox out with a overlay image safety area, do we insert popular links?

See Also:

Constant Field Values

LIGHTBOX_TABLE_BORDER_PX

private static final int LIGHTBOX_TABLE_BORDER_PX

Allow this many pixels' border in lightbox table; non-negative.

See Also:

Constant Field Values

HTMLThumbnailInsertGenerators

private HTMLThumbnailInsertGenerators()

Prevent construction of an instance.

makeHTMLExhibitRow

public static java.lang.String makeHTMLExhibitRow(Name.ExhibitFull[] exhibits,
                                                  DataSourceBean dataSource,
                                                  LocaleBeanBase localeBean,
                                                  boolean reduceEffort)
                                           throws java.io.IOException

Makes HTML for row display of the exhibits supplied; never null.

Parameters:

exhibits - non-null list of full, valid exhibit names, more important first (later items may not be displayed)

dataSource - non-null source of exhibit data and thumbnails

reduceEffort - if true, reduce CPU and bandwidth load in executing this routine and implied by the output

Returns:

empty output if no thumbnails available, else wrappable linked HTML for thumbnail display

Throws:

java.io.IOException

makeHTMLExhibitColumnDisplay

public static java.lang.String makeHTMLExhibitColumnDisplay(Name.ExhibitFull[] exhibits,
                                                            int pixelsWidth,
                                                            int pixelsHeight,
                                                            DataSourceBean dataSource,
                                                            LocaleBeanBase localeBean,
                                                            boolean reduceEffort)
                                                     throws java.io.IOException

Makes HTML for columnar (ie taller and thin) display of exhibits; never null. Given the width and height for display, and a list of exhibits, will format and show as many as is reasonably possible in the space. Exhibits from the start of the list will be shown first.

Text is horizontally centred.

This may not show any exhibits at all if the area is too small.

This will not work well if the space is very narrow or shallow, much less than about 100 pixels.

Note that this may not get things exactly right if the user selects different font sizes in their browser.

Parameters:

exhibits - non-null list of full, valid exhibit names, more important first (later items may not be displayed)

dataSource - non-null source of exhibit data and thumbnails

pixelsWidth - non-negative width of display space in pixels

pixelsHeight - non-negative height of display space in pixels

reduceEffort - if true, reduce CPU and bandwidth load in executing this routine and implied by the output

Throws:

java.io.IOException - if there is difficulty retrieving meta-data

getNewExhibitSelection

public static Name.ExhibitFull[] getNewExhibitSelection(javax.servlet.ServletContext application,
                                                        int maxExhibits,
                                                        java.util.Random rnd)
                                                 throws java.io.IOException

Get random selection of new-ish exhibit full names; never null. Selects from newest few percent of available exhibits, and within those the very newest are most likely to be returned. Note that no absolute age/time limits are imposed.

If there are any exhibits at all, and maxExhibits is positive, this routine ensures that at least one exhibit is a candidate to show.

These results are cached against the AEP, and automatically discarded/recomputed when the exhibit set changes.

May return empty list, but no nulls nor duplicates.

Should only be used with one servlet context.

Parameters:

application - the servlet context; never null

maxExhibits - the maximum number of exhibits to return; non-negative

rnd - the random number source if non-null, else null to pick top items

Throws:

java.io.IOException

getNewExhibitSelection

public static Name.ExhibitFull[] getNewExhibitSelection(javax.servlet.ServletContext application,
                                                        int maxExhibits,
                                                        java.util.Random rnd,
                                                        boolean beQuick)
                                                 throws java.io.IOException

Get random selection of new-ish exhibit full names; never null. Selects from newest few percent of available exhibits, and within those the very newest are most likely to be returned. Note that no absolute age/time limits are imposed.

If there are any exhibits at all, and maxExhibits is positive, this routine ensures that at least one exhibit is a candidate to show.

These results are cached against the AEP, and automatically discarded/recomputed when the exhibit set changes.

May return empty list, but no nulls nor duplicates.

Should only be used with one servlet context.

Parameters:

application - the servlet context; never null

maxExhibits - the maximum number of exhibits to return; non-negative

rnd - the random number source if non-null, else null to pick top items

beQuick - if true and the result is needs recomputing from scratch then this returns an empty result and attempts to recompute in the background

Throws:

java.io.IOException

getRandomJPEGSelection

public static Name.ExhibitFull[] getRandomJPEGSelection(javax.servlet.ServletContext application,
                                                        int maxExhibits)
                                                 throws java.io.IOException

Get random selection of JPEG exhibit full names; never null. These results are cached against the AEP, and automatically discarded/recomputed when the exhibit set changes.

May return empty list, but no nulls nor duplicates.

Should only be used with one servlet context.

Parameters:

application - the servlet context; never null

maxExhibits - the maximum number of exhibits to return; non-negative

Throws:

java.io.IOException

getRandomJPEGSelection

public static Name.ExhibitFull[] getRandomJPEGSelection(javax.servlet.ServletContext application,
                                                        int maxExhibits,
                                                        boolean beQuick)
                                                 throws java.io.IOException

Get random selection of JPEG exhibit full names; never null. These results are cached against the AEP, and automatically discarded/recomputed when the exhibit set changes.

May return empty list, but no nulls nor duplicates.

Should only be used with one servlet context.

Parameters:

application - the servlet context; never null

maxExhibits - the maximum number of exhibits to return; non-negative

beQuick - if true and the result is needs recomputing from scratch then this returns an empty result and attempts to recompute in the background

Throws:

java.io.IOException

getBestExhibitSelection

public static Name.ExhibitFull[] getBestExhibitSelection(javax.servlet.ServletContext application,
                                                         int maxExhibits,
                                                         java.util.Random rnd)
                                                  throws java.io.IOException

Get names of the the best exhibits ("goodness" greater than zero); never null. These results are cached against the AEP, and automatically discarded/recomputed when the exhibit set changes, and also periodically to allow for the values changing over time.

May return an empty list, but no nulls nor duplicates.

Should only be used with one servlet context.

If a random number source is supplied then it is used to chose a random (though weighted toward best) selection of exhibits.

If no random number source is supplied then the very best exhibits are returned.

(May invalidate its cache and spend a short time updating entries if any of the items that it is about to return is stale or the results are no longer in order (best first) in the hope that non-stale ones will have been computed in the mean time. This incremental cache validation and recomputation should help keep the results reasonable without penalising any one caller too much, and returns reasonable results in a short time on each call.)

Parameters:

application - the servlet context; never null

maxExhibits - the maximum number of exhibits to return; non-negative

rnd - the random number source if non-null, else null to pick top items

Throws:

java.io.IOException

getBestExhibitSelection

public static Name.ExhibitFull[] getBestExhibitSelection(javax.servlet.ServletContext application,
                                                         int maxExhibits,
                                                         java.util.Random rnd,
                                                         boolean beQuick)
                                                  throws java.io.IOException

Get names of the the best exhibits ("goodness" greater than zero); never null. These results are cached against the AEP, and automatically discarded/recomputed when the exhibit set changes, and also periodically to allow for the values changing over time.

May return an empty list, but no nulls nor duplicates.

Should only be used with one servlet context.

If a random number source is supplied then it is used to chose a random (though weighted toward best) selection of exhibits.

If no random number source is supplied then the very best exhibits are returned.

(May invalidate its cache and spend a short time updating entries if any of the items that it is about to return is stale or the results are no longer in order (best first) in the hope that non-stale ones will have been computed in the mean time. This incremental cache validation and recomputation should help keep the results reasonable without penalising any one caller too much, and returns reasonable results in a short time on each call.)

This ties not to block for the calculation of any EPCM values.

Parameters:

application - the servlet context; never null

maxExhibits - the maximum number of exhibits to return; non-negative

rnd - the random number source if non-null, else null to pick top items

beQuick - if true and the result is needs recomputing from scratch then this returns an empty result and attempts to recompute in the background

Throws:

java.io.IOException

getContactSheetHTML

public static java.lang.String getContactSheetHTML(Name.ExhibitFull exhibitName,
                                                   java.lang.String specialColour,
                                                   DataSourceBean dataSource,
                                                   java.util.List<Name.ExhibitFull> smartSortedNames)

Make "contact print" / "preview" HTML fragment to show a user all similar exhibits, "" if none possible; never null. This routine returns a table of (small thumbnails of) all the exhibits with the same main words prefix as the supplied word, in order, in as compact and efficient form as reasonable.

Note that if using the 'Hoverbox' feature, then overlay standard thumbnails may appear above and to the left or right of a small thumbnail being hovered over, so sufficient clearance should be given above this HTML insert to avoid conflicts with surrounding material, such as ads.

This may choose to omit or show substitute text for exhibits with no immediately-available thumbnail.

This does not generate any headings.

If this encounters an error (eg an exception, or inconsistent arguments) then it will attempt to return gracefully with a "no-contact-sheet-available" empty value ("").

This may spend a limited amount of time trying to create thumbnails, bring up-to-date computable data, etc, but in any case tries to be quick.

Appends a special HTML comment tag to the result if incomplete due to missing thumbnails or lack of time.

This may cache completed results against all of the exhibit names given, to be discarded if the AEP for the supplied DataSourceBean changes.

Parameters:

exhibitName - this name of the main exhibit for which a contact sheet is to be generated; must be a valid, non-null exhibit name

specialColour - HTML colour name (or #RRGGBB value) to distinguish the main exhibit in the contact sheet somehow, quoted if it need be for an attribute value, may be ignored for efficiency/consistency; null if no such marking to be done

dataSource - data source for thumbnails, etc; never null

smartSortedNames - list of all exhibit names, sorted with the SMART_ORDER Comparator, and should be random-access else this will probably be horribly slow; never null

Returns:

"" if a contact sheet is not applicable or cannot be generated (so result is safe to drop into HTML without checking if need be) else a well-formed HTML fragment suitable to drop into a catalogue page; never null

enableHoverboxCSS

public static final void enableHoverboxCSS(javax.servlet.http.HttpServletRequest request)

Call this before generating the header to load the Hoverbox CSS. Does nothing if the `Hoverbox' is not enabled.

This is idempotent, and sets a request-level attribute.

hoverboxCSSIsEnabled

public static final boolean hoverboxCSSIsEnabled(javax.servlet.http.HttpServletRequest request)

Returns true if the the Hoverbox CSS has been enabled with enableHoverboxCSS(). Does nothing if the `Hoverbox' is not enabled.

This checks a request-level attribute.

generateGenericContactSheetHTML

public static java.lang.String generateGenericContactSheetHTML(int maxPixelsWidth,
                                                               java.util.List<Name.ExhibitFull> exhibitNames,
                                                               java.lang.String specialColour,
                                                               Name.ExhibitFull specialExhibitName,
                                                               long stopBy,
                                                               DataSourceBean dataSource)

Generate contact sheet of the exhibits given, in order; never null. Has special HTML comment tag at end to indicate if the result is incomplete due to missing thumbnails or lack of time.

Note that if using the 'Hoverbox' feature, then overlay larger thumbnails may appear above a thumbnail being hovered over, so we insert sufficient padding around the thumbnail table to avoid conflicts with surrounding page material, such as ads.

Parameters:

exhibitNames - in-order list of exhibits to display; never null

specialExhibitName - name of "special" exhibit to emphasise; null if none

stopBy - approximate target time to finish by; can be set in the past to generate HTML as quickly as possible

specialColour - HTML colour name (or #RRGGBB value) to distinguish the main exhibit in the contact sheet somehow, quoted if it need be for an attribute value; null if no such marking to be done

maxPixelsWidth - maximum pixels available for display (approx); strictly positive

dataSource - data source for thumbnails, etc; never null

Returns:

HTML fragment for contact sheet, or ""; never null

popularUsefulLinksNarrowCol

public static java.lang.String popularUsefulLinksNarrowCol(DataSourceBean dsb,
                                                           int pixelsHigh,
                                                           int pixelsWide,
                                                           boolean toXHTML)

Generate a narrow column of popular/useful internal links for HTML/XHTML, "" if none; never null. Puts a default reasonable cap on generation time as a fraction of maximum page-generation time.

Parameters:

dsb - data source; never null

pixelsHigh - approx number of pixels high; strictly positive

pixelsWide - approx number of pixels wide; strictly positive

toXHTML - if true then link to XHTML catalogue pages rather than HTML pages

popularUsefulLinksNarrowCol

public static java.lang.String popularUsefulLinksNarrowCol(DataSourceBean dsb,
                                                           int pixelsHigh,
                                                           int pixelsWide,
                                                           boolean toXHTML,
                                                           long stopBy)

Generate a narrow column of popular/useful internal links for HTML/XHTML, "" if none; never null.

Parameters:

dsb - data source; never null

pixelsHigh - approx number of pixels high; strictly positive

pixelsWide - approx number of pixels wide; strictly positive

toXHTML - if true then link to XHTML catalogue pages rather than HTML pages

stopBy - try to stop by the specified time.