/*
    * 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.EnumSet;
  import java.util.concurrent.locks.ReentrantLock;
  import javax.xml.XMLConstants;
  import javax.xml.namespace.QName;
  import org.w3c.dom.Attr;
  import org.w3c.dom.DocumentFragment;
  import org.w3c.dom.Element;
  import org.w3c.dom.Node;
  import org.w3c.dom.Text;
  import sk.baka.ikslibs.DOMUtils;
  import sk.baka.ikslibs.interval.DOMInterval;
  import sk.baka.ikslibs.levelmapper.NodeListID;
  import sk.baka.ikslibs.modify.DOMMutils;
  import sk.baka.ikslibs.ptr.DOMPoint;
  import sk.baka.ikslibs.ptr.DomPointer;
  import sk.baka.ikslibs.ptr.DomPointerFactory;
  import sk.baka.ikslibs.ptr.DomPointerFlag;
  import sk.baka.ikslibs.ref.EntityManager;
  import sk.baka.xml.gene.ExportException;
  import sk.uniba.euromath.Const;
  import sk.uniba.euromath.tools.StringTools;
  /***
   * <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 DomCore 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(DomCore 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, denoted by given id, to given value. It may be pi, comment or
 	 * attribute node.
 	 * @param id id of text node, that receives new value.
 	 * @param value new text value. <code>null</code> value is equivalent to
 	 * an empty string.
 	 * @deprecated
 	 */
 	@Deprecated
 	public void setText(String id, String value) {
 		NodeListID list = doc.getIDManager().getNode(id);
 		DOMMutils.setText(list, value);
 	}
 	/***
 	 * 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);
 	}
 	/***
 	 * Splits the text/cdata node at the specified position. If pos is equal to
 	 * zero or length of textual value of given text then nothing happens. The
 	 * node denoted by given id is not moved, only its textual value is changed.
 	 * @param id the id of the text/cdata node
 	 * @param pos zero-based position where the text shall be splitted.
 	 * @return a second half of the splitted node. It may be <code>null</code>
 	 * when no splitting occured.
 	 * @deprecated
 	 */
 	@Deprecated
 	public Text splitText(String id, int pos) {
 		NodeListID list = doc.getIDManager().getNode(id);
 		return DOMMutils.splitText(list.getPointer(pos, true, true));
 	}
 	/***
 	 * Splits the text/cdata node at the specified position. If pos is equal to
 	 * zero or length of textual value of given text then nothing happens. The
 	 * node denoted by given id is not moved, only its textual value is changed.
 	 * @param text the text/cdata node
 	 * @param pos zero-based position where the text shall be splitted.
 	 * @return a second half of the splitted node. It may be <code>null</code>
 	 * when no splitting occured.
 	 * @deprecated
 	 */
 	@Deprecated
 	public Text splitText(Text text, int pos) {
 		return DOMMutils.splitText(text, pos);
 	}
 	/***
 	 * Splits the text/cdata node at the specified position. If pos is equal to
 	 * zero or length of textual value of given text then nothing happens. The
 	 * node denoted by given id is not moved, only its textual value is changed.
 	 * @param ptr the pointer pointing into the text/cdata node.
 	 * @return a second half of the splitted node. It may be <code>null</code>
 	 * when no splitting occured.
 	 * @deprecated
 	 */
 	@Deprecated
 	public Text splitText(DomPointer ptr) {
 		return DOMMutils.splitText(ptr);
 	}
 	/***
 	 * Inserts text into element, depending on given parameters. If ip points
 	 * into text, then that text is modified instead. If ip points to a location
 	 * next to node with equal type, then that text is modified instead.
 	 * @param ip insert point, where to insert new text.
 	 * @param contextId the context element, where new text must be inserted.
 	 * @param value new text value. if <code>null</code> or empty string ("")
 	 * is given, then nothing is created.
 	 * @param type type of created node, one of <code>Node.TEXT_NODE</code> or
 	 * <code>Node.CDATA_SECTION_NODE</code> constants. When modifying text,
 	 * this parameter is ignored.
 	 * @return id of newly created text element, or id of modified element. If
 	 * value is empty or null, then <code>null</code> is returned.
 	 * @throws DocumentException when element with given id doesn't exist or it
 	 * doesn't denote regular element.
 	 * @deprecated
 	 */
 	@Deprecated
 	public String insertText(DOMPoint ip, String contextId, String value,
 			short type) throws DocumentException {
 		return insertText(ip, doc.getContent().getElement(contextId), value,
 				type);
 	}
 	/***
 	 * Inserts text into element, depending on given parameters. If ip points
 	 * into text, then that text is modified instead. If ip points to a location
 	 * next to node with equal type, then that text is modified instead.
 	 * @param point insert point, where to insert new text. It must not point
 	 * into an entity.
 	 * @param value new text value. if <code>null</code> or empty string ("")
 	 * is given, then nothing is created.
 	 * @param type type of created node, one of <code>Node.TEXT_NODE</code> or
 	 * <code>Node.CDATA_SECTION_NODE</code> constants. When modifying text,
 	 * this parameter is ignored.
 	 * @return id of newly created text element, or id of modified element. If
 	 * value is empty or null, then <code>null</code> is returned.
 	 * @deprecated
 	 */
 	@Deprecated
 	public String insertText(final DomPointer point, final String value,
 			short type) {
 		final Node n= DOMMutils.insertText(point, value, type);
 		if(n==null)return null;
 		return doc.getIDManager().getID(n);
 	}
 	/***
 	 * Inserts text into element, depending on given parameters. If ip points
 	 * into text, then that text is modified instead. If ip points to a location
 	 * next to node with equal type, then that text is modified instead.
 	 * @param ip insert point, where to insert new text.
 	 * @param contextElement the context element, where new text must be
 	 * inserted.
 	 * @param value new text value. if <code>null</code> or empty string ("")
 	 * is given, then nothing is created.
 	 * @param type type of created node, one of <code>Node.TEXT_NODE</code> or
 	 * <code>Node.CDATA_SECTION_NODE</code> constants. When modifying text,
 	 * this parameter is ignored.
 	 * @return id of newly created text element, or id of modified element. If
 	 * value is empty or null, then <code>null</code> is returned.
 	 * @deprecated
 	 */
 	@Deprecated
 	public String insertText(DOMPoint ip, Element contextElement,
 			String value, short type) {
 		final Node n= DOMMutils.insertText(ip, contextElement, value, type);
 		if(n==null)return null;
 		return doc.getIDManager().getID(n);
 	}
 	/***
 	 * Removes node(s) with given id from document.
 	 * @param id id of the node, that will be removed.
 	 * @deprecated
 	 */
 	@Deprecated
 	public void remove(String id) {
 		final NodeListID list = doc.getIDManager().getNode(id);
 		if (!list.isTextual()) {
 			// non-textual list can contain only single node. remove it normally
 			remove(list.item(0));
 			return;
 		}
 		// try to remove the textual list
 		remove(list.getStart(), list.getEnd());
 	}
 	/***
 	 * 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 (StringTools.nonNullStr(namespace).startsWith(Const.EM_URI))
 			throw new IllegalArgumentException(
 					"Namespace " + Const.EM_URI + " 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 = XMLConstants.NULL_NS_URI;
 			prefix = XMLConstants.DEFAULT_NS_PREFIX;
 		}
 		final Attr attr=DOMMutils.createAttribute(e, prefix, localName, namespace, value);
 		return doc.getIDManager().getID(attr);
 	}
 	/***
 	 * Inserts the node at the specified pointer. The function does not use the
 	 * ip part of the pointer hence it inserts node into correct place even if
 	 * there was a node already inserted before this place. IP part is used only
 	 * if merge is true and the node is a text or cdata node. If the node is an
 	 * element then it receives an id, however no descendant elements receives
 	 * an id.
 	 * @param node the node to insert, it must be element, comment, pi, text or
 	 * cdata only.
 	 * @param ptr where to insert the node.
 	 * @param merge if <code>true</code> then if new node is a text node then
 	 * it will be merged with adjacent nodes if possible. If <code>false</code>
 	 * then no merging is performed.
 	 * @deprecated
 	 */
 	@Deprecated
 	public void insertNode(Node node, DomPointer ptr, boolean merge) {
 		DOMMutils.insertNode(node, ptr, merge);
 	}
 	/***
 	 * Inserts all nodes from specified document fragment into specified
 	 * position. All nodes are automatically merged. All <code>emp:id</code>
 	 * attributes are ignored. All nodes are removed from the fragment in the
 	 * process and become part of the document.
 	 * @param frag the fragment
 	 * @param ptr where to insert nodes from the fragment.
 	 * @deprecated
 	 */
 	@Deprecated
 	public void insertFragment(DocumentFragment frag, DomPointer ptr) {
 		DOMMutils.insertFragment(frag, ptr);
 	}
 	/***
 	 * 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);
 	}
 	/***
 	 * Checks whether all nodes from specified range can be deleted - i.e. if
 	 * <code>delete</code> with these parameters shall succeed.
 	 * @param from start of the removal interval. The node where this pointer
 	 * points shall be removed (an exception is if some contents of the node are
 	 * left after the operation).
 	 * @param to end of the removal interval.
 	 * @return <code>true</code> if the specified interval is removable,
 	 * <code>false</code> otherwise.
 	 */
 	public boolean isRemovable(DomPointer from, DomPointer to) {
 		// TODO MaVy p0> unify with DOMInterval.isDeletable()
 		// try to skip from entities
 		// 'to' can be null - in such case it points at the end of the document.
 		if (to != null)
 			to = to.getNext(EnumSet.of(DomPointerFlag.NotIntoEntity,
 					DomPointerFlag.PointToNode), true, false,false);
 		if (to != null)
 			to = to.skipFromEntities();
 		if (to == null)
 			to = DomPointerFactory.getLast(doc.getDocument(),
 					EnumSet.of(DomPointerFlag.NotIntoEntity));
 		// if we are now pointing into an entity then it is somewhere in middle
 		// of the entity -> cannot remove.
 		if (to.inEntity())
 			return false;
 		// find first node - any node will do
 		from = from.getNext(EnumSet.of(DomPointerFlag.NotIntoEntity,
 				DomPointerFlag.PointToNode), true, false,false);
 		if (from != null)
 			to = to.skipFromEntities();
 		if (from == null) {
 			// nothing to do, from points at the end of the document, nothing
 			// can be removed, just quit.
 			return true;
 		}
 		// if we are now pointing into an entity then it is somewhere in middle
 		// of the entity -> cannot remove.
 		if (from.inEntity())
 			return false;
 		if (from.equals(to))
 			return true;
 		if (from.compareTo(to) > 0)
 			throw new IllegalArgumentException("'from' must be less than 'to'"); //$NON-NLS-1$
 		return true;
 	}
 	/***
 	 * Tries to remove all nodes in the specified range (the node pointed to by
 	 * <code>to</code> parameter is not removed). The function shall not
 	 * remove elements that shall not have all its children removed.
 	 * @param from start of the removal interval. The node where this pointer
 	 * points shall be removed (exception is a node which have some children
 	 * left after the operation).
 	 * @param to end of the removal interval. It may be <code>null</code>- in
 	 * such case the function shall remove all nodes to the end of the document.
 	 * @deprecated
 	 */
 	@Deprecated
 	public void remove(DomPointer from, DomPointer to) {
 		new DOMInterval(from,to).toRange().deleteContents();
 	}
 	/***
 	 * Tries to remove all nodes in the specified range (the node pointed to by
 	 * <code>to</code> parameter is not removed). Removed nodes are returned
 	 * in a <code>DocumentFragment</code> instance. Both pointers must have
 	 * the same parent element.
 	 * @param from start of the removal interval. The node where this pointer
 	 * points shall be removed.
 	 * @param to end of the removal interval.
 	 * @return <code>DocumentFragment</code> instance containing nodes that
 	 * have been cut from the document. Never <code>null</code>. No element
 	 * in the target fragment will have <code>emp:id</code> attribute.
 	 * @deprecated
 	 */
 	@Deprecated
 	public DocumentFragment cut(DomPointer from, DomPointer to) {
 		return new DOMInterval(from,to).toRange().extractContents();
 	}
 	/***
 	 * Tries to insert some text into specified position.
 	 * @param list current list of nodes, where to insert the text.
 	 * @param pos the position in the <code>textValue</code> string.
 	 * @param type type of created node, one of <code>Node.TEXT_NODE</code> or
 	 * <code>Node.CDATA_SECTION_NODE</code> constants. When modifying text,
 	 * this parameter is ignored.
 	 * @param text the text to be inserted
 	 * @return new instance of list that reflects the changes made to the
 	 * document.
 	 * @throws IllegalArgumentException if no text can be inserted at specified
 	 * position.
 	 * @deprecated
 	 */
 	@Deprecated
 	public NodeListID insertText(NodeListID list, int pos, String text,
 			short type) {
 		DOMMutils.insertText(list, pos, text, type);
 		NodeListID result = list.recover();
 		return result;
 	}
 	/***
 	 * Inserts an entity into specified position.
 	 * @param list current list of nodes, where to insert the entity.
 	 * @param pos the position in the <code>textValue</code> string.
 	 * @param entityName the name of the entity.
 	 * @return new instance of list that reflects the changes made to the
 	 * document.
 	 * @deprecated
 	 */
 	@Deprecated
 	public NodeListID insertEntity(NodeListID list, int pos, String entityName) {
 		final EntityManager em = doc.getEntityManager();
 		DOMMutils.insertEntity(list, pos, entityName, em);
 		final NodeListID result = list.recover();
 		return result;
 	}
 	/***
 	 * Tries to delete specified range of text.
 	 * @param list list of text/cdata nodes. If function finishes succesfully
 	 * and the document gets modified, this list is invalid and must not be
 	 * used.
 	 * @param fromPos the starting position
 	 * @param toPos the ending position - character at this position shall not
 	 * be deleted.
 	 * @return new instance of list that reflects the changes made to the
 	 * document.
 	 * @deprecated
 	 */
 	@Deprecated
 	public NodeListID delete(NodeListID list, int fromPos, int toPos) {
 		DOMMutils.delete(list, fromPos, toPos);
 		final NodeListID result = list.recover();
 		return result;
 	}
 }