org.hd.d.pg2k.svrCore
Class AllExhibitPropertiesDelta

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

All Implemented Interfaces:

java.io.Serializable

public final class AllExhibitPropertiesDelta
extends java.lang.Object
implements java.io.Serializable

Class to compute/represent changes from one AEP instance to another. Where a small number of changes has occurred between one AEP and another, especially where those changes are renamings or minor textual changes, it may often be vastly more efficient to send a diff from an extant AEP instance than send the new instance in toto.

There may be circumstances in which this class cannot compute a diff, or where the diff is unlikely to be worthwhile (eg after huge changes), in which case the diff computation routine indicates failure/unwillingness and the caller may have to arrange for a full AEP to be transmitted.

This class is Serializable, and is reasonably efficient on-the-wire, but is not necessarily intended for long-term persistence; store the AEP instances themselves for that by preference.

We are cautious in that we store several explicit before-and-after hashes to be clear that we are applying diffs to the right AEP instance and so as to be sure that we end up with the correct value.

Author:

DHD

See Also:

Serialized Form

longHashAEPBefore

public final long longHashAEPBefore

The long hash for the AEP to which the diff is to be applied; guaranteed non-negative.

longHashAEPAfter

public final long longHashAEPAfter

The long hash for the AEP result; guaranteed non-negative.

hashNotChangedSinceAfter

public final long hashNotChangedSinceAfter

The timestamp from the AEP result; guaranteed non-negative.

timestampAEIDBefore

public final long timestampAEIDBefore

The timestamp/hash for the AEIP in the AEP to which the diff is to be applied; guaranteed non-negative.

timestampAEIDAfter

public final long timestampAEIDAfter

The timestamp/hash for the AEIP in the AEP result; guaranteed non-negative.

lengthAEIDBefore

public final int lengthAEIDBefore

The exhibit count for the AEIP in the AEP to which the diff is to be applied; guaranteed non-negative.

lengthAEIDAfter

public final int lengthAEIDAfter

The exhibit count for the AEIP in the AEP result; guaranteed non-negative.

epgiDiff

private final EPGIDiff epgiDiff

The diff from the previous EPGI; may be null to represent no changes to EPGI value.

exhibitsDeleted

private transient java.util.Set<Name.ExhibitFull> exhibitsDeleted

The set of exhibits (full exhibit names) removed (or changed); may be null if no deletions/changes. Not serialised as-is.

Does not contain duplicates, nulls or invalid-syntax values.

This is all exhibits whose old definitions/data must be logically removed from the input AEP first.

exhibitsAdded

private transient java.util.Set<AllExhibitPropertiesDelta.Change> exhibitsAdded

The set of exhibits (full exhibit names) added (or changed); may be null if no additions/changes. Not serialised as-is.

Does not contain duplicates, nulls or invalid-syntax values.

This is all exhibits whose old definitions/data must be logically added to the input AEP after the exhibitsDeleted set has been removed.

serialVersionUID

private static final long serialVersionUID

Serialisation ID.

See Also:

Constant Field Values

AllExhibitPropertiesDelta

public AllExhibitPropertiesDelta()

Construct an empty instance. This nominally represents the null diff/change from one empty AEP instance to another empty AEP instance.

AllExhibitPropertiesDelta

public AllExhibitPropertiesDelta(long longHashAEPBefore,
                                 long longHashAEPAfter,
                                 long timestampAEIDBefore,
                                 long timestampAEIDAfter,
                                 int lengthAEIDBefore,
                                 int lengthAEIDAfter,
                                 long hashNotChangedSinceAfter,
                                 EPGIDiff epgiDiff,
                                 java.util.Set<Name.ExhibitFull> exhibitsDeleted,
                                 java.util.Set<AllExhibitPropertiesDelta.Change> exhibitsAdded)

Construct an instance. The Collection arguments are defensively copied.

The String and other complex values are assumed to already have been intern()ed as far as needed/possible, given that any diff instance may be short-lived.

writeObject

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

Write out a less-redundant form of our internal information. In particular, since deltas will not usually involve deletion of any exhibits, we make the no-deletions case take no space at all in the serialised form.

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.)

Throws:

java.io.InvalidObjectException

_computeChangeValues

private static java.util.Set<AllExhibitPropertiesDelta.Change> _computeChangeValues(AllExhibitProperties aep)

Create "change" values from AEP; never null. This is the set of values to be added to an empty AEP to regenerate this one (ignoring the EPGI).

createDiff

public static AllExhibitPropertiesDelta createDiff(AllExhibitProperties aep1,
                                                   AllExhibitProperties aep2,
                                                   boolean force)
                                            throws AllExhibitPropertiesDelta.DiffException

Create diff between two AEP instances. This creates a diff to be applied to an instance of the first argument to recreate the second argument.

This will refuse to create a diff if it seems that the diff is unlikely to be useful, for example:

• If one AEP has much more exhibits than the other (the diff may not be much smaller than sending the second AEP whole).

Parameters:

force - if true then force a diff to be produced even if this routine would normally refuse to do so on efficiency grounds

Throws:

AllExhibitPropertiesDelta.DiffException - if no diff can be generated or is unlikely to be worthwhile to use (eg would be more than a fraction of the size of the second AEP)

applyDiff

public static AllExhibitProperties applyDiff(AllExhibitProperties aep1,
                                             AllExhibitPropertiesDelta diff)
                                      throws AllExhibitPropertiesDelta.DiffException

Applies diff to an extant AEP instance to generate a new AEP instance; never null. The diff must only be applied to the same AEP instance value that the diff was generated from (ie an equal one).

Throws:

AllExhibitPropertiesDelta.DiffException - if the diff cannot be applied

toString

public final java.lang.String toString()

Human-readable summary.

Overrides:

toString in class java.lang.Object