baserecognizer.java

It is the Speech recognition software. It is platform independent. To execute the source code,

/**
 * Copyright 1998-2003 Sun Microsystems, Inc.
 * 
 * See the file "license.terms" for information on usage and
 * redistribution of this file, and for a DISCLAIMER OF ALL 
 * WARRANTIES.
 */

package com.sun.speech.engine.recognition;

import javax.speech.*;
import javax.speech.recognition.*;

import java.net.*;
import java.io.*;
import java.util.*;

import com.sun.speech.engine.*;

import com.sun.speech.engine.SpeechEventUtilities;
import com.sun.speech.engine.SpeechEventDispatcher;

/**
 * Skeletal Implementation of the JSAPI Recognizer interface.
 * 
 * This class is useful by itself for debugging, e.g. you
 * can load grammars and simulate a recognizer recognizing
 * some text, etc.
 * <P>
 *
 * Actual JSAPI recognizer implementations might want to extend or
 * modify this implementation.
 * <P>
 *
 * Also contains utility routines for:
 * <UL>
 *  <LI>Loading imported grammars and resolving inter-grammar
 *      references.
 *
 *  <LI>Printing/dumping grammars in an extensible way
 *      (used to dump grammar to under-lying recognizer
 *       implementation via ascii strins)
 *
 *  <LI>Routines for copying grammars from one recognizer implementation
 *      to another.
 * </UL>
 *
 * @author Stuart Adams
 * @version 1.20 09/10/99 17:02:58
 */
public class BaseRecognizer extends BaseEngine
    implements Recognizer, SpeechEventDispatcher {
    protected Vector    resultListeners;
    protected Hashtable grammarList;
    protected boolean   caseSensitiveGrammarNames = true;
    protected boolean   hasModalGrammars = false;

    protected boolean supportsNULL = true;
    protected boolean supportsVOID = true;

    // used when printing grammars
    public RuleGrammar currentGrammar = null;  
  
    // Set to true if recognizer cannot handle partial
    // grammar loading.
    protected boolean reloadAll = false;          

//////////////////////
// Begin Constructors
//////////////////////
    /**
     * Create a new Recognizer in the DEALLOCATED state.
     */
    public BaseRecognizer() {
	this(false,null);
    }

    /**
     * Create a new Recognizer in the DEALLOCATED state.
     */
    public BaseRecognizer(RecognizerModeDesc mode) {
	this(false,mode);
    }

    /**
     * Create a new Recognizer in the DEALLOCATED state.
     * @param reloadAll set to true if recognizer cannot handle 
     * partial grammar loading.  Default = false.
     */
    public BaseRecognizer(boolean reloadAll, RecognizerModeDesc mode) {
	super(mode);
        this.reloadAll = reloadAll;
        resultListeners = new Vector();
        grammarList = new Hashtable();
	audioManager = new BaseRecognizerAudioManager();
    }
//////////////////////
// End Constructors
//////////////////////

//////////////////////
// Begin overridden Engine Methods
//////////////////////
    /**
     * Allocate the resources for the Engine and put it in the ALLOCATED,
     * RESUMED, QUEUE_EMPTY state.
     */
    public void allocate() 
        throws EngineException, EngineStateError {
        // We don't need the following steps to be atomic
        // so there's no need to synchronize on engineStateLock
        if (testEngineState(ALLOCATED)) {
            return;
        }
        
        // Temporarily go in to the ALLOCATING_RESOURCES state.
        long[] states = setEngineState(CLEAR_ALL_STATE, ALLOCATING_RESOURCES);
        postEngineAllocatingResources(states[0], states[1]);
        
        // Go in to the ALLOCATED, RESUMED, LISTENING, and FOCUS_ON states.
        // Subclasses with shared engines should check all states before
        // changing them here.
        synchronized (engineStateLock) {
            long newState = ALLOCATED | RESUMED | LISTENING | FOCUS_ON;
            states = setEngineState(CLEAR_ALL_STATE, newState);
        }
        postEngineAllocated(states[0], states[1]);
        handleAllocate();        
    }

    /**
     * Deallocate the resources for the Engine and put it in the 
     * DEALLOCATED state.
     */

    public void deallocate()
      throws EngineException, EngineStateError
    {            
      // We don't need the following steps to be atomic
      // so there's no need to synchronize on engineStateLock

      if (testEngineState(DEALLOCATED))
	  return;

      // Clean up the focus state
      releaseFocus();

      // Temporarily go in to the DEALLOCATING_RESOURCES state.
      // Make sure we kill the PAUSE/RESUME, LISTENING, FOCUS states etc.
      long[] states = setEngineState(CLEAR_ALL_STATE, DEALLOCATING_RESOURCES);
      postEngineDeallocatingResources(states[0], states[1]);
      
      // Go in to the DEALLOCATED state.
      states = setEngineState(CLEAR_ALL_STATE, DEALLOCATED);
      postEngineDeallocated(states[0], states[1]);
      handleDeallocate();
    }


    /**
     * Return an object that provides management of the audio input
     * or output of the Engine.
     * From javax.speech.Engine.
     */
    public AudioManager getAudioManager() {
	if (audioManager == null) {
	    audioManager = new BaseRecognizerAudioManager();
	}
        return audioManager;
    }    
//////////////////////
// End overridden Engine Methods
//////////////////////
    
//////////////////////
// Begin Recognizer Methods
//////////////////////
    /**
     * Create a new RuleGrammar with the given name.
     * From javax.speech.recognition.Recognizer.
     * @param name the name of the RuleGrammar.
     */
    public RuleGrammar newRuleGrammar(String name) 
        throws IllegalArgumentException, EngineStateError
    {
        checkEngineState(DEALLOCATED | DEALLOCATING_RESOURCES);
        BaseRuleGrammar G = new BaseRuleGrammar(this, name);
        storeGrammar(G);
        return G;
    }
    
    /** 
     * NOT IMPLEMENTED YET.
     * We use a JavaCC generated parser for reading jsgf file. It 
     * does not support reading from java.io.Reader yet - once it
     * does we will implement this method.  The current implementation
     * assumes the Reader can be converted into an ASCII input stream.
     * From javax.speech.recognition.Recognizer.
     * @param JSGFinput the Reader containing JSGF input.
     */
    public RuleGrammar loadJSGF(Reader JSGFinput) 
        throws GrammarException, IOException, EngineStateError
    {
        checkEngineState(DEALLOCATED | DEALLOCATING_RESOURCES);
        
        RuleGrammar G = JSGFParser.newGrammarFromJSGF(JSGFinput, 
                                                      (Recognizer)this);
        if (G == null) {
            throw new IOException();	// Should never happen
        }
        if (G.getName() != null) {
            storeGrammar(G);
        }
        return G;
    }

    /**
     * Load a RuleGrammar and its imported grammars from a URL containing
     * JSGF text.
     * From javax.speech.recognition.Recognizer.
     * @param baseURL the base URL containing the JSGF grammar file.
     * @param grammarName the name of the JSGF grammar to load.
     */
    public RuleGrammar loadJSGF(java.net.URL baseURL, String grammarName) 
        throws GrammarException, MalformedURLException, 
            IOException, EngineStateError 
    {
        checkEngineState(DEALLOCATED | DEALLOCATING_RESOURCES);

	return loadJSGF(baseURL,grammarName,true,false,null);
    }

  private static URL gnameToURL(URL baseURL, String grammarName) throws MalformedURLException {
    
    // Convert each period in the grammar name to a slash "/"
    // Append a slash and the converted grammar name to the base URL
    // Append the ".gram" suffix
    grammarName = grammarName.replace('.', '/');
    String urlstr = "";
    if (baseURL != null) urlstr = baseURL.toString();
    urlstr = urlstr.concat(((urlstr.lastIndexOf((int)'/')
			     == (urlstr.length() - 1)) 
			    ? "" 
			    : "/") + grammarName + ".gram");
    
    URL grammarURL = null;
    try {
      grammarURL = new URL(urlstr);
    }
    catch (MalformedURLException me) {
      grammarURL = ClassLoader.getSystemResource(urlstr);
      if (grammarURL == null) 
	throw new MalformedURLException(urlstr);
    }
    
    return grammarURL;
  }
      
   /** 
     * 
     * From javax.speech.recognition.Recognizer.
     */
    public RuleGrammar loadJSGF(URL context, String grammarName,
                                boolean loadImports, boolean reloadGrammars,
                                Vector loadedGrammars) 
        throws GrammarException, MalformedURLException, 
            IOException, EngineStateError 
    {
        checkEngineState(DEALLOCATED | DEALLOCATING_RESOURCES);
	
        URL grammarURL = gnameToURL(context, grammarName);

        RuleGrammar G = JSGFParser.newGrammarFromJSGF(grammarURL, this);

        if (G == null) {
            throw new IOException();	// Should never happen
        }

        if (loadImports) loadImports(this,G,context,true,reloadGrammars,loadedGrammars);

        if (G.getName() != null) {
            storeGrammar(G);
        }
        return G;
    }
    
    /**
     * Return the named RuleGrammar 
     * From javax.speech.recognition.Recognizer.
     * @param name the name of the RuleGrammar.
     */
    public RuleGrammar getRuleGrammar(String name) throws EngineStateError {
        checkEngineState(DEALLOCATED | DEALLOCATING_RESOURCES);
        return retrieveGrammar(name);
    }

    /**
     * Get a list of loaded or defined RuleGrammars known to the
     * Recognizer.
     * From javax.speech.recognition.Recognizer.
     */
    public RuleGrammar[] listRuleGrammars() throws EngineStateError {
        checkEngineState(DEALLOCATED | DEALLOCATING_RESOURCES);
	if (grammarList == null) {
	    return new RuleGrammar[0];
	}
        RuleGrammar rl[] = new RuleGrammar[grammarList.size()];
        int i=0;
        Enumeration e = grammarList.elements();
        while (e.hasMoreElements()) {
            rl[i++] = (RuleGrammar) e.nextElement(); 
        }
        return rl;
    }
    
    /**
     * Delete a RuleGrammar from the Recognizer.
     * From javax.speech.recognition.Recognizer.
     * @param grammar the RuleGrammar to delete.
     */
    public void deleteRuleGrammar(RuleGrammar grammar) 
        throws IllegalArgumentException, EngineStateError 
    {
        checkEngineState(DEALLOCATED | DEALLOCATING_RESOURCES);
        String name = grammar.getName();
        grammarList.remove(name);
    }
    
    /**
     * Get the DicationGrammar for this Recognizer.
     * Always returns null.  Should be overridden by
     * recognizers that support dictation.
     */
    public DictationGrammar getDictationGrammar(String name) 
        throws EngineStateError 
    {
        checkEngineState(DEALLOCATED | DEALLOCATING_RESOURCES);
        return null;
    }

    /** 
     * Commit grammar changes.
     * From javax.speech.recognition.Recognizer.
     */
    public void commitChanges()
        throws GrammarException, EngineStateError
    {
        checkEngineState(DEALLOCATED | DEALLOCATING_RESOURCES);

	// All cases:
	//   If there is a pending suspend call, it can be cleared.
	//   THIS IS NOT IMPLEMENTED YET
	// Case 1:
	//   If the recognizer is in the LISTENING state we should
	//   first transition to the SUSPENDED state, then commit,
	//   then return the LISTENING state.
	// Case 2: 
	//   If the recognizer is in the SUSPENDED state, we remain
	//   in that state, commit, then return to LISTENING state.
	//   EXCEPTION: if the recognizer is still issuing events
	//   for a Result that brought it to the SUSPENDED state,
	//   the commit should be deferred until the event processing
	//   is complete -- THIS IS NOT IMPLEMENTED YET.
	// Case 3:
	//   If the recognizer is in the PROCESSING state, the
	//   commit should be deferred until following result is
	//   finalized and appropriate events have been issued.

	// The following hack avoids inappropriately going from
	// PROCESSING to LISTENING states.  It does not correctly
	// handle clearing of explicit suspend requests.
	boolean goBackToListening = false;

	if (testEngineState(LISTENING)) {
	  goBackToListening = true;
	  long[] states = setEngineState(LISTENING | PROCESSING, SUSPENDED);
	  postRecognizerSuspended(states[0], states[1]);
	}
        
	// If we're in the PROCESSING state we shouldn't modify grammars.

	// Prepare the grammars to be committed
        linkGrammars();

        //GRAMMAR_CHANGES_COMMITTED events are sent in commitChangesInternal

        // Activate or Deactivate any grammars
        checkForModalGrammars();
        notifyGrammarActivation();

	if (goBackToListening) {
  	    long[] states = setEngineState(SUSPENDED | PROCESSING, LISTENING);
	    postChangesCommitted(states[0], states[1], null);
	}
    }

    /**
     * Temporarily suspend recognition while the application updates
     * grammars prior to a call to commitChanges.
     */
    public void suspend() throws EngineStateError {
        checkEngineState(DEALLOCATED | DEALLOCATING_RESOURCES);

        //[[[WDW - need to set a flag saying we got here via a method call
        //from the application.]]]

        if (testEngineState(SUSPENDED)) {
            return;
        }

	long[] states = setEngineState(LISTENING | PROCESSING, SUSPENDED);
	postRecognizerSuspended(states[0], states[1]);
    }
    
    /**
     * NOT IMPLEMENTED YET.
     * If the Recognizer is in the PROCESSING state, force the Recognizer
     * to immediately complete processing of that result by finalizing it.
     * From javax.speech.recognition.Recognizer.
     * @param flush whether audio buffer should be processed or flushed.
     */
    public void forceFinalize(boolean flush) throws EngineStateError {
        checkEngineState(DEALLOCATED | DEALLOCATING_RESOURCES);
        throw new RuntimeException(
            "forceFinalize not yet implemented.");
    }

    /**
     * Request speech focus for this Recognizer from the underlying speech
     * recognition system.
     */
    public void requestFocus() throws EngineStateError {
        checkEngineState(DEALLOCATED | DEALLOCATING_RESOURCES);

	// Do nothing if the state is already OK