/*
 * Copyright (c) 2006, 2017, Oracle and/or its affiliates. All rights reserved.
 */
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * 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 com.sun.org.apache.xerces.internal.impl.xs.models;

import com.sun.org.apache.xerces.internal.impl.xs.SubstitutionGroupHandler;
import com.sun.org.apache.xerces.internal.impl.xs.XMLSchemaException;
import com.sun.org.apache.xerces.internal.xni.QName;
import java.util.List;

Note: State of the content model is stored in the validator
Author:
Sandy Gao, IBM, Elena Litani, IBM
@xerces.internal
@LastModified
: Oct 2017/**
 * Note: State of the content model is stored in the validator
 *
 * @xerces.internal
 *
 * @author Sandy Gao, IBM
 * @author Elena Litani, IBM
 * @LastModified: Oct 2017
 */
public interface XSCMValidator {


    public static final short FIRST_ERROR = -1;

    // on subsequent errors the validator should not report
    // an error
    //
    public static final short SUBSEQUENT_ERROR = -2;

    
This methods to be called on entering a first element whose type
has this content model. It will return the initial state of the content model
Returns:
Start state of the content model/**
     * This methods to be called on entering a first element whose type
     * has this content model. It will return the initial state of the content model
     *
     * @return Start state of the content model
     */
    public int[] startContentModel();


    
The method corresponds to one transaction in the content model.
Params:
elementName – 
state –  Current state
Returns:
element decl or wildcard decl that
        corresponds to the element from the Schema grammar/**
     * The method corresponds to one transaction in the content model.
     *
     * @param elementName
     * @param state  Current state
     * @return element decl or wildcard decl that
     *         corresponds to the element from the Schema grammar
     */
    public Object oneTransition (QName elementName, int[] state, SubstitutionGroupHandler subGroupHandler);


    
The method indicates the end of list of children
Params:
state –  Current state of the content model
Returns:
true if the last state was a valid final state/**
     * The method indicates the end of list of children
     *
     * @param state  Current state of the content model
     * @return true if the last state was a valid final state
     */
    public boolean endContentModel (int[] state);

    
check whether this content violates UPA constraint.
Params:
subGroupHandler – the substitution group handler
Returns:
true if this content model contains other or list wildcard/**
     * check whether this content violates UPA constraint.
     *
     * @param subGroupHandler the substitution group handler
     * @return true if this content model contains other or list wildcard
     */
    public boolean checkUniqueParticleAttribution(SubstitutionGroupHandler subGroupHandler) throws XMLSchemaException;

    
Check which elements are valid to appear at this point. This method also
works if the state is in error, in which case it returns what should
have been seen.
Params:
state –  the current state
Returns:
      a list whose entries are instances of
              either XSWildcardDecl or XSElementDecl./**
     * Check which elements are valid to appear at this point. This method also
     * works if the state is in error, in which case it returns what should
     * have been seen.
     *
     * @param state  the current state
     * @return       a list whose entries are instances of
     *               either XSWildcardDecl or XSElementDecl.
     */
    public List<Object> whatCanGoHere(int[] state);

    
Used by constant space algorithm for a{n,m} for n > 1 and
m <= unbounded. Called by a validator if validation of
countent model succeeds after subsuming a{n,m} to a*
(or a+) to check the n and m bounds.
Returns:
null if validation of bounds is
successful. Returns a list of strings with error info
if not. Even entries in list returned are error codes
(used to look up properties) and odd entries are parameters
to be passed when formatting error message. Each parameter
is associated with the error code that proceeds it in
the list./**
     * Used by constant space algorithm for a{n,m} for n > 1 and
     * m <= unbounded. Called by a validator if validation of
     * countent model succeeds after subsuming a{n,m} to a*
     * (or a+) to check the n and m bounds.
     *
     * @return <code>null</code> if validation of bounds is
     * successful. Returns a list of strings with error info
     * if not. Even entries in list returned are error codes
     * (used to look up properties) and odd entries are parameters
     * to be passed when formatting error message. Each parameter
     * is associated with the error code that proceeds it in
     * the list.
     */
    public List<String> checkMinMaxBounds();

     
Returns an array containing information about the current repeating term
or null if no occurrence counting was being performed at the
current state.
If an array is returned it will have a length == 4 and will contain:
 

  
a[0] :: min occurs
  
a[1] :: max occurs
  
a[2] :: current value of the counter
  
a[3] :: identifier for the repeating term
 

Params:
state – the current state
Returns:
an array containing information about the current repeating term/**
     * <p>Returns an array containing information about the current repeating term
     * or <code>null</code> if no occurrence counting was being performed at the
     * current state.</p>
     *
     * <p>If an array is returned it will have a length == 4 and will contain:
     *  <ul>
     *   <li>a[0] :: min occurs</li>
     *   <li>a[1] :: max occurs</li>
     *   <li>a[2] :: current value of the counter</li>
     *   <li>a[3] :: identifier for the repeating term</li>
     *  </ul>
     * </p>
     *
     * @param state the current state
     * @return an array containing information about the current repeating term
     */
    public int [] occurenceInfo(int[] state);

    
Returns the name of the term (element or wildcard) for the given identifier.
Params:
termId – identifier for the element declaration or wildcard
Returns:
the name of the element declaration or wildcard/**
     * Returns the name of the term (element or wildcard) for the given identifier.
     *
     * @param termId identifier for the element declaration or wildcard
     * @return the name of the element declaration or wildcard
     */
    public String getTermName(int termId);

    
Checks if this content model has had its min/maxOccurs values reduced for
purposes of speeding up UPA.  If so, this content model should not be used
for any purpose other than checking unique particle attribution
Returns:
a boolean that says whether this content has been compacted for UPA/**
     * Checks if this content model has had its min/maxOccurs values reduced for
     * purposes of speeding up UPA.  If so, this content model should not be used
     * for any purpose other than checking unique particle attribution
     *
     * @return a boolean that says whether this content has been compacted for UPA
     */
    public boolean isCompactedForUPA();
} // XSCMValidator