ca.macewan.ims.enterprise.io
Class IMSEnterpriseParser

java.lang.Object
  ca.macewan.ims.enterprise.io.IMSEnterpriseProcessor
      ca.macewan.ims.enterprise.io.IMSEnterpriseImportProcessor
          ca.macewan.ims.enterprise.io.IMSEnterpriseParser

public class IMSEnterpriseParser

extends ca.macewan.ims.enterprise.io.IMSEnterpriseImportProcessor

IMSEnterpriseParser lets you read the top-level elements of an IMS enterprise XML document one at a time, much like an iterator. This is as opposed to the IMSEnterpriseReader class, which reads the complete document in one read action. The advantages of this parser as opposed to the document-style reader class are mainly in terms of resource efficiency. Some IMS enterprise XML documents can get fairly large, and reading a document of several megabytes in file size can easily cause the JVM to run out of memory. This parser class can be used to avoid such memory issues. It allows you instead to read each top-level element and extract only the information you really need. Top-leve elements in the IMS enterprise specification include comments, properties, person, group and membership elements. Please note that this means that the parser class never returns an actual Enterprise object.

The parser class is set up more or less as an iterator. First, create the parser by passing it the inputstream for the IMS enterprise XML file in the constructor. Then, iterate over the top-level elements using the hasNext and next methods. The next method returns an integer value representing the type of element that was just processed. Use this to select the proper getXXXX method to read the actual object representing the IMS enterprise element.

IMSEnterpriseParser parser = new IMSEnterpriseParser(someInputStream);
while (parser.hasNext()) {
        int type = parser.next();
        switch (type) {
                case ELEMENT_PERSON:
                        processPersonElement(parser.getCurrentPerson());
                        break;
                case ELEMENT_GROUP:
                        processGroupElement(parser.getCurrentGroup());
                        break;
                default:
                        break;
        }
}
 

Version:

0.1

Author:

Erwin Veugelers

Field Summary

static int	ELEMENT_COMMENTS Constant indicating the top-level element last processed was a comments element.
static int	ELEMENT_GROUP Constant indicating the top-level element last processed was a group element.
static int	ELEMENT_MEMBERSHIP Constant indicating the top-level element last processed was a membership element.
static int	ELEMENT_NONE Constant indicating there are no top-level elements available at this time.
static int	ELEMENT_PERSON Constant indicating the top-level element last processed was a person element.
static int	ELEMENT_PROPERTIES Constant indicating the top-level element last processed was a properties element.
static int	ELEMENT_UNKNOWN Constant indicating the top-level element last processed was not recognized.

Constructor Summary

IMSEnterpriseParser(InputStream in)
Creates an IMSEnterpriseParser with the given InputStream to access the IMS enterprise XML information.

IMSEnterpriseParser(String readerClass, InputStream in)
Creates an IMSEnterpriseParser with the given InputStream to access the IMS enterprise XML information.

Method Summary

Comments	getCurrentComments() Get the current IMS enterprise element as a Comments object.
Group	getCurrentGroup() Get the current IMS enterprise element as a Group object.
Membership	getCurrentMembership() Get the current IMS enterprise element as a Membership object.
Person	getCurrentPerson() Get the current IMS enterprise element as a Person object.
Properties	getCurrentProperties() Get the current IMS enterprise element as a Properties object.
int	getElementType() Returns the IMS enterprise element type of the currently available element.
boolean	hasNext() Returns true if there are more IMS enterprise elements available.
boolean	isIMSValidating() Returns true if IMS enterprise validation is turned on.
boolean	isXMLValidating() Returns true if XML validation is turned on.
int	next() Moves the parser on to the next element, and returns the type of the element read.
void	setIMSValidating(boolean v) Turn IMS enterprise validation on or off.
void	setValidating(boolean v) Convenience method to set both XML validation and IMS enterprise validation with one method.
void	setXMLValidating(boolean v) Turn XML validation on or off.

Methods inherited from class java.lang.Object

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

Field Detail

ELEMENT_UNKNOWN

public static final int ELEMENT_UNKNOWN

Constant indicating the top-level element last processed was not recognized.

See Also:

Constant Field Values

ELEMENT_NONE

public static final int ELEMENT_NONE

Constant indicating there are no top-level elements available at this time.

See Also:

Constant Field Values

ELEMENT_COMMENTS

public static final int ELEMENT_COMMENTS

Constant indicating the top-level element last processed was a comments element.

See Also:

Constant Field Values

ELEMENT_PROPERTIES

public static final int ELEMENT_PROPERTIES

Constant indicating the top-level element last processed was a properties element.

See Also:

Constant Field Values

ELEMENT_PERSON

public static final int ELEMENT_PERSON

Constant indicating the top-level element last processed was a person element.

See Also:

Constant Field Values

ELEMENT_GROUP

public static final int ELEMENT_GROUP

Constant indicating the top-level element last processed was a group element.

See Also:

Constant Field Values

ELEMENT_MEMBERSHIP

public static final int ELEMENT_MEMBERSHIP

Constant indicating the top-level element last processed was a membership element.

See Also:

Constant Field Values

Constructor Detail

IMSEnterpriseParser

public IMSEnterpriseParser(InputStream in)
                    throws IMSEnterpriseException

Creates an IMSEnterpriseParser with the given InputStream to access the IMS enterprise XML information. The system JSR173 XMLInputFactory class is used.

Parameters:

in - The InputStream to access the IMS enterprise XML information.

IMSEnterpriseParser

public IMSEnterpriseParser(String readerClass,
                           InputStream in)
                    throws IMSEnterpriseException

Creates an IMSEnterpriseParser with the given InputStream to access the IMS enterprise XML information. The first argument is used to specify the JSR173 XMLInputFactory class to be used. Check the JSR173 documentation for more information.

Parameters:

readerClass - The XMLInputFactory class to use.

in - The InputStream to access the IMS enterprise XML information.

See Also:

JSR173 API

Method Detail

setValidating

public void setValidating(boolean v)

Convenience method to set both XML validation and IMS enterprise validation with one method. See setXMLValidating and setIMSValidating.

Parameters:

v - Whether or not to enable both IMS enterprise validation and XML validation.

setIMSValidating

public void setIMSValidating(boolean v)

Turn IMS enterprise validation on or off. If true, the parser will call the validate method on the IMS enterprise objects being read, and calls to hasNext and next may throw an IMSEnterpriseException if the information in the object is not valid according to the IMS enterprise specification.

Parameters:

v - Whether or not to enable IMS enterprise validation.

isIMSValidating

public boolean isIMSValidating()

Returns true if IMS enterprise validation is turned on.

Returns:

Whether or not IMS enterprise validation is turned on.

setXMLValidating

public void setXMLValidating(boolean v)

Turn XML validation on or off. The parser will set the underlying JSR173 XML reader validating property to the value of the method argument. This level of validation deals with XML document structure, rather than with IMS enterprise specification validation (see setIMSValidating). Subsequent calls to hasNext and next may throw an IMSEnterpriseException wrapping any XML exceptions.

Parameters:

v - Whether or not to enable XML validation.

isXMLValidating

public boolean isXMLValidating()

Returns true if XML validation is turned on.

Returns:

Whether or not XML validation is turned on.

hasNext

public boolean hasNext()
                throws IMSEnterpriseException

Returns true if there are more IMS enterprise elements available.

Note: This method will move the parser on to the next element, so the current element will no longer be avaiable after a call to hasNext. This means that the following two code fragments are currently functionally equivalent, although they really shouldn't be.

while (parser.hasNext()) {
        int type = parser.next();
}

while (parser.hasNext()) {
        int type = parser.getElementType();
}
 

This may change in a future release. Note that you can call getElementType more than once, though, without causing additional reads, which is not true for calls to next.

Returns:

Whether or not any IMS enterprise elements are available to read.

Throws:

IMSEnterpriseException - An exception is thrown only if something untoward happens while parsing the next element. If no more elements are available, the method simply returns false.

next

public int next()
         throws IMSEnterpriseException

Moves the parser on to the next element, and returns the type of the element read. (Check hasNext for an important caveat).

Returns:

The type of the IMS enterprise element read.

Throws:

IMSEnterpriseException - An exception is thrown if a call to next is made when no more elements are available. See hasNext.

getElementType

public int getElementType()

Returns the IMS enterprise element type of the currently available element.

Returns:

The type of the currently available element.

getCurrentComments

public Comments getCurrentComments()

Get the current IMS enterprise element as a Comments object. If the current element is not a comments element, this method will return null.

Returns:

The currently available element as a Comments object.

getCurrentProperties

public Properties getCurrentProperties()

Get the current IMS enterprise element as a Properties object. If the current element is not a properties element, this method will return null.

Returns:

The currently available element as a Properties object.

getCurrentGroup

public Group getCurrentGroup()

Get the current IMS enterprise element as a Group object. If the current element is not a group element, this method will return null.

Returns:

The currently available element as a Group object.

getCurrentPerson

public Person getCurrentPerson()

Get the current IMS enterprise element as a Person object. If the current element is not a person element, this method will return null.

Returns:

The currently available element as a Person object.

getCurrentMembership

public Membership getCurrentMembership()

Get the current IMS enterprise element as a Membership object. If the current element is not a membership element, this method will return null.

Returns:

The currently available element as a Membership object.