/*
    * Copyright 1999-2006 Faculty of Mathematics, Physics and Informatics, Comenius
    * University, Bratislava. This file is protected by the Mozilla Public License
    * version 1.1 (the "License"); you may not use this file except in compliance
    * with the License. You may obtain a copy of the License at
    * http://euromath2.sourceforge.net/license.html 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 sk.uniba.euromath.document;
  import java.io.IOException;
  import java.util.Collection;
  import java.util.concurrent.locks.ReentrantLock;
  import javax.xml.XMLConstants;
  import javax.xml.namespace.QName;
  import org.w3c.dom.Attr;
  import org.w3c.dom.Element;
  import org.w3c.dom.Node;
  import sk.baka.ikslibs.DOMUtils;
  import sk.baka.ikslibs.modify.DOMMutils;
  import sk.baka.ikslibs.ptr.DomPointerFactory;
  import sk.baka.xml.gene.ExportException;
  import sk.baka.xml.gene.ExportUtils;
  /***
   * <p>
   * Serves for modifying document. Tracks changes in document, and makes them
   * consistent with 'splitted' images of document. Accessible from out of
   * document package. All functions work on DOM-level nodes. Thread safe.
   * </p>
   * <p>
   * This class is unchecked - it allows to set given text or modify document
   * structure even if the change violates the grammar rules. Caller should make
   * sure that the document is valid before the transformation execution.
   * </p>
   * <p>
   * WARNING: when modifying the document, then IDs pointing to nodes after node
   * being modified can become invalid (may denote a wrong node) - this happens
   * for example when the text/cdata/comment/pi node is deleted (for example, when
   * <code>null</code> value is given to a <code>setText()</code> function).
   * </p>
   * @author Martin Vysny
   */
  public final class DocumentModifier {
  	/***
  	 * Document.
  	 */
  	private final XMLAccess doc;
  	/***
  	 * Collections containing all opened views.
  	 */
  	private final Collection< ? extends DocumentView> views;
  	/***
  	 * Listens to the events.
  	 */
  	private final DocumentListeners listeners;
  	/***
  	 * This lock is locked when some thread starts the document modification,
  	 * and released when a thread finishes the modification. When the lock is
  	 * released, the document is transformed if there are no more threads
  	 * waiting for the modification.
  	 */
  	private final ReentrantLock currentModifierLock = new ReentrantLock();
  	/***
  	 * Constructs instance of document modifier.
  	 * @param doc modifies this document.
  	 * @param views collection of views, opened for this document. This table is
  	 * managed, and modified, by XMLAccess, DocumentModifier class doesn't
  	 * modify it.
  	 * @param listeners listens for document modifications
  	 */
  	DocumentModifier(XMLAccess doc, Collection< ? extends DocumentView> views,
  			DocumentListeners listeners) {
  		super();
  		this.doc = doc;
  		this.views = views;
  		this.listeners = listeners;
  	}
  	/***
  	 * <p>
  	 * Begins modification sequence. All modifications to document must be
  	 * enclosed with <code>startModify() .. endModify()</code> sequence. In
  	 * other words, modifying document when <code>isModifying()==false</code>
  	 * will result in <code>IllegalStateException</code>.
  	 * <code>startModify()</code> calls can be nested, i.e. it is possible to
  	 * call <code>startModify()</code> when <code>isModifying()</code>, but
  	 * every call to <code>startModify()</code> should be closed with
  	 * <code>endModify()</code>, otherwise document won't be never
  	 * transformed, and other threads will block forever.
  	 * </p>
  	 * <p>
  	 * Two threads cannot modify one document concurrently. If one thread is
  	 * currently modifying a document and second thread calls
  	 * <code>startModify()</code>, the function will block until current
  	 * thread finishes the modification.
  	 * </p>
  	 */
  	public void startModify() {
 		currentModifierLock.lock();
 		// this thread granted the right to modify the document.
 	}
 	/***
 	 * Ends modification of document. It may still be possible to edit document,
 	 * when every call to startModify() wasn't yet accompanied by endModify()
 	 * call. When last startModify() is closed by this call, transformation is
 	 * performed.
 	 * @throws ExportException when something goes wrong in the process of
 	 * transformation.
 	 */
 	public void endModify() throws ExportException {
 		ensureModify();
 		final boolean hasWaitingModifiers = currentModifierLock
 				.hasQueuedThreads();
 		final boolean unlocksLastLock = currentModifierLock.getHoldCount() <= 1;
 		// unlock the lock.
 		currentModifierLock.unlock();
 		// if more modifiers are waiting for the modification to start, quit
 		// immediately and let another thread execute startModify and gain the
 		// lock.
 		if (hasWaitingModifiers)
 			return;
 		if (unlocksLastLock) {
 			// if something changed then execute the transformation
 			if (doc.getSplittedChanges().hasChanges()) {
 				for (final DocumentView view : views) {
 					try {
 						view.export();
 					} catch (IOException ex) {
 						throw new ExportException("I/O error: " //$NON-NLS-1$
 								+ ex.getLocalizedMessage(), ex);
 					}
 				}
 				doc.getSplittedChanges().clear();
 				listeners.documentWasTransformed();
 			}
 		}
 	}
 	/***
 	 * Returns <code>true</code>, if document is being modified by caller
 	 * thread.
 	 * @return <code>true</code>, if document is being modified,
 	 * <code>false</code> otherwise.
 	 */
 	public boolean isModifying() {
 		return currentModifierLock.isHeldByCurrentThread();
 	}
 	/***
 	 * Ensures that document is being modified by caller thread. If not,
 	 * <code>IllegalStateException</code> is thrown.
 	 */
 	void ensureModify() {
 		if (!isModifying())
 			throw new IllegalStateException(
 					"Document is not currently being modified by this thread."); //$NON-NLS-1$
 	}
 	/***
 	 * Sets text of given node to given value. It may be pi, comment, attribute,
 	 * text or cdata node only.
 	 * @param node the text node, that receives new value.
 	 * @param value new text value. <code>null</code> value is equivalent to
 	 * an empty string.
 	 */
 	public void setText(Node node, String value) {
 		checkReserved(node);
 		DOMMutils.setText(node, value);
 	}
 	/***
 	 * Removes given node from the document. If both previous and next sibling
 	 * of the node are of same text type (text or cdata) then these nodes are
 	 * merged into one.
 	 * @param node the node, that will be removed. Its id is removed aswell, but
 	 * the id of descendants is not removed.
 	 */
 	public void remove(Node node) {
 		checkReserved(node);
 		DOMMutils.remove(node);
 	}
 	/***
 	 * Check if such node is reserved and cannot be created in the document.
 	 * @param node node to check.
 	 * @throws IllegalArgumentException if node is reserved.
 	 */
 	private void checkReserved(final Node node) {
 		checkReserved(node.getNamespaceURI(), node.getNodeType());
 	}
 	/***
 	 * Check if such node is reserved and cannot be created in the document.
 	 * @param namespace the namespace of the node
 	 * @param nodeType the type of the node.
 	 * @throws IllegalArgumentException if node is reserved.
 	 */
 	private void checkReserved(final String namespace, final short nodeType) {
 		if ((nodeType != Node.ATTRIBUTE_NODE)
 				&& (nodeType != Node.ELEMENT_NODE))
 			return;
 		if (DOMUtils.equalsURI(namespace, ExportUtils.GENE_ID_ATTRIBUTE_QNAME
 				.getNamespaceURI()))
 			throw new IllegalArgumentException(
 					"Namespace " + ExportUtils.GENE_ID_ATTRIBUTE_QNAME.getNamespaceURI() + " is reserved."); //$NON-NLS-1$ //$NON-NLS-2$
 	}
 	/***
 	 * Creates an attribute. If attribute with given local name and namespace is
 	 * already present in context node, its value is modified instead - prefix
 	 * is not changed.
 	 * @param id id of element, that contains the attribute.
 	 * @param prefix prefix of qname of attribute. See
 	 * <code>NamespaceManager</code> for details.
 	 * @param localName local name of attribute.
 	 * @param namespace namespace of attribute.
 	 * @param value new value for attribute.
 	 * @return ID of newly created attribute.
 	 */
 	public String createAttribute(String id, String prefix, String localName,
 			String namespace, String value) {
 		return createAttribute(doc.getIDManager().getElement(id), prefix,
 				localName, namespace, value);
 	}
 	/***
 	 * Creates an attribute. If attribute with given local name and namespace is
 	 * already present in context node, its value is modified instead - prefix
 	 * is not changed.
 	 * @param id id of element, that contains the attribute.
 	 * @param qname qualified name of the attribute
 	 * @param value new value for attribute.
 	 * @return ID of newly created attribute.
 	 */
 	public String createAttribute(String id, QName qname, String value) {
 		return createAttribute(id, qname.getPrefix(), qname.getLocalPart(),
 				qname.getNamespaceURI(), value);
 	}
 	/***
 	 * Creates an attribute. If attribute with given local name and namespace is
 	 * already present in context node, its value is modified instead - prefix
 	 * is not changed.
 	 * @param e element, that contains the attribute.
 	 * @param qname qualified name of the attribute
 	 * @param value new value for attribute.
 	 * @return ID of newly created attribute.
 	 */
 	public String createAttribute(Element e, QName qname, String value) {
 		return createAttribute(e, qname.getPrefix(), qname.getLocalPart(),
 				qname.getNamespaceURI(), value);
 	}
 	/***
 	 * Creates an attribute. If attribute with given local name and namespace is
 	 * already present in context node, its value is modified instead - prefix
 	 * is not changed.
 	 * @param e element, that contains the attribute.
 	 * @param prefix prefix of qname of attribute. See
 	 * <code>NamespaceManager</code> for details.
 	 * @param localName local name of attribute.
 	 * @param namespace namespace of attribute.
 	 * @param value new value for attribute.
 	 * @return ID of newly created attribute.
 	 */
 	public String createAttribute(Element e, String prefix, String localName,
 			String namespace, String value) {
 		// forbid creating reserved attribute
 		checkReserved(namespace, Node.ATTRIBUTE_NODE);
 		// if namespace is equal to namespace of parent element, then null it.
 		if (DOMUtils.equalsURI(namespace, e.getNamespaceURI())) {
 			namespace = ""; //$NON-NLS-1$
 			prefix = XMLConstants.DEFAULT_NS_PREFIX;
 		}
 		final Attr attr = DOMMutils.createAttribute(e, prefix, localName,
 				namespace, value);
 		return doc.getIDManager().getID(attr);
 	}
 	/***
 	 * Replaces the node with another node. <code>newNode</code> must have
 	 * <code>null</code> parent or it must be from another document.
 	 * @param node the node to be replaced.
 	 * @param newNode the node will be replaced with this node. If
 	 * <code>null</code> then given node is removed. If not from our document
 	 * then it is automatically imported.
 	 */
 	public void replaceNode(Node node, Node newNode) {
 		if (newNode == null) {
 			remove(node);
 			return;
 		}
 		doc.checkNode(node);
 		if ((newNode.getParentNode() != null) && (doc.isOurNode(newNode)))
 			throw new IllegalArgumentException(
 					"The replacing node is present in our document"); //$NON-NLS-1$
 		ensureModify();
 		// remove old node from the document
 		final Node nextSibling = node.getNextSibling();
 		final Node parent = node.getParentNode();
 		parent.removeChild(node);
 		// insert new node into its place
 		Node replaceBy = newNode;
 		if (!doc.isOurNode(replaceBy))
 			replaceBy = doc.getDocument().importNode(newNode, true);
 		DOMMutils.insertNode(replaceBy, DomPointerFactory.create(nextSibling),
 				true);
 	}
 }