org.hd.d.pg2k.svrCore
Class AccessionData

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

All Implemented Interfaces:

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

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

Immutable, Serializable collection of all the accession data for an exhibit. This contains all of the available accession data for an exhibit, ie data collected at or after the exhibit was added to the library, such as checksums to verify that the exhibit has not become corrupted.

In some cases not all fields will be complete.

The core fields are made available as public final fields for speed of access.

We do not ever expect two instances for different exhibits to be equal, so the only reason to intern() the whole object is to reduce heap churn between an extant and new/updated exhibit set. We don't do this automatically during deserialisation, and leave it up to a user of this type to do so if they wish. We do not intern() the fields of this object individually, to help avoid pointless space and time being taken in intern().

See Also:

Serialized Form

NAME_TOP_NODE

public static final java.lang.String NAME_TOP_NODE

Top-level node name for XML representation, ie tag name.

See Also:

Constant Field Values

NAME_ACCESSION_DATE

public static final java.lang.String NAME_ACCESSION_DATE

Name of the accession date sub-node, if any.

See Also:

Constant Field Values

NAME_ACCESSION_SIZE

public static final java.lang.String NAME_ACCESSION_SIZE

Name of the accession-time size sub-node, if any.

See Also:

Constant Field Values

NAME_ACCESSION_CRC32

public static final java.lang.String NAME_ACCESSION_CRC32

Name of the accession-time whole-exhibit CRC32 hash sub-node, if any.

See Also:

Constant Field Values

NAME_ACCESSION_MD5

public static final java.lang.String NAME_ACCESSION_MD5

Name of the accession-time whole-exhibit MD5 hash sub-node, if any.

See Also:

Constant Field Values

HASH_BLOCK_SIZE_BYTES

public static final int HASH_BLOCK_SIZE_BYTES

Block size (in bytes) used for partial hashes; strictly positive power of two. This is can be used while reading in a file in a block at a time to avoid holding a lock too long, and as the size of each block of a per-block hash such as can be used to check validity of the start of a partly-cached exhibit.

See Also:

Constant Field Values

date

public final java.lang.Long date

Nominal time/data at which exhibit was added to the Gallery; null or strictly positive. This is null if not available, ie the accession time/date was not recorded, else it is the strictly positive Java time in milliseconds (since 19700101 00:00 UTC).

This can the same as, or later than, the exhibit's timestamp. If earlier than the exhibit's timestamp it may mean that the exhibit has been altered in some way.

size

public final java.lang.Long size

Size of exhibit file at time of accession; null or strictly positive. This is null if not available, ie the accession time/date was not recorded, else it is the strictly positive number of bytes in the file.

This should be identical to the current exhibit length else it may mean that the exhibit has been altered in some way.

hashCRC32

public final java.lang.Integer hashCRC32

Accession-time CRC32 whole-exhibit hash or null if not available. We use CRC32 since it is commonly used elsewhere as a file checksum, for example in ZIP files.

hashMD5

public final ROByteArray hashMD5

Accession-time MD5 whole-exhibit hash or null if not available. If non-null the array is always exactly 16 bytes long.

We use MD5 since it is commonly used elsewhere as a file checksum, and will in practice detect any conceivable corruption in exhibits especially given that we separately record the length.

dbf_gAD

private static final javax.xml.parsers.DocumentBuilderFactory dbf_gAD

Private shared factory_pFX for getAsDOM(); never null.

EMPTY

public static final AccessionData EMPTY

Public empty instance.

factory_pFX

private static final javax.xml.parsers.DocumentBuilderFactory factory_pFX

Private shared factory_pFX for parseFromXML(); never null.

serialVersionUID

private static final long serialVersionUID

Unique Serialisation class ID generated by http://random.hd.org/.

See Also:

Constant Field Values

AccessionData

private AccessionData()

Construct new immutable instance with no data. Is private to help with instance control.

AccessionData

public AccessionData(java.lang.Long accessionDate,
                     java.lang.Long accessionSize,
                     java.lang.Integer accessionCRC32,
                     ROByteArray accessionMD5)
              throws java.lang.IllegalArgumentException

Construct new immutable instance with the given data.

Throws:

java.lang.IllegalArgumentException - in the case of bad data

isIncomplete

public final boolean isIncomplete()

If true, some accession data is missing (eg null).

getAsDOM

public org.w3c.dom.Node getAsDOM()

Get exhibit accession metadata as DOM, never null. This data includes such items as:

• When the exhibit was loaded into to the Gallery.
• Its checksums, timestamp, length, etc when loaded into the Gallery.

All this data is also accessible by (probably cheaper) direct accessor methods or fields if required.

hashCode

public final int hashCode()

The hashCode is VM-independent. The size and CRC32 fields are used in the computation.

Overrides:

hashCode in class java.lang.Object

equals

public final boolean equals(java.lang.Object o)

All fields are compared.

Overrides:

equals in class java.lang.Object

parseFromXML

public static AccessionData parseFromXML(java.lang.String xml)
                                  throws java.io.IOException

Parse from XML format UNICODE text. We will attempt to be generous in our parsing, but must be able to extract the top-level node and at least one sub-ordinate node else we will assume that we have been given a bogus file.

Parameters:

xml - must be correct XML format and start with '<', not null, not zero-length

Throws:

java.io.IOException - in case of difficulty parsing the text

fromExhibitFile

public static AccessionData fromExhibitFile(java.io.File f)
                                     throws java.io.IOException

Construct accession data purely from the exhibit file. This does not look at any extant or old-style accession data.

This does not check that the exhibit is valid except that it is a plain file and not zero-length.

Throws:

java.io.IOException

computeFullFileHashes

public static Tuple.Pair<java.lang.Integer,ROByteArray> computeFullFileHashes(java.io.InputStream is)
                                                                       throws java.io.IOException

Compute the full-file hashes over an exhibit; never null and neither element of the Pair null. This reads the entire InputStream and computes all the full-stream hashes at once for efficiency.

This does not close the InputStream.

The InputStream need not be buffered since we read in large efficient blocks anyway if possible.

Returns:

the CRC32 checksum as an Integer in the first element, and the MD5 hash as an ROByteArray in the second element

Throws:

java.io.IOException

readResolve

protected java.lang.Object readResolve()

Deserialise: use constructor for validation, defensive copying, etc.

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