Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.jackrabbit.jcr2spi.state; import java.util.Collection; import java.util.Iterator; import java.util.LinkedHashSet; import java.util.Set; import javax.jcr.InvalidItemStateException; import javax.jcr.ItemExistsException; import javax.jcr.RepositoryException; import javax.jcr.nodetype.ConstraintViolationException; import org.apache.commons.collections.iterators.IteratorChain; import org.apache.jackrabbit.jcr2spi.hierarchy.HierarchyEntry; import org.apache.jackrabbit.jcr2spi.hierarchy.NodeEntry; import org.apache.jackrabbit.jcr2spi.hierarchy.PropertyEntry; import org.apache.jackrabbit.jcr2spi.operation.Operation; import org.apache.jackrabbit.spi.Name; import org.apache.jackrabbit.spi.QNodeDefinition; import org.apache.jackrabbit.spi.QPropertyDefinition; import org.apache.jackrabbit.spi.QValue; import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** * <code>TransientItemStateManager</code> adds support for transient changes on * {@link ItemState}s and also provides methods to create new item states. * While all other modifications can be invoked on the item state instances itself, * creating a new node state is done using * {@link #createNewNodeState(Name, String, Name, QNodeDefinition, NodeState)} * and * {@link #createNewPropertyState(Name, NodeState, QPropertyDefinition, QValue[], int)}. */ public class TransientItemStateManager implements ItemStateCreationListener { /** * Logger instance for this class. */ private static final Logger log = LoggerFactory.getLogger(TransientItemStateManager.class); /** * Added states */ private final Set<ItemState> addedStates = new LinkedHashSet<ItemState>(); /** * Modified states */ private final Set<ItemState> modifiedStates = new LinkedHashSet<ItemState>(); /** * Removed states */ private final Set<ItemState> removedStates = new LinkedHashSet<ItemState>(); /** * Stale states */ private final Set<ItemState> staleStates = new LinkedHashSet<ItemState>(); /** * Set of operations */ private final Set<Operation> operations = new LinkedHashSet<Operation>(); /** * */ TransientItemStateManager() { } /** * @return the operations that have been recorded until now. */ Iterator<Operation> getOperations() { return operations.iterator(); } /** * Add the given operation to the list of operations to be recorded within * this TransientItemStateManager. * * @param operation */ void addOperation(Operation operation) { operations.add(operation); } /** * @return <code>true</code> if this transient ISM has pending changes. */ boolean hasPendingChanges() { return !operations.isEmpty(); } /** * Create the change log for the tree starting at <code>target</code>. This * includes a check if the ChangeLog to be created is totally 'self-contained' * and independent; items within the scope of this update operation (i.e. * below the target) must not have dependencies outside of this tree (e.g. * moving a node requires that the target node including both old and new * parents are saved). * * @param target * @param throwOnStale Throws InvalidItemStateException if either the given * <code>ItemState</code> or any of its descendants is stale and the flag is true. * @return * @throws InvalidItemStateException if a stale <code>ItemState</code> is * encountered while traversing the state hierarchy. The <code>changeLog</code> * might have been populated with some transient item states. A client should * therefore not reuse the <code>changeLog</code> if such an exception is thrown. * @throws RepositoryException if <code>state</code> is a new item state. */ ChangeLog getChangeLog(ItemState target, boolean throwOnStale) throws InvalidItemStateException, ConstraintViolationException, RepositoryException { // fail-fast test: check status of this item's state if (target.getStatus() == Status.NEW) { String msg = "Cannot save/revert an item with status NEW (" + target + ")."; log.debug(msg); throw new RepositoryException(msg); } if (throwOnStale && Status.isStale(target.getStatus())) { String msg = "Attempt to save/revert an item, that has been externally modified (" + target + ")."; log.debug(msg); throw new InvalidItemStateException(msg); } Set<Operation> ops = new LinkedHashSet<Operation>(); Set<ItemState> affectedStates = new LinkedHashSet<ItemState>(); HierarchyEntry he = target.getHierarchyEntry(); if (he.getParent() == null) { // the root entry -> the complete change log can be used for // simplicity. collecting ops, states can be omitted. if (throwOnStale && !staleStates.isEmpty()) { String msg = "Cannot save changes: States has been modified externally."; log.debug(msg); throw new InvalidItemStateException(msg); } else { affectedStates.addAll(staleStates); } ops.addAll(operations); affectedStates.addAll(addedStates); affectedStates.addAll(modifiedStates); affectedStates.addAll(removedStates); } else { // not root entry: // - check if there is a stale state in the scope (save only) if (throwOnStale) { for (ItemState state : staleStates) { if (containedInTree(target, state)) { String msg = "Cannot save changes: States has been modified externally."; log.debug(msg); throw new InvalidItemStateException(msg); } } } // - collect all affected states within the scope of save/undo Iterator[] its = new Iterator[] { addedStates.iterator(), removedStates.iterator(), modifiedStates.iterator() }; IteratorChain chain = new IteratorChain(its); if (!throwOnStale) { chain.addIterator(staleStates.iterator()); } while (chain.hasNext()) { ItemState state = (ItemState) chain.next(); if (containedInTree(target, state)) { affectedStates.add(state); } } // - collect the set of operations and // check if the affected states listed by the operations are all // listed in the modified,removed or added states collected by this // changelog. for (Operation op : operations) { Collection<ItemState> opStates = op.getAffectedItemStates(); for (ItemState state : opStates) { if (affectedStates.contains(state)) { // operation needs to be included if (!affectedStates.containsAll(opStates)) { // incomplete changelog: need to save a parent as well String msg = "ChangeLog is not self contained."; throw new ConstraintViolationException(msg); } // no violation: add operation an stop iteration over // all affected states present in the operation. ops.add(op); break; } } } } ChangeLog cl = new ChangeLog(target, ops, affectedStates); return cl; } /** * Creates a new transient {@link NodeState} that does not overlay any other * {@link NodeState}. * * @param nodeName the name of the <code>NodeState</code> to create. * @param uniqueID the uniqueID of the <code>NodeState</code> to create or * <code>null</code> if the created <code>NodeState</code> * cannot be identified by a unique ID. * @param nodeTypeName name of the node type of the new node state. * @param definition The definition for the new node state. * @param parent the parent of the new node state. * @return a new transient {@link NodeState}. */ NodeState createNewNodeState(Name nodeName, String uniqueID, Name nodeTypeName, QNodeDefinition definition, NodeState parent) throws RepositoryException { NodeEntry ne = ((NodeEntry) parent.getHierarchyEntry()).addNewNodeEntry(nodeName, uniqueID, nodeTypeName, definition); try { parent.markModified(); } catch (RepositoryException e) { ne.remove(); throw e; } return ne.getNodeState(); } /** * Creates a new transient property state for a given <code>parent</code> * node state. * * @param propName the name of the property state to create. * @param parent the node state where to the new property is added. * @param definition * @return the created property state. * @throws ItemExistsException if <code>parent</code> already has a property * with the given name. * @throws ConstraintViolationException * @throws RepositoryException */ PropertyState createNewPropertyState(Name propName, NodeState parent, QPropertyDefinition definition, QValue[] values, int propertyType) throws ItemExistsException, ConstraintViolationException, RepositoryException { // NOTE: callers must make sure, the property type is not 'undefined' NodeEntry nodeEntry = (NodeEntry) parent.getHierarchyEntry(); PropertyEntry pe = nodeEntry.addNewPropertyEntry(propName, definition, values, propertyType); try { parent.markModified(); } catch (RepositoryException e) { pe.remove(); throw e; } return pe.getPropertyState(); } /** * Disposes this transient item state manager. Clears all references to * transiently modified item states. */ void dispose() { addedStates.clear(); modifiedStates.clear(); removedStates.clear(); staleStates.clear(); // also clear all operations operations.clear(); } /** * Remove the states and operations listed in the changeLog from internal * list of modifications. * * @param subChangeLog */ void dispose(ChangeLog subChangeLog) { Set<ItemState> affectedStates = subChangeLog.getAffectedStates(); addedStates.removeAll(affectedStates); modifiedStates.removeAll(affectedStates); removedStates.removeAll(affectedStates); staleStates.removeAll(affectedStates); operations.removeAll(subChangeLog.getOperations()); } /** * A state has been removed. If the state is not a new state * (not in the collection of added ones), then remove * it from the modified states collection and add it to the * removed states collection. * * @param state state that has been removed */ private void removed(ItemState state) { if (!addedStates.remove(state)) { modifiedStates.remove(state); } removedStates.add(state); } /** * * @param parent * @param state * @return */ private static boolean containedInTree(ItemState parent, ItemState state) { HierarchyEntry he = state.getHierarchyEntry(); HierarchyEntry pHe = parent.getHierarchyEntry(); // short cuts first if (he == pHe || he.getParent() == pHe) { return true; } if (!parent.isNode() || he == pHe.getParent()) { return false; } // none of the simple cases: walk up hierarchy HierarchyEntry pe = he.getParent(); while (pe != null) { if (pe == pHe) { return true; } pe = pe.getParent(); } // state isn't descendant of 'parent' return false; } //-----------------------------------------< ItemStateLifeCycleListener >--- /** * Depending on status of the given state adapt change log. * E.g. a revert on states will reset the status from 'existing modified' to * 'existing'. A state which changes from 'existing' to 'existing modified' * will go into the modified set of the change log, etc. * * @see ItemStateLifeCycleListener#statusChanged(ItemState, int) */ public void statusChanged(ItemState state, int previousStatus) { /* Update the collections of states that were transiently modified. NOTE: cleanup of operations is omitted here. this is expected to occur upon {@link ChangeLog#save()} and {@link ChangeLog#undo()}. External modifications in contrast that clash with transient modifications render the corresponding states stale. */ switch (state.getStatus()) { case (Status.EXISTING): switch (previousStatus) { case Status.EXISTING_MODIFIED: // was modified and got persisted or reverted modifiedStates.remove(state); break; case Status.EXISTING_REMOVED: // was transiently removed and is now reverted removedStates.remove(state); break; case Status.STALE_MODIFIED: // was modified and stale and is now reverted staleStates.remove(state); break; case Status.NEW: // was new and has been saved now addedStates.remove(state); break; //default: // INVALIDATED, MODIFIED ignore. no effect to transient modifications. // any other status change is invalid -> see Status#isValidStatusChange(int, int } break; case Status.EXISTING_MODIFIED: // transition from EXISTING to EXISTING_MODIFIED modifiedStates.add(state); break; case (Status.EXISTING_REMOVED): // transition from EXISTING or EXISTING_MODIFIED to EXISTING_REMOVED removed(state); break; case (Status.REMOVED): switch (previousStatus) { case Status.EXISTING_REMOVED: // was transiently removed and removal was persisted. // -> ignore break; case Status.NEW: // a new entry was removed again: remember as removed // in order to keep the operations and the affected // states in sync removed(state); break; } // in any case: stop listening to status changes state.removeListener(this); break; case Status.STALE_DESTROYED: case Status.STALE_MODIFIED: /** state is stale due to external modification -> move it to the collection of stale item states. validation omitted for only 'existing_modified' states can become stale see {@link Status#isValidStatusChange(int, int)} */ modifiedStates.remove(state); staleStates.add(state); break; case Status.MODIFIED: case Status.INVALIDATED: // MODIFIED, INVALIDATED: ignore. log.debug("Item " + state.getName() + " changed status from " + Status.getName(previousStatus) + " to " + Status.getName(state.getStatus()) + "."); break; default: log.error("ItemState " + state.getName() + " has invalid status: " + state.getStatus()); } } //-----------------------------------------< ItemStateCreationListener >--- /** * @see ItemStateCreationListener#created(ItemState) */ public void created(ItemState state) { // new state has been created if (state.getStatus() == Status.NEW) { addedStates.add(state); } } }