The purpose behind the transient storage in the session is to provide a space in which complex changes can be made to content without having these changes validated at every step. When a node/property structure is fully assembled it can be saved and validated against node type and other constraints. This allows structures of nodes and properties to be temporarily invalid while they are being built.
The methods that write to the transient layer are:
Node.addNode, setProperty, orderBefore, addMixin and
removeMixin.
Property.setValue.
Item.remove.
Session.move and importXML.
Query.storeAsNode.
Changes made though these methods will only be pushed to the workspace when a save is called that includes the change within its scope.
Session.save persists all pending changes currently stored in the Session object. Conversely, Session.refresh(false) discards all pending changes currently stored in the Session.
For more fine-grained control over which changes are persisted or discarded, the methods Item.save and Item.refresh(false) are also provided. Item.save saves all pending changes that apply to that particular item and its subtree. Analogously, Item.refresh discards all pending changes that apply to that item and its subtree.