To create a new version of a versionable node N, the application calls N.checkin. If N is already checked-in, this method has no effect but simply returns the current base version of this node. If N is not versionable then a UnsupportedRepositoryOperationException is thrown. Otherwise, the following preconditions must hold:
N must not have any unsaved changes pending, otherwise an InvalidItemStateException is thrown.
N's jcr:mergeFailed (multi-value) property must not be present, otherwise a VersionException is thrown (notice that this is enforced in any case due to the ABORT setting of the jcr:mergeFailed property's OnParentVersion attribute).
Given these preconditions, N.checkin will cause the following series of events:
A new nt:version node V is created and added as a child node to VH, the nt:versionHistory pointed to by N’s jcr:versionHistory property.
N’s current jcr:predecessors property is copied to V, and N's jcr:predecessors property is then set to the empty array (it is a multi-value property, therefore it can be set to empty). Note that N's jcr:predecessors property also forms part of the frozen state of N (because it has an OnParentVersion attribute of COPY) and therefore will also be copied to V/jcr:frozenNode.
A reference to V is added to the jcr:successors property of each of the versions identified in V’s jcr:predecessors property.
N’s jcr:baseVersion property is set to refer to V.
N’s jcr:isCheckedOut property is set to false.
The state of N is recorded in the form of the jcr:frozenNode child of V. The extent of the state stored (i.e. exactly which child items are included and which ignored, etc.) will typically be partial, as prescribed by the OnParentVersion attribute of each of N’s child items. See 8.2.11 OnParentVersion Attribute, for the details. The jcr:primaryType, jcr:mixinTypes and jcr:uuid properties of N are copied over to the child jcr:frozenNode of V but renamed to jcr:frozenPrimaryType, jcr:frozenMixinTypes and jcr:frozenUuid to avoid conflict with jcr:frozenNode's own properties with these names.
V is given a automatically generated name. How this is done is implementation specific.
The node N and its connected non-versionable subtree become read-only. N's connected non-versionable subtree is the set of non-versionable descendant nodes reachable from N through child links without encountering any versionable nodes. In other words, the read-only status flows down from the checked-in node along every child link until either a versionable node is encountered or an item with no children is encountered.
Read-only status means that an item cannot be altered by the client using standard API methods (addNode, setProperty, etc.). The only exceptions to this rule are the restore9, Node.merge and Node.update operations; these do not respect read-only status due to check-in. Note that remove of a read-only node is possible, as long as its parent is not read-only (since removal is an alteration of the parent node).
This method acts directly on the workspace and the version storage. All changes are persisted immediately. There is no need to call save.