oracle.ifs.beans.parsers
Interface Parser

All Known Implementing Classes:

XmlParser, IfsXmlParser

public interface Parser

A Parser operates on one or more LibraryObjects based on data read from an InputStream or Reader.

Parsers are typically used to create new LibraryObjects in the repository. For example, an XML Parser creates LibraryObjects based on XML input; a Multipart MIME Parser creates LibraryObjects based on multipart MIME input.

Generally, a given Parser can create objects of any LibraryObject subclass. For example, an XML Parser could create Folders, Documents, a mixture of these, or any other LibraryObject subclass. However, a specialized Parser capable of parsing only Documents (for example) could throw an exception if the InputStream or Reader described a DirectoryUser.

A Parser typically determines which LibraryObject subclass to create based on the InputStream or Reader. However, some Parsers may allow or even require this to be specified through the options parameter to the parse method.

If the InputStream or Reader describes more than one LibraryObject, a parser may elect either to create each object as it goes or to create all objects upon reaching the end of the stream.

Choosing the correct Parser is the application's responsibility. An application might do this based on filename extension, MIME type, explicit user input, or any other mechanism appropriate for that application.

Parsers should provide a constructor with the following signature: Parser(LibrarySession) throws IfsException.

Field Summary

static java.lang.String	CURRENT_NAME_OPTION Key for hashtable option which specifies the current working name.
static java.lang.String	CURRENT_PATH_OPTION Key for hashtable option which specifies the current working folder path.
static java.lang.String	DOCUMENT_CHARSET_OPTION Key for hashtable option which specifies the character set of a document.
static java.lang.String	DOCUMENT_LANGUAGE_OPTION Key for hashtable option which specifies the language of a document.
static java.lang.String	UPDATE_OBJECT_OPTION Option which indicates the existing iFS object being updated by this call to the Parser.
static java.lang.String	VALIDATE_DOCUMENT_OPTION Key for hashtable option which specifies whether an XML document should be validated against its corresponding DTD.

Method Summary

LibraryObject	parse(java.io.InputStream stream, ParserCallback callback, java.util.Hashtable options) Parses the specified InputStream.
LibraryObject	parse(java.io.Reader reader, ParserCallback callback, java.util.Hashtable options) Parses the specified Reader.

Field Detail

CURRENT_PATH_OPTION

public static final java.lang.String CURRENT_PATH_OPTION

Key for hashtable option which specifies the current working folder path. Applications can set this option if the current path is known. Parsers may need this information when dealing with relative paths or creating PublicObjects.

CURRENT_NAME_OPTION

public static final java.lang.String CURRENT_NAME_OPTION

Key for hashtable option which specifies the current working name. Applications can set this option if the current name is known. Parsers may need this information when dealing with foldered object.

VALIDATE_DOCUMENT_OPTION

public static final java.lang.String VALIDATE_DOCUMENT_OPTION

Key for hashtable option which specifies whether an XML document should be validated against its corresponding DTD.

DOCUMENT_CHARSET_OPTION

public static final java.lang.String DOCUMENT_CHARSET_OPTION

Key for hashtable option which specifies the character set of a document.

DOCUMENT_LANGUAGE_OPTION

public static final java.lang.String DOCUMENT_LANGUAGE_OPTION

Key for hashtable option which specifies the language of a document.

UPDATE_OBJECT_OPTION

public static final java.lang.String UPDATE_OBJECT_OPTION

Option which indicates the existing iFS object being updated by this call to the Parser. If this option is set, then the parser should attempt to update the object set as the value for this option key in the Option hashtable.

Method Detail

parse

public LibraryObject parse(java.io.InputStream stream,
                           ParserCallback callback,
                           java.util.Hashtable options)
                    throws IfsException

Parses the specified InputStream.

Parameters:

stream - the InputStream

callback - an application object that interacts with the the parsing process; optional, can be null

options - any Parser-specific options

Returns:

The primary object created. If there is only one top level object then this is returned. If no object is "primary" then null is returned.

Throws:

IfsException - (IFS-12601) if the operation fails

parse

public LibraryObject parse(java.io.Reader reader,
                           ParserCallback callback,
                           java.util.Hashtable options)
                    throws IfsException

Parses the specified Reader.

Parameters:

reader - the Reader

callback - an application object that interacts with the the parsing process; optional, can be null

options - any Parser-specific options

Returns:

The primary object created. If there is only one top level object then this is returned. If no object is "primary" then null is returned.

Throws:

IfsException - (IFS-12602) if the operation fails