org.hd.d.pg2k.svrCore
Class ExhibitPropsComputable

java.lang.Object
  org.hd.d.pg2k.svrCore.ExhibitPropsComputable

All Implemented Interfaces:

java.io.ObjectInputValidation, java.io.Serializable, MemoryTools.Compactable, MemoryTools.Internable

public final class ExhibitPropsComputable
extends java.lang.Object
implements java.io.Serializable, java.io.ObjectInputValidation, MemoryTools.Internable, MemoryTools.Compactable

Immutable (and serialisable) store of all immutable computable auxiliary properties of a single exhibit. These are properties that can be computed from the basic exhibit binary data and that generally do not need to be recomputed (unless that exhibit changes, or if we upgrade the code and can get "better" values).

Some of the attributes contained in this object may be expensive to compute (and may require reading the entire exhibit) and thus this object is precomputed on the master server (or offline) where the exhibit is available from fast local storage in its entirety.

This is designed to be efficient on the wire and in memory, since these details will be held for each and every exhibit.

Some data in this object is transient and recomputable from other fields and is recomputed if this object is serialised and deserialised or is kicked out of memory due a shortage.

The equals() and hashCode() of this class can be very expensive, so intern()ing it can be too. However, we do intern() some of its elements.

The construction of this item is brittle, so that if we cannot construct it all, correctly, then we veto construction entirely, so as to avoid results from transient failures persisting indefinitely.

TODO: use a raw UTF form for the description text (not a String or Name) on the wire so that when serialising we don't create and hold onto another Object reference when we could instead have some compressed bytes in a stream somewhere

See Also:

Serialized Form

EMPTY

public static final ExhibitPropsComputable EMPTY

Shared empty instance.

MDPREFIX

private static final java.lang.String MDPREFIX

Common "assumed" prefix on XML metadata.

See Also:

Constant Field Values

MDPREFIX_LENGTH

private static final int MDPREFIX_LENGTH

MDSUFFIX

private static final java.lang.String MDSUFFIX

Common "assumed" suffix on XML metadata.

See Also:

Constant Field Values

MDSUFFIX_LENGTH

private static final int MDSUFFIX_LENGTH

xyDimensions

private final java.awt.Dimension xyDimensions

X,Y dimensions in pixels for images (moving or still) that have a fixed rectangular dimension, else null. If this is non-null then x and y are strictly positive.

Because Dimension is mutable, we hand out copies of it to callers.

sDict

public static final Compact7BitString.StaticDictionary sDict

Shared static dictionary for use with in-memory Compact7BitString metadata. We expose this to help generate tuned dictionary values; this is safe to do since this dictionary is immutable.

metadata

private volatile java.lang.Object metadata

Trimmed metadata for the exhibit (without the constant prefix/suffix); null if none available. This may exist in a number of formats for efficiency "on the wire" and to save space in memory.

• null: no metadata for this exhibit
• String: the simplest format, containing well-formed XML-format metadata (LEGACY)
• ROByteArray: deflated UTF-8 version of String format (LEGACY)
• Compact7BitString: compact byte representation (PREFERRED IN MEMORY)
• Name: compact byte representation (PREFERRED ON THE WIRE)
• byte[]: raw internal Compact7BitString data (LEGACY: NOT SUPPORTED)

Note that this is stored without the redundant top-level tag.

Marked volatile to allow safe lockless update by compact().

ATTEMPT_C7BS_COMPRESSION

private static final boolean ATTEMPT_C7BS_COMPRESSION

If true then attempt in-memory compression of metadata to save space with Compact7BitString.

See Also:

Constant Field Values

serialVersionUID

private static final long serialVersionUID

Our serial version...

See Also:

Constant Field Values

_hash

private transient int _hash

Private cache of the hash value; initially zero, and zero for an EMPTY instance. Thread-safe as int access guaranteed atomic.

DEFER_COMPACTION

private static final boolean DEFER_COMPACTION

If true then defer compaction of metadata. If true then (any) compaction is NOT done during construction or deserialisation since it may place memory under more stress with old and new versions in memory simultaneously, but until some later point such as a call to compact().

Conversely, this could save a lot of time constructing/deserialising data before the first operations can be performed on it and where memory space is not the primary constraint.

See Also:

Constant Field Values

ExhibitPropsComputable

private ExhibitPropsComputable()

Make an empty instance.

ExhibitPropsComputable

private ExhibitPropsComputable(java.awt.Dimension xyDim,
                               java.lang.Object metadata)

Make non-empty instance. This does not intern() any of its arguments (so any that can usefully be intern()ed should already have been).

This may defensively copy mutable argument values.

Parameters:

xyDim - xy (positive) dimensions in pixels or null if none

metadata - normalised metadata else null if none.

getXyDimensions

public java.awt.Dimension getXyDimensions()

Get x,y dimensions in pixels for images (moving or still) that have a fixed rectangular dimension, else null. If this is non-null then x and y are strictly positive.

We return a copy of our internal data.

getMetadataAsXMLTrimmed

public java.lang.CharSequence getMetadataAsXMLTrimmed()

Get metadata as (immutable) trimmed XML, NOT surrounded with top-level tags; null if no metadata.

Returns:

null if no metadata

getMetadataAsXML

public java.lang.String getMetadataAsXML()

Get metadata as full XML string surrounded with top-level tags; null if no metadata.

Returns:

null if no metadata

getMetadata

public org.w3c.dom.Node getMetadata()

Get exhibit metadata; null if none available.

getFactory

private static javax.xml.parsers.DocumentBuilderFactory getFactory()

Return a new factory each time to minimise chance of 'leaks'.

parseMetadata

private static org.w3c.dom.Node parseMetadata(java.lang.String xml)
                                       throws java.io.IOException,
                                              org.xml.sax.SAXException,
                                              javax.xml.parsers.ParserConfigurationException

Parse metadata from internal XML String format; never null.

Parameters:

xml - well-formed non-null non-empty XML metadata

Returns:

non-null DOM node

Throws:

java.io.IOException

org.xml.sax.SAXException

javax.xml.parsers.ParserConfigurationException

_compressTrimmedMetadata

private static java.lang.Object _compressTrimmedMetadata(java.lang.CharSequence mdTrimmed)

Attempt to compress supplied already-trimmed metadata; returns null if input is null. Given the metadata in full XML form, returns it trimmed, and compressed if possible.

createExhibitPropsComputable

public static ExhibitPropsComputable createExhibitPropsComputable(ExhibitStaticAttr esa,
                                                                  AllExhibitProperties.ExhibitDataSource ds)
                                                           throws java.io.IOException

Factory method to create a fully populated ExhibitPropsComputable object. This is given the a data source from which it can fetch the exhibit data one or more times to do its computations.

The data source object is not stored in the object.

This will veto any attempt at construction if the data object is not fully loaded, ie all available immediately with high bandwidth.

Underlying methods, such as getMetadata(), can throw all sorts of horrors, such as an Error, so we try very hard to fail gracefully if this happens and only throw an IOException.

Throws:

java.io.IOException

_trimStringFormOfOuterMetadataTag

public static java.lang.String _trimStringFormOfOuterMetadataTag(java.lang.String mdString)

Remove explicit fixed outer tag to save a little space, or null if input is null. Not for casual use, and not part of the supported API of this class.

readResolve

protected java.lang.Object readResolve()

Deserialise: use constructor for validation, defensive copying, etc. Also resolve all empty instances to a singleton as a minor optimisation, and immediately intern() new values so as to immediately discard duplicates (eg of exhibits already known) ASAP to minimise heap churn.

writeReplace

protected java.lang.Object writeReplace()

Serialise: write in the best format for the wire. To get best aggregate compressed size on the wire, eg where the compressed stream contains many similar non-identical instances, we always write out the metadata in its Name (or String) format (minus the outer tags) regardless of how it is actually held in memory. This also makes us immune to changes in the the internals of the other formats and allows use of a static dictionary with Compact7BitString for better in-memory compression (ie effectively cross-instance compression).

This allows a stream compressor to effectively remove the redundancy between instances of this class on the wire as well as internal redundancies.

We assume that there will almost never be identical instances on one stream so we don't mind writing new copies each time where it does happen.

validateObject

public void validateObject()
                    throws java.io.InvalidObjectException

Validate fields/state. Called in the constructor and possibly after de-serialising.

Barf if something bad is found. (Maybe allow some extra info in debug version.)

Specified by:

validateObject in interface java.io.ObjectInputValidation

Throws:

java.io.InvalidObjectException

equals

public boolean equals(java.lang.Object obj)

Equal if all the members are.

Overrides:

equals in class java.lang.Object

toString

public java.lang.String toString()

Human-readable summary.

Overrides:

toString in class java.lang.Object

_computeHash

private int _computeHash()

Compute the hash value. As well as being used for hash tables, this will be used to detect changes in the representation of computed data, ie for the overall AEP hash, so this should include all significant elements.

Note that this also means that the AEP hash contains a semantically-significant sampling of the exhibit data as well as such things as length and timestamp from the AEID.

hashCode

public int hashCode()

Hash based on the dimensions, else on the metadata.

Overrides:

hashCode in class java.lang.Object

compact

public void compact()

Compact the internal representation of this instance (and its sub-objects) if possible. This has no effect on the logical content of this instance in-memory or serialised, is guaranteed to be safe to run concurrently with other uses of this instance (and will take any locks as needed to work incrementally), and may do nothing but consume some CPU cycles.

This may be able to convert some state to a more memory-efficient representation after construction or deserialisation, and is suitable to be called by a background thread.

We don't prevent multiple concurrent calls to this routine, since they are at worst wasteful of CPU but not unsafe.

Specified by:

compact in interface MemoryTools.Compactable

getCompactableInstanceName

public java.lang.String getCompactableInstanceName()

Get name of this Compactable instance for tracking purposes, or null if none.

Specified by:

getCompactableInstanceName in interface MemoryTools.Compactable