org.apache.xmlgraphics.ps.dsc
Class DSCParser

java.lang.Object
  org.apache.xmlgraphics.ps.dsc.DSCParser

All Implemented Interfaces:

DSCParserConstants

public class DSCParser
extends Object
implements DSCParserConstants

Parser for DSC-compliant PostScript files (DSC = Document Structuring Conventions). The parser is implemented as a pull parser but has the ability to act as a push parser through the DSCHandler interface.

Field Summary

Fields inherited from interface org.apache.xmlgraphics.ps.dsc.DSCParserConstants

COMMENT, DSC_COMMENT, EOF, HEADER_COMMENT, LINE

Constructor Summary

DSCParser(InputStream in)
Creates a new DSC parser.

Method Summary

void	addListener(DSCListener listener) Adds a DSC event listener.
DSCEvent	getCurrentEvent() Returns the current event.
InputStream	getInputStream() Returns the InputStream the PostScript code is read from.
String	getLine() Returns the current PostScript line.
boolean	hasNext() Indicates whether there are additional items.
boolean	isCheckEOF() Indicates whether the parser is configured to check for content after the EOF comment.
boolean	isListenersDisabled() Indicates whether the listeners are currently disabled.
int	next() Steps to the next item indicating the type of event.
DSCComment	nextDSCComment(String name) Advances to the next DSC comment with the given name.
DSCComment	nextDSCComment(String name, PSGenerator gen) Advances to the next DSC comment with the given name.
DSCEvent	nextEvent() Steps to the next item returning the new event.
PostScriptComment	nextPSComment(String prefix, PSGenerator gen) Advances to the next PostScript comment with the given prefix.
void	parse(DSCHandler handler) Starts the parser in push parsing mode sending events to the DSCHandler instance.
protected void	parseNext() Parses the next event.
DSCEvent	peek() Returns the next event without moving the cursor to the next event.
protected String	readLine() Reads one line from the input file
void	removeListener(DSCListener listener) Removes a DSC event listener.
void	setCheckEOF(boolean value) Tells the parser whether to check for content after the EOF comment.
void	setFilter(DSCFilter filter) Sets a filter for DSC events.
void	setListenersDisabled(boolean value) Allows to disable all listeners.
void	setNestedDocumentHandler(NestedDocumentHandler handler) Sets a NestedDocumentHandler which is used to skip nested documents like embedded EPS files.
protected void	warn(String msg) This method is used to write out warning messages for the parsing process.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DSCParser

public DSCParser(InputStream in)
          throws IOException,
                 DSCException

Creates a new DSC parser.

Parameters:

in - InputStream to read the PostScript file from (the stream is not closed by this class, the caller is responsible for that)

Throws:

IOException - In case of an I/O error

DSCException - In case of a violation of the DSC spec

Method Detail

getInputStream

public InputStream getInputStream()

Returns the InputStream the PostScript code is read from.

Returns:

the InputStream the PostScript code is read from

warn

protected void warn(String msg)

This method is used to write out warning messages for the parsing process. Subclass to override this method. The default implementation writes to logger.

Parameters:

msg - the warning message

readLine

protected String readLine()
                   throws IOException,
                          DSCException

Reads one line from the input file

Returns:

the line or null if there are no more lines

Throws:

IOException - In case of an I/O error

DSCException - In case of a violation of the DSC spec

parse

public void parse(DSCHandler handler)
           throws IOException,
                  DSCException

Starts the parser in push parsing mode sending events to the DSCHandler instance.

Parameters:

handler - the DSCHandler instance to send the events to

Throws:

IOException - In case of an I/O error

DSCException - In case of a violation of the DSC spec

hasNext

public boolean hasNext()

Indicates whether there are additional items.

Returns:

true if there are additonal items, false if the end of the file has been reached

next

public int next()
         throws IOException,
                DSCException

Steps to the next item indicating the type of event.

Returns:

the type of event (See DSCParserConstants)

Throws:

IOException - In case of an I/O error

DSCException - In case of a violation of the DSC spec

NoSuchElementException - If an attempt was made to advance beyond the end of the file

nextEvent

public DSCEvent nextEvent()
                   throws IOException,
                          DSCException

Steps to the next item returning the new event.

Returns:

the new event

Throws:

IOException - In case of an I/O error

DSCException - In case of a violation of the DSC spec

getCurrentEvent

public DSCEvent getCurrentEvent()

Returns the current event.

Returns:

the current event

peek

public DSCEvent peek()

Returns the next event without moving the cursor to the next event.

Returns:

the next event

parseNext

protected void parseNext()
                  throws IOException,
                         DSCException

Parses the next event.

Throws:

IOException - In case of an I/O error

DSCException - In case of a violation of the DSC spec

getLine

public String getLine()

Returns the current PostScript line.

Returns:

the current PostScript line

Throws:

IllegalStateException - if the current event is not a normal PostScript line

nextDSCComment

public DSCComment nextDSCComment(String name)
                          throws IOException,
                                 DSCException

Advances to the next DSC comment with the given name.

Parameters:

name - the name of the DSC comment

Returns:

the requested DSC comment or null if the end of the file is reached

Throws:

IOException - In case of an I/O error

DSCException - In case of a violation of the DSC spec

nextDSCComment

public DSCComment nextDSCComment(String name,
                                 PSGenerator gen)
                          throws IOException,
                                 DSCException

Advances to the next DSC comment with the given name.

Parameters:

name - the name of the DSC comment

gen - PSGenerator to pass the skipped events though to

Returns:

the requested DSC comment or null if the end of the file is reached

Throws:

IOException - In case of an I/O error

DSCException - In case of a violation of the DSC spec

nextPSComment

public PostScriptComment nextPSComment(String prefix,
                                       PSGenerator gen)
                                throws IOException,
                                       DSCException

Advances to the next PostScript comment with the given prefix. This is used to find comments following the DSC extension mechanism.

Example: To find FOP's custom comments, pass in "FOP" as a prefix. This will find comments like "%FOPFontSetup".

Parameters:

prefix - the prefix of the extension comment

gen - PSGenerator to pass the skipped events though to

Returns:

the requested PostScript comment or null if the end of the file is reached

Throws:

IOException - In case of an I/O error

DSCException - In case of a violation of the DSC spec

setFilter

public void setFilter(DSCFilter filter)

Sets a filter for DSC events.

Parameters:

filter - the filter to use or null to disable filtering

addListener

public void addListener(DSCListener listener)

Adds a DSC event listener.

Parameters:

listener - the listener

removeListener

public void removeListener(DSCListener listener)

Removes a DSC event listener.

Parameters:

listener - the listener to remove

setListenersDisabled

public void setListenersDisabled(boolean value)

Allows to disable all listeners. This can be used to disable any filtering, for example in nested documents.

Parameters:

value - true to disable all listeners, false to re-enable them

isListenersDisabled

public boolean isListenersDisabled()

Indicates whether the listeners are currently disabled.

Returns:

true if they are disabled

setNestedDocumentHandler

public void setNestedDocumentHandler(NestedDocumentHandler handler)

Sets a NestedDocumentHandler which is used to skip nested documents like embedded EPS files. You can also process those parts in a special way.

It is suggested to use the more generally usable addListener(DSCListener) and removeListener(DSCListener) instead. NestedDocumentHandler is internally mapped onto a DSCListener.

Parameters:

handler - the NestedDocumentHandler instance or null to disable the feature

setCheckEOF

public void setCheckEOF(boolean value)

Tells the parser whether to check for content after the EOF comment. This can be disabled to skip nested documents.

Parameters:

value - true if the check is enabled

isCheckEOF

public boolean isCheckEOF()

Indicates whether the parser is configured to check for content after the EOF comment.

Returns:

true if the check is enabled.