org.hd.d.pg2k.svrCore
Class AllExhibitImmutableData

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

All Implemented Interfaces:

java.io.ObjectInputValidation, java.io.Serializable

public final class AllExhibitImmutableData
extends java.lang.Object
implements java.io.Serializable, java.io.ObjectInputValidation

Immutable set of names and ExhibitStaticAttr for all exhibits. This provides a set of all exhibits, mapped from the full name to the static/immutable attributes for an exhibit (ie the parts that will not change unless the exhibit itself is changed).

Also provides a mapping from the final file component of an exhibit to its full name within the collection. All exhibits should be unique in this last component; if not then only the alphabetically first full-name value will be kept.

Also contains the time of last change to exhibit set when this snapshot was taken; this is verified simply to be non-negative and may for example be some combination of timestamp and hash over the exhibit content to best catch changes in the exhibit-set composition or it may be a pure hash. If a combination then usually the most significant bits would be those of the newest exhibit and the least significant would be the hash. If the exhibit set changes then this value should change, however the timestamp may not monotonically increase as new exhibits are added (or existing ones are altered).

Designed to be efficient `on-the-wire'; for serialisation we send a count and the ExhibitStaticAttr objects in sorted order by name instead of the map, which should be much less bulky than our internal representation (which is designed for lookup speed), and contains all the required information. On deserialising we simply reconstruct the map. We still let default serialisation deal with any other fields (the timestamp).

(It looks like HashMap's serialisation must be quite good since the saving in uncompressed size is only about 6%.)

The hashCode() is based on a hash of the timestamp, and equality is based on the sets of exhibits and global and per-exhibit attributes being equal.

See Also:

Serialized Form

timestamp

public final long timestamp

Timestamp of last exhibit update when this snapshot was taken. Strictly positive unless map is empty, in which case it will be zero.

This information is accessable without holding any locks.

length

public final int length

Exhibit count, with lock-free access; non-negative. The information in this is redundant (it is available in m.size() for example), but is small and useful for speed and an integrity check, etc.

This emulates the length field of an array while size() emulates the behaviour of collections...

This information is accessable without holding any locks.

m

private transient java.util.Map<java.lang.String,ExhibitStaticAttr> m

Map from name to static attr; never null once construction/deserialisation is complete. Never altered once installed so is thread-safe.

Custom serialisation means that this map has to be mutable, so cannot be given out to a caller as-is.

shortToFull

private transient java.util.Map<java.lang.String,java.lang.String> shortToFull

Immutable Map from final file component (ie short name) to full name; never null.

shortNameDups

private transient java.lang.String[] shortNameDups

List of duplicates found by _buildShortToFull; never null.

_cache_getAllExhibitNamesList

private transient volatile java.util.List<java.lang.String> _cache_getAllExhibitNamesList

Cache for getAllExhibitNamesList() immutable content. Initially null, but never non-null once set.

Marked volatile for lock-free thread-safe access.

Marked transient as this is recomputable redundant state.

_cache_getAllExhibitNamesSorted

private transient volatile java.lang.String[] _cache_getAllExhibitNamesSorted

Cache for getAllExhibitNamesSorted(). Initially null, but never non-null once set.

Marked volatile for lock-free thread-safe access.

Marked transient as this is recomputable redundant state.

serialVersionUID

private static final long serialVersionUID

Our serial version...

See Also:

Constant Field Values

AllExhibitImmutableData

public AllExhibitImmutableData()

Construct an empty, zero-timestamp snapshot.

AllExhibitImmutableData

public AllExhibitImmutableData(java.util.Map<java.lang.String,ExhibitStaticAttr> nameToStaticAttr,
                               long lastExhibitChangeTimestamp)
                        throws java.lang.IllegalArgumentException

Construct a new snapshot. The Map must consist purely of mappings from valid String exhibit names to ExhibitStaticAttr items; the Map is copied and this is checked.

The timestamp must be zero if the map is empty, else it must be strictly positive.

Throws:

java.lang.IllegalArgumentException - if the timestamp or Map are found to be malformed.

_buildShortToFull

private void _buildShortToFull()

Builds shortToFull (and shortNameDups) from m if required. We ensure that at least the short names are intern()ed to avoid duplication in memory.

getFullNamesWithDuplicateShortNames

public java.lang.String[] getFullNamesWithDuplicateShortNames()

Gets (sorted) list of full names that have duplicate short names; zero-length if none. This returns a copy that can be safely tampered with by the caller.

getAllExhibitShortNamesSet

public java.util.Set<java.lang.String> getAllExhibitShortNamesSet()

Gets a Set of all short exhibit names.

getFullName

public java.lang.String getFullName(java.lang.String shortName)

Gets the full name of an exhibit from its (unique) file component; null if no exhibit has the specified short name.

Parameters:

shortName - must not be null

Returns:

non-null full name iff the param is a syntactically-valid short name for that extant full name

getShortToFullMap

public java.util.Map<java.lang.String,java.lang.String> getShortToFullMap()

Gets the immutable Map from short to full name; null if no exhibit has the short name.

getStaticAttr

public ExhibitStaticAttr getStaticAttr(java.lang.String name)

Get exhibit attributes; if result non-null the exhibit is valid.

size

public int size()

Get exhibit count; 0 if no exhibits.

isEmpty

public boolean isEmpty()

True if zero/no exhibits.

getAllExhibitNamesSet

public java.util.Set<java.lang.String> getAllExhibitNamesSet()

Gets a Set of all (String) raw (full) exhibit names. The result is immutable.

Should be relatively efficient.

getAllExhibitNamesList

public java.util.List<java.lang.String> getAllExhibitNamesList()

Gets an immutable RandomAccess list of all raw exhibit names which is probably not sorted; never null. This should be reasonably quick.

getAllExhibitNamesSorted

public java.lang.String[] getAllExhibitNamesSorted()

Gets an array of all raw exhibit names; sorted by raw name. This may be slow, as it may have to do the sort in place.

This returns a private array.

getAllStaticAttrs

public java.util.Set<ExhibitStaticAttr> getAllStaticAttrs()

Gets Set of all static attrs unsorted. Could be very large and slow to get; use with caution.

getAllStaticAttrsSorted

public java.util.SortedSet<ExhibitStaticAttr> getAllStaticAttrsSorted()

Gets SortedSet of all static attrs; sorted by raw name. Could be very large and slow to get; use with caution.

getPooledExhibitName

public java.lang.String getPooledExhibitName(java.lang.String name)

Canonicalise exhibit name String. This looks up a full String name in the list of exhibits. If not found it returns the original String. If found it returns the copy of the String in the exhibit.

computeFileSpaceBytes

public final long computeFileSpaceBytes(java.lang.String author)

Conservatively estimates filespace bytes required to store all exhibits. This makes some assumptions about filespace overhead and so on.

This is for the specific named author, unless author is null in which case it for all authors.

This separately rounds up each exhibit size and name size to an assume filesystem block size as per FileTools.roundUpToFSBlockSize().

Throws:

java.lang.IllegalArgumentException - if author is not null and is not a syntactically-valid author name (initials)

hashCode

public int hashCode()

Returns a hash code value for the object derived from the timestamp. Will be zero (because the timestamp is) if there are no exhibits.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value for this object.

See Also:

Object.equals(Object), Hashtable

equals

public boolean equals(java.lang.Object obj)

Returns true when the underlying set of exhibits and attributes is the same.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the reference object with which to compare.

Returns:

true if this object is the same as the obj argument; false otherwise.

See Also:

Boolean.hashCode(), Hashtable

writeObject

private void writeObject(java.io.ObjectOutputStream oos)
                  throws java.io.IOException

Write out a less-redundant (and more compressable) form of our internal information.

Throws:

java.io.IOException

readObject

private void readObject(java.io.ObjectInputStream ois)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException

Deserialise.

Throws:

java.io.IOException

java.lang.ClassNotFoundException

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