Area Checkpoints

From HEWIKI
Jump to: navigation, search

Contents

Overview

The Area Server Checkpoint System implements the mechanics for creating, listing and restoring area server content backups. This page describes how to access the Area Server Checkpoint system via the Hotspot Interface and HSL.

What problem(s) does this solve?

What problem(s) does this not solve?

Concepts

Usage

Interaction with the Area Server Checkpoint System is accomplished via its exposed HSL interface or through the GUI provided by Clean Engine's HotSpot Menu. No matter which interface is used, the Area Server will refuse all checkpoint operations if the user is not currently in an Edit Instance.

HotSpot Menu

Areacheckpoints-tab.jpg

Opening the Area Server Checkpoint System GUI requires you access the hidden HotSpot Menu toolbox located in the top left corner of the render window with a cntrl-shift-leftclick or typing F5. On the TOOLs tab, under the Areas category, you will find an option to open the Area Checkpoint GUI. In keeping with the Area Server's Edit Instance only restriction for checkpoint interaction, the Area Checkpoint GUI will only open when the user is in an Edit Instance.

Areacheckpoint-checkpointlist.jpg

Listing checkpoints

The Checkpoint System GUI retrieves a list of all checkpoints for the current area when it is opened. This list is updated when you save a new checkpoint. Checkpoints created through this GUI record the time the checkpoint was created and the name of the user that created the checkpoint within the checkpoint's label. When the GUI displays the checkpoint list the checkpoint's string label, the recorded creation time and the user name are parsed out and placed within their respective columns.

Just as with other lists in HeroEngine, the list of checkpoints can be culled by typing into the search box. Text entered into the search box is compared as a phrase against the label and account column contents. Searching is automatically triggered by entering text into the search box, requiring no user intervention. The current search can be canceled by erasing all entered text or pressing the icon to the immediate left of the search box.

Auto-saves

As a safety precaution, an area checkpoint is automatically saved any time a restoration is requested through the Checkpoint System GUI. Over time the list of auto-saves can become quite long, impairing visually scanning the list of non-auto-save checkpoints. Clicking the "Hide Auto-Saves" checkbox toggles suppression of the display of auto-save checkpoints. Auto-save checkpoints, like any other checkpoint, cannot be deleted.

Saving a new checkpoint

To save a checkpoint of the area, click on the "New" button. The Checkpoint System GUI will pop up a text input box requiring a name/description for the checkpoint. This name is displayed in the "description" column of the checkpoint list form. After a description is provided for the checkpoint, the asynchronous checkpoint creation process begins.

Restoring to a checkpoint

Areacheckpoint-restore.jpg

To restore an area to a checkpoint, select the checkpoint you wish to restore to and click on the "Restore" button. The Checkpoint System GUI will pop up a box asking whether an additive, destructive, or restricted restore is desired. After the restoration type is selected, the asynchronous checkpoint restoration process begins. While a checkpoint is being restored to the HeroBlade screen is dimmed and editing is disallowed. If checkpoint restoration succeeded the area's contents will be altered appropriately.


Via HSL

The Area Server Checkpoint System can also be accessed via external functions provided by the edit instance of area servers. Due to the asynchronous nature of checkpoint operations, the HSL functions do not return success information and instead rely on a callback node that is supplied to the external functions.

List Area Checkpoints

This function retrieves a list of all checkpoints created for the current Area. The supplied callerRef is given to the checkpoint system and used to return the list (as a list of String containing the labels for the checkpoints) in a callback.

external function ListAreaCheckpoints(callerRef as NodeRef)

Save Area Checkpoint

This function creates a new checkpoint with the Area's current contents. The checkpointLabel is applied to the newly created checkpoint's entry in the checkpoint catalog. The supplied callerRef node is given to the checkpoint system and will be used for all callback interaction during the checkpoint creation process.

external function SaveAreaCheckpoint(checkpointLabel as String, callerRef as NodeRef)

Restore Area Checkpoint

This function selects an area checkpoint to restore from. The supplied callerRef node is given to the checkpoint system and will be used for all callback interaction during the checkpoint restoration process. The decision to preform a destructive or additive checkpoint is made by passing TRUE or FALSE as the allowDestructiveChanges parameter

external function RestoreAreaCheckpoint(checkpointVersionID as ID, callerRef as NodeRef, allowDestructiveChanges as Boolean)

Checkpoint callbacks

The Checkpoint system utilizes several callback functions on the supplied callerRef node to query decisions while it works and to communicate the final status of each operation. The list of methods required to exist for callerRef are:

method _QueryNodeCheckpointable( nodeID as ID ) as Boolean

This method is called for each node, identified by its ID nodeID, encountered while the checkpoint system crawls through an area's node hierarchy. The return value determines whether or not the node will be saved in the checkpoint file.

method _QueryAssociationCheckpointable( sourceNodeID as ID, targetNodeID as ID, associationType as ID ) as Boolean

This method is called for each association encountered while the checkpoint system crawls through an area's checkpoint eligible nodes. The return value determines whether or not the association will be saved in the checkpoint file. This method is NOT called for hard associations, as they are always written out if their targets are checkpoint eligible nodes. The parameters sourceNodeID, targetNodeID and associationType describe, by ID, the source, target and type of the association respectively.

method _QueryCheckpointedNodeUserData( nodeID as ID ) as String

This method is called for each checkpoint eligible node, identified by its ID nodeID, from the area. The returned string is saved alongside the node in the checkpoint file and fed back to the _QueryCheckpointRestoreAfterNodeParsed callback function on checkpoint node load.

method _SaveAreaCheckpointResult( checkpointSaved as Boolean, statusMessage as String )

This method is called when a requested Checkpoint save has completed. The checkpointSaved boolean denotes whether the save was successful. The statusMessage string contains a message describing the success or failure in greater detail.

method _ListAreaCheckpointVersions( versionsString as List of String )

This method is called when a requested Checkpoint list has completed. The versionsString contains a list of checkpoint labels as strings. The index of each label in the list corresponds to the ID used to load that checkpoint via RestoreAreaCheckpoint.

method _QueryCheckpointRestoreAfterDiscrepancy( discrepancies as List of String ) as Boolean

This method is called on checkpoint load when a discrepancy is detected between the Area Server's DOM and the DOM mini-dump saved within the checkpoint file. The return value determines if the checkpoint restore should continue. The discrepancies parameter is a list of strings each of which describes a detected discrepancy in a CLI command like manner. The discrepancy values are:

DACD - Could not list class defs
DCD ID# - Class has been deleted
MDT ID# - Definition type has changed
MDN ID# - Definition name has changed
MDD ID# - Definition description has changed
MCU ID# - Class uber type has changed
MCRP ID# PARENT# - Class parent has been removed
MCAP ID# PARENT# - Class parent has been added
DAFD - Could not list field defs
DFD ID# - Field has been deleted
MFL ID# - Field lightweight flag has changed
MFVT ID# - Field value type has changed
MFR ID# - Field reflect to client has changed
MFW ID# - Field write strategy has changed
MFS ID# - Field watching script has changed
MFP ID# - Field privacy has changed
DAED - Could not list enum defs
DED ID# - Enum has been deleted
MERV ID# VALUESTRING - Enum value has been removed
MEAV ID# VALUESTRING - Enum value has been added


method _QueryCheckpointRestoreAfterNodeParsed( nodeID as ID, userData as String ) as Boolean

This method is called after a node, identified by its ID nodeID, has been parsed from the checkpoint file. The nodeID is not necessarily a valid node ID in the Area Server's GOM as it may have been removed since the checkpoint file was written. The User Data string is the value supplied by the call to _QueryCheckpointedNodeUserData during checkpoint creation. The return value determines if the checkpoint restore should continue.

method _QueryCheckpointRestoreAfterNodeLoaded( nodeID as ID, userData as String ) as Boolean

This method is called after a node, identified by its ID nodeID, has been parsed from the checkpoint file and reloaded into the Area Server's GOM. It is NOT called for nodes whose class or field value makeup only changed. The userData string is the value supplied by the call to _QueryCheckpointedNodeUserData during checkpoint creation. The return value determines if the checkpoint restore should continue.

method _QueryRemoveNonCheckpointNode( nodeID as ID ) as Boolean

This method is called during a destructive restore when a node, identified by its ID nodeID, is encountered in the Area Server's GOM that was not in the checkpoint. The return value specifies whether the node should be deleted from the Area Server's GOM.

method _RestoreAreaCheckpointResult( checkpointLoaded as Boolean, statusMessage as String )

This method is called when a requested Checkpoint restore has completed. The checkpointLoaded boolean denotes whether the save was successful. The statusMessage string contains a message describing the success or failure in greater detail.

Example

First a new checkpoint is created:

callbackNode as NodeRef of Class myCheckpointCallbackClass
SaveAreaCheckpoint("ImportantCheckpoint", callbackNode)

Second the checkpoint list is queried:

callbackNode as NodeRef of Class myCheckpointCallbackClass
ListAreaCheckpoints(callbacknode)

And the list of checkpoints is returned to myCheckpointCallbackClass' _ListAreaCheckpointVersions implementation:

 method _ListAreaCheckpointVersions( versionsString as List of String )
  checkPointID as ID = 1
  foreach s in versionsString
   if ("ImportantCheckpoint" == s)
     // Finally if the checkpoint we're interested in is found, it is restored to with an additive restore
     callbackNode as NodeRef of Class myCheckpointCallbackClass
     RestoreAreaCheckpoint(checkPointID, callbackNode, false)
     return
   .
   checkPointID += 1
  .
 .

Area Checkpoint restoration example

Say you save a checkpoint, when an object (the blue sphere) is on the left side of the area:

Areacheckpoint-scenestart.jpg


Then you move that sphere to another location, and add a new object:

Areacheckpoint-sceneedit.jpg


You then do a restore, in one of two possible ways, an additive restore, or a destructive restore:

After an additive restore, the original sphere is back in its original location, but the newer object is still in the area as well.
After a destructive restore, the newer object is gone, and only the sphere remains, in the location that it was when the checkpoint was saved.
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox