SnuggleSession (SnuggleTeX Core 1.5.0-SNAPSHOT API)

java.lang.Object
- uk.ac.ed.ph.snuggletex.SnuggleSession

All Implemented Interfaces:

SessionContext
```
public final class SnuggleSession
extends Object
implements SessionContext
```
This represents a single "job" for SnuggleTeX.
Usage
- Create a session with SnuggleEngine.createSession(), optionally passing configuration details for this session.
- Call parseInput(SnuggleInput) on one or more input documents to tokenise and fix-up the LaTeX contained therein.
- Call one or more of the DOM and/or web page building methods to generate the appropriate type of output.
- Call getErrors() to get at the errors that have arisen during this session.
- Call createSnapshot() at any time to make a "snapshot" of the current state for later reuse.
- An instance of this Class should only be used by one Thread at a time. It is stateful and intended to be discarded after use.
Version:

$Revision$

Author:

David McKain

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`SnuggleSession.EndOutputAction` Trivial enumeration which specifies the possible actions to perform once we finish writing with the various `writeWebPage(WebPageOutputOptions, OutputStream)` methods.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`NodeList`	`buildDOMSubtree()` Convenience method to build a DOM `NodeList` representing the converted Tokens.
`NodeList`	`buildDOMSubtree(DOMOutputOptions options)` Convenience method to build a DOM `NodeList` representing the converted Tokens.
`boolean`	`buildDOMSubtree(Element targetRoot)` Builds a DOM sub-tree based on the currently parsed tokens, appending the results as children of the given target root Element.
`boolean`	`buildDOMSubtree(Element targetRoot, DOMOutputOptions options)` Builds a DOM sub-tree based on the currently parsed tokens, appending the results as children of the given target root Element.
`Document`	`buildWebPage(WebPageOutputOptions options)` Builds a complete web page based on the currently parsed tokens, returning a DOM `Document` Object.
`String`	`buildWebPageString(WebPageOutputOptions options)` Builds a complete web page based on the currently parsed tokens, returning a String containing the resulting content.
`String`	`buildXMLString()` Creates a well-formed external general parsed entity out of the currently parsed tokens.
`String`	`buildXMLString(boolean indent)` Deprecated. Use `buildXMLString(XMLStringOutputOptions)` instead
`String`	`buildXMLString(DOMOutputOptions options)` Deprecated. Use `buildXMLString(XMLStringOutputOptions)` instead.
`String`	`buildXMLString(DOMOutputOptions options, boolean indent)` Deprecated. Use `buildXMLString(XMLStringOutputOptions)` instead.
`String`	`buildXMLString(XMLStringOutputOptions options)` Creates a well-formed external general parsed entity out of the currently parsed tokens.
`SnuggleSnapshot`	`createSnapshot()` Creates a `SnuggleSnapshot` Object holding the current state of this session that can be later used to recreate a session having exactly the same state.
`Document`	`createWebPage(WebPageOutputOptions options)` Deprecated.
`BuiltinCommand`	`getBuiltinCommandByTeXName(String texName)` Returns the `BuiltinCommand` corresponding to LaTeX command called `\texName`, or null if this command is not defined.
`BuiltinEnvironment`	`getBuiltinEnvironmentByTeXName(String texName)` Returns the `BuiltinEnvironment` corresponding to LaTeX environment called `texName`, or null if this environment is not defined.
`SessionConfiguration`	`getConfiguration()`
`List<InputError>`	`getErrors()`
`MathCharacter`	`getMathCharacter(int codePoint)`
`List<FlowToken>`	`getParsedTokens()`
`StylesheetManager`	`getStylesheetManager()` Gets the `StylesheetManager` being used by the underlying `SnuggleEngine`
`Map<String,UserDefinedCommand>`	`getUserCommandMap()` Gets the `Map` of all user-defined commands created in this session.
`Map<String,UserDefinedEnvironment>`	`getUserEnvironmentMap()` Gets the `Map` of all user-defined environments created in this session.
`boolean`	`parseInput(SnuggleInput snuggleInput)` Parses the data contained within the given `SnuggleInput`, and performs fixing on the resulting tokens.
`void`	`registerError(InputError inputError)` Records a new error, throwing a `SnuggleParseException` if the current `SessionConfiguration` deems that we should fail on the first error.
`void`	`reset()` Resets this `SnuggleSession` back to an initial blank state
`void`	`setWebPageContentType(WebPageOutputOptions options, Object contentTypeSettable)` Calls the `setContentType` of the given Object to something appropriate for the given `WebPageOutputOptions`.
`boolean`	`writeWebPage(WebPageOutputOptions options, Object contentTypeSettable, OutputStream outputStream)` Builds a complete web page based on the currently parsed tokens, sending the results to the given `OutputStream`, which is closed afterwards.
`boolean`	`writeWebPage(WebPageOutputOptions options, Object contentTypeSettable, OutputStream outputStream, SnuggleSession.EndOutputAction endOutputAction)` Builds a complete web page based on the currently parsed tokens, sending the results to the given `OutputStream` and performing the given `SnuggleSession.EndOutputAction` to it afterwards (i.e. close, flush or do nothing).
`boolean`	`writeWebPage(WebPageOutputOptions options, OutputStream outputStream)` Builds a complete web page based on the currently parsed tokens, sending the results to the given `OutputStream`, which is closed afterwards.
`boolean`	`writeWebPage(WebPageOutputOptions options, OutputStream outputStream, SnuggleSession.EndOutputAction endOutputAction)` Builds a complete web page based on the currently parsed tokens, sending the results to the given `OutputStream` and performing the given `SnuggleSession.EndOutputAction` to it afterwards (i.e. close, flush or do nothing).

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getConfiguration
```
public SessionConfiguration getConfiguration()
```
    Specified by:
    
    getConfiguration in interface SessionContext
  - getErrors
```
public List<InputError> getErrors()
```
    Specified by:
    
    getErrors in interface SessionContext
  - getParsedTokens
```
public List<FlowToken> getParsedTokens()
```
  - parseInput
```
public boolean parseInput(SnuggleInput snuggleInput)
                   throws IOException
```
    Parses the data contained within the given SnuggleInput, and performs fixing on the resulting tokens.
    
    Parameters:
    
    snuggleInput - input to parse, which must not be null
    
    Returns:
    
    true if parsing finished, false if it was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
    
    Throws:
    
    IOException
  - createSnapshot
```
public SnuggleSnapshot createSnapshot()
```
    Creates a SnuggleSnapshot Object holding the current state of this session that can be later used to recreate a session having exactly the same state.
  - reset
```
public void reset()
```
    Resets this SnuggleSession back to an initial blank state
  - buildDOMSubtree
```
public boolean buildDOMSubtree(Element targetRoot,
                               DOMOutputOptions options)
```
    Builds a DOM sub-tree based on the currently parsed tokens, appending the results as children of the given target root Element. The given DOMOutputOptions Object is used to configure the process.
    If the DOMOutputOptions specifies that MathML should be down-converted to XHTML where possible, then this will also happen.
    
    Returns:
    
    true if completed successfully, false if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
  - buildDOMSubtree
```
public boolean buildDOMSubtree(Element targetRoot)
```
    Builds a DOM sub-tree based on the currently parsed tokens, appending the results as children of the given target root Element. This uses the default DOMOutputOptions associated with this engine.
    
    Returns:
    
    true if completed successfully, false if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
  - buildDOMSubtree
```
public NodeList buildDOMSubtree()
```
    Convenience method to build a DOM NodeList representing the converted Tokens. These Nodes will belong to a "fake root" element in the SnuggleConstants.SNUGGLETEX_NAMESPACE namespace called "root".
    The default DOMOutputOptions specified in the SnuggleEngine will be used.
    
    Returns:
    
    resulting NodeList if the process completed successfully, null if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
  - buildDOMSubtree
```
public NodeList buildDOMSubtree(DOMOutputOptions options)
```
    Convenience method to build a DOM NodeList representing the converted Tokens. These Nodes will belong to a "fake root" element in the SnuggleConstants.SNUGGLETEX_NAMESPACE namespace called "root".
    The given DOMOutputOptions Object is used to configure the process, which must not be null.
    
    Parameters:
    
    options - DOMOutputOptions to use, which must not be null
    
    Returns:
    
    resulting NodeList if the process completed successfully, null if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
  - buildXMLString
```
public String buildXMLString()
```
    Creates a well-formed external general parsed entity out of the currently parsed tokens.
    The default XMLStringOutputOptions specified in the SnuggleEngine will be used.
    
    Returns:
    
    resulting XML if the process completed successfully, null if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
  - buildXMLString
```
public String buildXMLString(XMLStringOutputOptions options)
```
    Creates a well-formed external general parsed entity out of the currently parsed tokens.
    The given XMLStringOutputOptions Object is used to configure the process.
    
    Parameters:
    
    options - XMLStringOutputOptions to use, which must not be null.
    
    Returns:
    
    resulting XML if the process completed successfully, null if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
  - buildXMLString
```
@Deprecated
public String buildXMLString(boolean indent)
```
    Deprecated. Use buildXMLString(XMLStringOutputOptions) instead
    
    Convenience method to create a well-formed external general parsed entity out of the currently parsed tokens.
    The default DOMOutputOptions specified in the SnuggleEngine will be used.
    
    Parameters:
    
    indent - whether to indent the resulting XML or not
    
    Returns:
    
    resulting XML if the process completed successfully, null if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
  - buildXMLString
```
@Deprecated
public String buildXMLString(DOMOutputOptions options)
```
    Deprecated. Use buildXMLString(XMLStringOutputOptions) instead.
    
    Convenience method to create a well-formed external general parsed entity out of the currently parsed tokens.
    The given DOMOutputOptions Object is used to configure the process.
    
    Returns:
    
    resulting XML if the process completed successfully, null if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
  - buildXMLString
```
@Deprecated
public String buildXMLString(DOMOutputOptions options,
                                          boolean indent)
```
    Deprecated. Use buildXMLString(XMLStringOutputOptions) instead.
    
    Convenience method to create a well-formed external general parsed entity out of the currently parsed tokens.
    The given DOMOutputOptions Object is used to configure the process.
    
    Parameters:
    
    indent - whether to indent the resulting XML or not
    
    Returns:
    
    resulting XML if the process completed successfully, null if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
  - buildWebPage
```
public Document buildWebPage(WebPageOutputOptions options)
```
    Builds a complete web page based on the currently parsed tokens, returning a DOM Document Object.
    The provided WebPageOutputOptions Object is used to determine which type of web page to generate and how it should be configured.
    Any XSLT stylesheet specified by WebPageOutputOptions.getStylesheets() will have been applied to the result before it is returned. On the other hand, serialisation options in the WebPageOutputOptions (such as Content Type and encoding) will not have been applied when this method returns.
    
    Returns:
    
    resulting Document if the process completed successfully, null if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
  - createWebPage
```
@Deprecated
public Document createWebPage(WebPageOutputOptions options)
```
    Deprecated.
    
    For naming consistency, please use buildWebPage(WebPageOutputOptions) instead.
  - buildWebPageString
```
public String buildWebPageString(WebPageOutputOptions options)
```
    Builds a complete web page based on the currently parsed tokens, returning a String containing the resulting content. This is a convenience method; using writeWebPage(WebPageOutputOptions, OutputStream) might be more efficient.
    The provided WebPageOutputOptions Object is used to determine which type of web page to generate and how it should be configured.
    Any XSLT stylesheet specified by WebPageOutputOptions.getStylesheets() will have been applied to the result before it is returned. On the other hand, serialisation options in the WebPageOutputOptions (such as Content Type and encoding) will not have been applied when this method returns.
    
    Returns:
    
    resulting Document if the process completed successfully, null if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
    
    Since:
    
    1.3.0
  - writeWebPage
```
public boolean writeWebPage(WebPageOutputOptions options,
                            OutputStream outputStream)
                     throws IOException
```
    Builds a complete web page based on the currently parsed tokens, sending the results to the given OutputStream, which is closed afterwards.
    The provided WebPageOutputOptions Object is used to determine which type of web page to generate and how it should be configured.
    
    Returns:
    
    true if completed successfully, false if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
    
    Throws:
    
    IOException
  - writeWebPage
```
public boolean writeWebPage(WebPageOutputOptions options,
                            OutputStream outputStream,
                            SnuggleSession.EndOutputAction endOutputAction)
                     throws IOException
```
    Builds a complete web page based on the currently parsed tokens, sending the results to the given OutputStream and performing the given SnuggleSession.EndOutputAction to it afterwards (i.e. close, flush or do nothing).
    The provided WebPageOutputOptions Object is used to determine which type of web page to generate and how it should be configured.
    
    Returns:
    
    true if completed successfully, false if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
    
    Throws:
    
    IOException
    
    Since:
    
    1.2.2
  - writeWebPage
```
public boolean writeWebPage(WebPageOutputOptions options,
                            Object contentTypeSettable,
                            OutputStream outputStream)
                     throws IOException
```
    Builds a complete web page based on the currently parsed tokens, sending the results to the given OutputStream, which is closed afterwards.
    The provided WebPageOutputOptions Object is used to determine which type of web page to generate and how it should be configured.
    If the contentTypeSettable Object has a property called contentType, then it is set in advance to the appropriate HTTP Content-Type header for the resulting page before the web page data is written.
    
    Returns:
    
    true if completed successfully, false if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
    
    Throws:
    
    IOException - if an I/O problem arose whilst writing out the web page data.
    
    SnuggleRuntimeException - if calling setContentType() on the contentTypeSettable Object failed, with the underlying Exception wrapped up.
  - writeWebPage
```
public boolean writeWebPage(WebPageOutputOptions options,
                            Object contentTypeSettable,
                            OutputStream outputStream,
                            SnuggleSession.EndOutputAction endOutputAction)
                     throws IOException
```
    Builds a complete web page based on the currently parsed tokens, sending the results to the given OutputStream and performing the given SnuggleSession.EndOutputAction to it afterwards (i.e. close, flush or do nothing).
    The provided WebPageOutputOptions Object is used to determine which type of web page to generate and how it should be configured.
    If the contentTypeSettable Object has a property called contentType, then it is set in advance to the appropriate HTTP Content-Type header for the resulting page before the web page data is written.
    
    Returns:
    
    true if completed successfully, false if the process was terminated by an error in the input LaTeX and if the session was configured to fail on the first error.
    
    Throws:
    
    IOException - if an I/O problem arose whilst writing out the web page data.
    
    SnuggleRuntimeException - if calling setContentType() on the contentTypeSettable Object failed, with the underlying Exception wrapped up.
    
    Since:
    
    1.2.2
  - setWebPageContentType
```
public void setWebPageContentType(WebPageOutputOptions options,
                                  Object contentTypeSettable)
```
    Calls the setContentType of the given Object to something appropriate for the given WebPageOutputOptions. This may be useful in some cases.
    The main example for this would be passing a javax.servlet.http.HttpResponse Object, which I want to avoid a compile-time dependency on.
    
    See Also:
    
    writeWebPage(WebPageOutputOptions, Object, OutputStream)
  - getMathCharacter
```
public MathCharacter getMathCharacter(int codePoint)
```
    Specified by:
    
    getMathCharacter in interface SessionContext
  - getBuiltinCommandByTeXName
```
public BuiltinCommand getBuiltinCommandByTeXName(String texName)
```
    Returns the BuiltinCommand corresponding to LaTeX command called \texName, or null if this command is not defined.
    
    Specified by:
    
    getBuiltinCommandByTeXName in interface SessionContext
  - getBuiltinEnvironmentByTeXName
```
public BuiltinEnvironment getBuiltinEnvironmentByTeXName(String texName)
```
    Returns the BuiltinEnvironment corresponding to LaTeX environment called texName, or null if this environment is not defined.
    
    Specified by:
    
    getBuiltinEnvironmentByTeXName in interface SessionContext
  - getUserCommandMap
```
public Map<String,UserDefinedCommand> getUserCommandMap()
```
    Gets the Map of all user-defined commands created in this session.
    
    Specified by:
    
    getUserCommandMap in interface SessionContext
  - getUserEnvironmentMap
```
public Map<String,UserDefinedEnvironment> getUserEnvironmentMap()
```
    Gets the Map of all user-defined environments created in this session.
    
    Specified by:
    
    getUserEnvironmentMap in interface SessionContext
  - getStylesheetManager
```
public StylesheetManager getStylesheetManager()
```
    Gets the StylesheetManager being used by the underlying SnuggleEngine
    
    Specified by:
    
    getStylesheetManager in interface SessionContext
  - registerError
```
public void registerError(InputError inputError)
                   throws SnuggleParseException
```
    Records a new error, throwing a SnuggleParseException if the current SessionConfiguration deems that we should fail on the first error.
    
    Specified by:
    
    registerError in interface SessionContext
    
    Parameters:
    
    inputError - InputError to register, which must not be null.
    
    Throws:
    
    SnuggleParseException - if this session is configured to fail fast

Class SnuggleSession

Usage

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getConfiguration

getErrors

getParsedTokens

parseInput

createSnapshot

reset

buildDOMSubtree

buildDOMSubtree

buildDOMSubtree

buildDOMSubtree

buildXMLString

buildXMLString

buildXMLString

buildXMLString

buildXMLString

buildWebPage

createWebPage

buildWebPageString

writeWebPage

writeWebPage

writeWebPage

writeWebPage

setWebPageContentType

getMathCharacter

getBuiltinCommandByTeXName

getBuiltinEnvironmentByTeXName

getUserCommandMap

getUserEnvironmentMap

getStylesheetManager

registerError