/*******************************************************************************
 * Copyright (c) 2006 Oracle Corporation.
 * 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:
 *    Cameron Bateman/Oracle - initial API and implementation
 *    
 ********************************************************************************/

package org.eclipse.jst.jsf.context.resolver.structureddocument.internal;

import org.eclipse.jst.jsf.context.resolver.IDocumentContextResolver;
import org.eclipse.jst.jsf.context.structureddocument.IStructuredDocumentContext;

/**
 * Defines a resolver that can resolve context information in the
 * structured document region context.
 * 
 * Unless otherwise stated, the context region is the most specific
 * region (leaf) in which the current context is contained.
 * 
 * Note: this interface may use internal/provisional types.
 * 
 * @author cbateman
 *
 */
public interface ITextRegionContextResolver extends IDocumentContextResolver 
{
	/**
	 * @return the text for the context region
	 */
	String getRegionText();
	
	/**
	 * @return the document relative offset of the start of the region
	 * in which the context in is contained or -1 if the offset cannot be determined.
	 */
	int getStartOffset();
	
	/**
	 * @return the document relative offset of the end of the region
	 * in which the context is contained or -1 if the offset cannot be determined
	 */
	int getEndOffset();
	
	/**
	 * @return the length of the most specific region in which the context
	 * is contained or -1 if the length cannot be determined.
	 */
	int getLength();
	
	/**
	 * @return the most specific TextRegion type for the current context  
	 */
	String  getRegionType();
	
	/**
	 * @return the path to the most specific TextRegtion for the current context
	 * note that this does not include the actual region for the current region.
	 * That is returned by getRegionType(). 
	 *
	 */
	String[]  getRegionTypePath();
	
	
	/**
	 * The offset into the structured document will be set to be
	 * the start offset of the previous region
	 * 
	 * @return a context for the previous sibling of this context's
	 * text region parent or null if no previous sibling exists
	 */
	IStructuredDocumentContext getPreviousContext();
	
	/**
	 * The offset into the structured document will be set to be
	 * the start offset of the next region
	 * 
	 * @return a context for the next sibling of this context's
	 * text region parent or null if no next sibling exists
	 */
	IStructuredDocumentContext getNextContext();
	
	/**
	 * Relative path works backwards from the current context.  So if the
	 * path to current context is /a/b/c/d/e then:
	 * 
	 * matchesRelative({"e"}) == true
	 * matchesRelative({"d", "e"}) == true
	 * matchesRelative({"c", "d", "e"}) == true
	 * matchesRelative({"b", "c", "d", "e"}) == true
	 * matchesRelative({"a", "b", "c", "d", "e"}) == true
	 * 
	 * because in every case the path matches working backward from the current
	 * context 
	 * 
	 * but
	 * 
	 * matchesRelative({a}) == false because context/.. == e not a
	 * 
	 * TODO: what does path = new String[0] mean?
	 * 
	 * @param path
	 * @return true if the relative path matches the path to the current context
	 * working relative to the current context.
	 */
	boolean   matchesRelative(String[] path);
	
	/**
	 * Absolute path works forward from the root of the document to the 
	 * current context.  So if the path to the current context is /a/b/c/d/e then:
	 * 
	 * matchesAbsolute({"a", "b", "c", "d", "e"}) == true
	 * 
	 * but 
	 * 
	 * matchesAbsolute({"b", "c", "d", "e"}) == true because starting from the root
	 * you cannot follow /b/c/d/e to the context.
	 * 
	 * @param path
	 * @return true if the absolute path from the root of the document 
	 * matches the current context
	 */
	boolean   matchesAbsolute(String[] path);
}