/*******************************************************************************
 * Copyright (c) 2002, 2006 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.xml.core.internal.contentmodel.modelquery;

import java.util.List;

import org.eclipse.wst.xml.core.internal.contentmodel.CMAttributeDeclaration;
import org.eclipse.wst.xml.core.internal.contentmodel.CMDocument;
import org.eclipse.wst.xml.core.internal.contentmodel.CMElementDeclaration;
import org.eclipse.wst.xml.core.internal.contentmodel.CMNode;
import org.eclipse.wst.xml.core.internal.contentmodel.modelquery.extension.ModelQueryExtensionManager;
import org.w3c.dom.Attr;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.Node;


/**
 * This class provides an interface for performing higher level queries based on
 * a xml model (DOM) and one or more associated content models (CMDocument).
 *
 * The queries provided can be organized into three groups:
 *
 * 1) DOM Node to CMNode mapping
 *      Given a grammatically valid DOM Node the corresponding CMNode can be determined.
 *      (i.e. Element -> CMElementDeclaration, Attr -> CMAttributeDeclaration, CharacterData -> CMDataType)
 *
 * 2) DOM editing tests ("Can I do this?")
 *      Questions such as canInsert, canRemove, canReplace can assist in the editing of a DOM.
 *
 *      The validityChecking argument determines the strictness of the validity testing that occurs.
 *
 *      - VALIDITY_NONE    : The current content of the Element is ignored.
 *                           Only the content model is considered.
 *                           This is most useful for codeassist related queries.
 *
 *      - VALIDITY_STRICT  : The current content of the Element is considered.
 *                           Returns true only if the operation preserves content validity.
 *                           This is useful when DOM editing needs to be constrained to maintain validity.
 *
 *      - VALIDITY_PARTIAL : Some optimized compromise between the two options above.
 *
 * 3) DOM editing actions ("What can I do here?")
 *      These methods return ModelQueryActions that are relevant at some specified DOM Node.
 *      The actions indicate what kinds of DOM Node can be inserted where (at what index).
 */
public interface ModelQuery
{
  public static final int VALIDITY_NONE = 0;
  public static final int VALIDITY_PARTIAL = 1;
  public static final int VALIDITY_STRICT = 2;

  public static final int INCLUDE_ALL = 0xFF;
  public static final int INCLUDE_ATTRIBUTES = 0x01;
  public static final int INCLUDE_CHILD_NODES = 0x02;
  public static final int INCLUDE_SEQUENCE_GROUPS = 0x04;
  public static final int INCLUDE_TEXT_NODES = 0x08;
  public static final int INCLUDE_ENCLOSING_REPLACE_ACTIONS = 0x10;

  public static final int EDIT_MODE_UNCONSTRAINED = 0;
  public static final int EDIT_MODE_CONSTRAINED_LENIENT= 1;
  public static final int EDIT_MODE_CONSTRAINED_STRICT = 2;


  void setEditMode(int editMode);

  int  getEditMode();

  /**
   * Returns the CMDocument that corresponds to the DOM Node.
   * or null if no CMDocument is appropriate for the DOM Node.
   */
  CMDocument getCorrespondingCMDocument(Node node);

  /**
   * Returns the corresponding CMNode for the DOM Node
   * or null if no CMNode is appropriate for the DOM Node.
   */
  CMNode getCMNode(Node node);

  /**
   * Returns the corresponding CMAttribute for the DOM Node
   * or null if no CMNode is appropriate for the DOM Node.
   */
  CMAttributeDeclaration getCMAttributeDeclaration(Attr attr);

  /**
   * Returns the corresponding CMAttribute for the DOM Node
   * or null if no CMNode is appropriate for the DOM Node.
   */
  CMElementDeclaration getCMElementDeclaration(Element element);

  /**
   * Returns true if the content of the element is valid
   */
  boolean isContentValid(Element element);

  /**
   * Returns the CMNode of the parent element's content model
   * that corresponds to the node
   */
  CMNode getOrigin(Node node);

  /**
   * Returns an array of CMNodes of the parent element's content model
   * that corresponds to the node
   */
  CMNode[] getOriginArray(Element element);

  /**
   * Returns a list of all CMNode 'meta data' that may be potentially added to the element.
   */
  List getAvailableContent(Element element, CMElementDeclaration ed, int includeOptions);

  /**
   * Can a DOM Node corresponding to the CMNode 'meta data' be added to the parent
   */
  boolean canInsert(Element parent, CMNode cmNode, int index, int validityChecking);

  /**
   * Can multiple DOM Nodes corresponding to the list of CMNode 'meta data' be added to the parent
   */
  boolean canInsert(Element parent, List cmNodeList, int index, int validityChecking);

  /**
   * Can the DOM Node be removed
   */
  boolean canRemove(Node node, int validityChecking);

  /**
   * Can the list of DOM Nodes be removed
   */
  boolean canRemove(List nodeList, int validityChecking);

  /**
   * Can the children within the indicated indices be replaced with a DOM Node corresponding to the CMNode 'meta data'
   */
  boolean canReplace(Element parent, int startIndex, int endIndex, CMNode cmNode, int validityChecking);

  /**
   * Can the children within the indicated indices be replaced with multiple DOM Nodes corresponding to the list of CMNode 'meta data'
   */
  boolean canReplace(Element parent, int startIndex, int endIndex, List cmNodeList, int validityChecking);

  /**
   *
   */
  void getInsertActions(Element parent, CMElementDeclaration ed, int index, int includeOptions, int validityChecking, List actionList);

  /**
   *
   */
  void getInsertActions(Document parent, CMDocument cmDocument, int index, int includeOptions, int validityChecking, List actionList);

  /**
   * Return a list of replace actions that can be performed on the parent's content
   */
  void getReplaceActions(Element parent, CMElementDeclaration ed, int includeOptions, int validityChecking, List actionList);

  /**
   * Return a list of replace actions that can be performed on the selected children of that parent 
   */
  void getReplaceActions(Element parent, CMElementDeclaration ed, List selectedChildren, int includeOptions, int validityChecking, List actionList);

                        
  /** 
   *  @deprecated - use getPossibleDataTypeValues()
   */
  List getDataTypeValues(Element element, CMNode cmNode);

  /**
   * This methods return an array of possible values corresponding to the datatype of the CMNode (either an CMAttributeDeclaration or a CMElementDeclaration)
   */
  String[] getPossibleDataTypeValues(Element element, CMNode cmNode);

  /**
   * This method may return null if a CMDocumentManager is not used by the ModelQuery
   */
  CMDocumentManager getCMDocumentManager();                                       

  /**
   * This method may return null the ModelQuery doesn't support the use of extensions
   */
  ModelQueryExtensionManager getExtensionManager();   
}