toxgene.interfaces.ToXgeneEngine Maven / Gradle / Ivy

Go to download
package toxgene.interfaces;

import java.io.PrintStream;
import java.io.InputStream;
import java.util.Vector;

import toxgene.core.ToXgeneErrorException;

/**
 * Interface to the ToXgene generation engine.
 *
 * @author Denilson Barbosa
 *
 * @version 0.1
 */
public interface ToXgeneEngine{

	/**
	 * This method inits a ToXgene session, passing the parameters under
	 * which ToXgene will work.
	 *
	 * @param session contains the paramaters for the data generation
	 * session
	 * @see ToXgeneSession
	 * @throws ToXgeneErrorException indicates that ToXgene could not
	 * initialize a session.
	 */
	public void startSession(ToXgeneSession session)
		throws ToXgeneErrorException;

	/**
	 * This method invokes ToXgene's cleanup routine.
	 */
	public void endSession();

	/**
	 * Parses a template and prepares ToXgene for producing the
	 * synthetic documents.
	 *
	 * @param template stream from which the template is read
	 *
	 * @throws ToXgeneErrorException indicates that a fatal exceptional
	 * situation arised durint the parsing of the template
	 */
	public boolean parseTemplate(InputStream template)
		throws ToXgeneErrorException;

	/**
	 * Returns a Vector containing all document collections specified by
	 * tox-document elements in the template.  Individual
	 * documents (i.e., tox-documents with
	 * copies=1 are viewed as collections with a single
	 * document.
	 *
	 * @see ToXgeneDocumentColletion
	 */
	public Vector getToXgeneDocumentCollections();

/**
* Generates all temporary data declared in the tox-lists elements
* in the input template. This method is optional; if not invoked
* explicitly, ToXGene will automatically generate all temporary
* data as needed.
*
* This method is useful when measuring time for generating the documents
* as it isolates the generation of temporary data.
*/
public void generateLists();

	/**
	 * Materializes an XML document from the given collection into a
	 * PrintStream object. For a collection with n documents,
	 * there can be at most n calls to this method.
	 *
	 * @param collection document collection that will be materialized
	 * @param outStream PrintStream where the document will be written to
	 *
	 * @see ToXgeneDocumentCollection
	 *
	 * @throws ToXgeneErrorException indicates that ToXgene cannot
	 * proceed to materialize the document. In particular, such an
	 * exception is raised if a ToXgeneDocumentCollection is used more
	 * than the number of documents it contains.
	 */
	public void materialize(ToXgeneDocumentCollection collection,
													PrintStream outStream) throws ToXgeneErrorException;
}