/*******************************************************************************
 * Copyright (c) 2001, 2005 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *     Jens Lukowski/Innoopract - initial renaming/restructuring
 *     
 *******************************************************************************/
package org.eclipse.wst.sse.core.internal.provisional.text;

/**
 * A ITextRegionCollection is a collection of ITextRegions. It is a structural
 * unit, but a minimal one. For example, in might consist of a "start tag" but
 * not a whole XML element.
 */
public interface IStructuredDocumentRegion extends ITextRegionCollection {

	/**
	 * Adds a text region to the end of the collection of regions contained by
	 * this region. It is the parsers responsibility to make sure its a
	 * correct region (that is, its start offset is one greater than previous
	 * regions end offset)
	 * 
	 * For use by parsers and reparsers only.
	 */
	void addRegion(ITextRegion aRegion);

	/**
	 * Returns the structured document region that follows this one or null if
	 * at end of document.
	 * 
	 * @return the structured document region that follows this one.
	 * 
	 * ISSUE: for thread safety, this should be more restrictive.
	 */
	IStructuredDocumentRegion getNext();

	/**
	 * Returns this regions parent document.
	 * 
	 * @return this regions parent document.
	 */
	IStructuredDocument getParentDocument();

	/**
	 * Returns the structured document region that preceeds this one or null
	 * if at beginning of document.
	 * 
	 * @return the structured document region that follows this one.
	 * 
	 * ISSUE: for thread safety, this should be more restrictive.
	 */
	IStructuredDocumentRegion getPrevious();

	/**
	 * Returns true if this document has been deleted, and is no longer part
	 * of the actual structured document. This field can be used in
	 * multi-threaded operations, which may retrieve a long list of regions
	 * and be iterating through them at the same time the document is
	 * modified, and regions deleted.
	 * 
	 * @return true if this region is no longer part of document.
	 */
	boolean isDeleted();

	/**
	 * Returns true if this structured document region was ended "naturally"
	 * by syntactic rules, or if simply assumed to end so another could be
	 * started.
	 * 
	 * @return true if region has syntactic end.
	 */
	boolean isEnded();

	/**
	 * Tests is region is equal to this one, ignoring position offsets of
	 * shift.
	 * 
	 * For use by parsers and reparsers only.
	 * 
	 * @param region
	 * @param shift
	 * @return
	 */
	boolean sameAs(IStructuredDocumentRegion region, int shift);

	/**
	 * Tests if <code>oldRegion</code> is same as <code>newRegion</code>,
	 * ignoring position offsets of <code>shift</code>.
	 * 
	 * ISSUE: which document region are old and new in?
	 * 
	 * For use by parsers and reparsers only.
	 * 
	 * @param oldRegion
	 * @param documentRegion
	 * @param newRegion
	 * @param shift
	 * @return
	 */
	boolean sameAs(ITextRegion oldRegion, IStructuredDocumentRegion documentRegion, ITextRegion newRegion, int shift);

	/**
	 * Set to true if/when this region is removed from a document, during the
	 * process of re-parsing.
	 * 
	 * For use by parsers and reparsers only.
	 * 
	 * @param deleted
	 */
	void setDeleted(boolean deleted);

	/**
	 * Set to true by parser/reparser if region deemed to end syntactically.
	 * 
	 * For use by parsers and reparsers only.
	 * 
	 * @param hasEnd
	 */
	void setEnded(boolean hasEnd);

	/**
	 * Sets length of region.
	 * 
	 * For use by parsers and reparsers only.
	 */
	void setLength(int newLength);

	/**
	 * Assigns pointer to next region, or null if last region.
	 * 
	 * For use by parsers and reparsers only.
	 */
	void setNext(IStructuredDocumentRegion newNext);

	/**
	 * Assigns parent documnet.
	 * 
	 * For use by parsers and reparsers only.
	 */
	void setParentDocument(IStructuredDocument document);

	/**
	 * Assigns pointer to previous region, or null if first region.
	 * 
	 * For use by parsers and reparsers only.
	 */
	void setPrevious(IStructuredDocumentRegion newPrevious);

	/**
	 * Sets start offset of region, relative to beginning of document.
	 * 
	 * For use by parsers and reparsers only.
	 */
	void setStart(int newStart);


}