com.sun.msv.reader.State Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jaxb1-impl
JAXB (JSR 222) reference implementation - JAXB1 build
There is a newer version: 2.2.5.1
/*
 * @(#)$Id: State.java,v 1.16 2003/08/07 17:30:20 kohsuke Exp $
 *
 * Copyright 2001 Sun Microsystems, Inc. All Rights Reserved.
 * 
 * This software is the proprietary information of Sun Microsystems, Inc.  
 * Use is subject to license terms.
 * 
 */
package com.sun.msv.reader;

import org.xml.sax.ContentHandler;
import org.xml.sax.Locator;
import org.xml.sax.SAXException;
import org.xml.sax.helpers.LocatorImpl;

import com.sun.msv.grammar.Expression;
import com.sun.msv.util.StartTagInfo;

/**
 * base interface of 'parsing state'.
 * 
 * parsing of XML representation of a grammar is done by
 * using various states.
 * 
 * 
 * Each State-derived class is responsible for a particular type of
 * declaration of the grammar. For example, SequenceState is responsible
 * for parsing <sequence> element of RELAX module.
 * 
 * 

 * State objects interact each other. There are two ways of interaction.
 * 
 * 

 *  from parent to child
 *  
from child to parent
 * 
 * 
 * The first type of communication occurs only when a child state object is
 * created. The last type of communication occurs usually (but not limited to)
 * when a child state sees its end tag.
 * 
 * 
 * 
 * In this level of inheritance, contract is somewhat abstract.
 * 
 * 

 *  When a State object is created, its init method is called
 *        and various information is set. Particularly, start tag
 *        information (if any) and the parent state is set.
 *        This process should only be initiated by GrammarReader.
 * 
 *  
After that, startSelf method is called. Usually,
 *        this is the place to do something useful.
 * 
 *  
State object is registered as a ContentHandler, and
 *        therefore will receive SAX events from now on.
 * 
 *  
Derived classes are expected to do something useful
 *        by receiving SAX events.
 * 
 *  
When a State object finishes its own part, it should
 *        call GrammarReader.popState method. It will remove
 *        the current State object and registers the parent state 
 *        as a ContentHandler again.
 * 
 * 
 * Of course some derived classes introduce more restricted
 * contract. See {@link SimpleState}.
 * 
 * 
 * this class also provides:
 * 

 *  access to the parent state
 *  
default implementations for all ContentHandler callbacks
 *        except startElement and endElement
 * 
 * 
 * @author Kohsuke KAWAGUCHI
 */
public abstract class State implements ContentHandler
{
    /**
     * parent state of this state.
     * 
     * In other words, the parent state is a state who is responsible
     * for the parent element of the current element.
     * 
     * For states responsible for the document element, the parent state is
     * a state who is responsible for the entire document.
     * 
     * For states responsible for the entire document, the parent state is
     * always null.
     */
    protected State parentState;
    public final State getParentState() { return parentState; }

    /**
     * reader object who is the owner of this object.
     * This information is avaiable after init method is called.
     */
    public GrammarReader reader;
                
    /**
     * information of the start tag.
     * This information is avaiable after init method is called.
     */
    protected StartTagInfo startTag;
    public StartTagInfo getStartTag() { return startTag; }
    
    /**
     * Location of the start tag.
     * This information is avaiable after init method is called.
     */
    protected Locator location;
    public Locator getLocation() { return location; }
    
    /**
     * base URI for this state.
     * This information is avaiable after init method is called.
     */
    protected String baseURI;
    public String getBaseURI() { return baseURI; }
    
    protected final void init( GrammarReader reader, State parentState, StartTagInfo startTag ) {
        // use of the constructor, which is usually the preferable way,
        // is intentionally avoided for short hand.
        // if we use the constructor to do the initialization, every derived class
        // has to have a dumb constructor, which simply delegates all the parameter
        // to the super class.
        
        this.reader = reader;
        this.parentState = parentState;
        this.startTag = startTag;
        if( reader.locator!=null )    // locator could be null, in case of the root state.
        this.location = new LocatorImpl( reader.locator );
        
        // handle the xml:base attribute.
        String base=null;
        if( startTag!=null )
            base = startTag.getAttribute("http://www.w3.org/XML/1998/namespace","base");
        
        if( parentState==null )
            // this state is the root state and therefore we don't have locator.
            this.baseURI = null;
        else {
            this.baseURI = parentState.baseURI;
            if( this.baseURI==null )
                this.baseURI = reader.locator.getSystemId();
        }
        if( base!=null )
            this.baseURI = reader.combineURI( this.baseURI, base );
        startSelf();
    }
    
    /** performs a task that should be done before reading any child elements.
     * 
     * derived-class can safely read startTag and/or parentState values.
     */
    protected void startSelf() {}
    
    
    public static void _assert( boolean b ) {
        if(!b)  throw new InternalError();
    }

    public void characters(char[] buffer, int from, int len ) throws SAXException {
        // both RELAX and TREX prohibits characters in their grammar.
        for( int i=from; i