7.1.3.3 Invalid Items

Methods of an Item object (i.e., Node or Property) may throw an InvalidItemStateException in certain circumstances.

The first case is if Item.remove has been called on the item. In this case any subsequent calls to any read or write methods or invocations of save or refresh on that Item will throw an InvalidItemStateException.

Before the removal is persisted (by a save on the parent of the removed node) it may be cancelled by a refresh(false) on the parent of the removed node. This has the effect of reverting the parent node to its current saved state in the workspace. At this point the invalid Item object may become valid again, or the repository may require a new Item object to be acquired. Which approach is taken is a matter of implementation.

An InvalidItemStateException may be thrown on a write method of an Item if the change being made would (upon save) conflict with a change made, and persisted, through another Session. If detection of the conflict is only possible at save-time, then save will throw an InvalidItemStateException.

Whether a conflict is detected when the change is made to the Item or later, when an attempt is made to save that change, depends on the implementation. The key issue is when a particular Session sees changes made in the persistent storage by other sessions.