net.sf.xaj.core
Class StaxXQuerySearchResults

java.lang.Object
  java.util.AbstractCollection<E>
      java.util.AbstractList<E>
          java.util.AbstractSequentialList<XmlResource>
              net.sf.xaj.core.StaxXQuerySearchResults

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<XmlResource>, java.util.Collection<XmlResource>, java.util.List<XmlResource>, XmlDb.XQuerySearchResults

public class StaxXQuerySearchResults
extends java.util.AbstractSequentialList<XmlResource>
implements XmlDb.XQuerySearchResults

Implementation of XmlDb.XQuerySearchResults using StAX parsing to conserve memory on large result sets.

There are some limitations to consider when using this class. Every XmlResource returned from AbstractSequentialList.iterator() should be "consumed" in some way before calling Iterator.next(). By "consumed" we refer to calling any of the XmlResource.getAs* or XmlResource.free() methods. This is because of how the XML input is internally streamed with StAX. Additionally, each XmlResource may only be consumed once.

This class can also be used as a convienent method of parsing a large XML document into smaller, individual XML resources by splitting the document into individual resources for each element that is a child of the root element. By default this class will skip the root element, returning one XmlResource for each element that is a child of the root element. Simply pass a null Metadata value to one of the constructors, and then you can call the AbstractSequentialList.iterator() method to get an iterator over these XML resources.

The Iterator returned by AbstractSequentialList.iterator() is an implementation of ListIterator but does not support the remove(), previous(), add(), or set() methods.

Version:

$Revision: 53 $ $Date: 2007-10-18 19:36:52 +1300 (Thu, 18 Oct 2007) $

Author:

matt

See Also:

Serialized Form

Field Summary

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

StaxXQuerySearchResults(java.io.Reader xmlStream, XmlDb.SearchResultsMetadata metadata)
Construct instance from stream.

StaxXQuerySearchResults(org.springframework.core.io.Resource xmlFile, XmlDb.SearchResultsMetadata metadata)
Construct instance.

StaxXQuerySearchResults(org.springframework.core.io.Resource xmlFile, XmlDb.SearchResultsMetadata metadata, boolean deleteOnClear)
Construct instance.

StaxXQuerySearchResults(org.springframework.core.io.Resource xmlFile, XmlDb.SearchResultsMetadata metadata, boolean deleteOnClear, java.util.concurrent.ExecutorService executorService)
Construct instance.

Method Summary

void	clear()
void	clearTempData() Delete the temporary file associated with this instance.
XmlDb.SearchResultsMetadata	getMetadata() Get the result metadata.
boolean	isSkipRootElement()
java.util.ListIterator<XmlResource>	listIterator(int index)
void	setSkipRootElement(boolean skipXmlDbXQueryResultListRootElement)
int	size()
java.lang.String	toString()

Methods inherited from class java.util.AbstractSequentialList

add, addAll, get, iterator, remove, set

Methods inherited from class java.util.AbstractList

add, equals, hashCode, indexOf, lastIndexOf, listIterator, removeRange, subList

Methods inherited from class java.util.AbstractCollection

addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List

add, add, addAll, addAll, contains, containsAll, equals, get, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, remove, remove, removeAll, retainAll, set, subList, toArray, toArray

Constructor Detail

StaxXQuerySearchResults

public StaxXQuerySearchResults(org.springframework.core.io.Resource xmlFile,
                               XmlDb.SearchResultsMetadata metadata)

Construct instance.

Calls #StaxXQuerySearchResults(File, SearchResultsMetadata, boolean) passing true for the deleteOnClear parameter.

Parameters:

xmlFile - the XML file to read from

metadata - the metadata

StaxXQuerySearchResults

public StaxXQuerySearchResults(org.springframework.core.io.Resource xmlFile,
                               XmlDb.SearchResultsMetadata metadata,
                               boolean deleteOnClear)

Construct instance.

Parameters:

xmlFile - the XML file to read from

metadata - the metadata

deleteOnClear - if true then delete the xml file when clear() is called, otherwise do not

StaxXQuerySearchResults

public StaxXQuerySearchResults(org.springframework.core.io.Resource xmlFile,
                               XmlDb.SearchResultsMetadata metadata,
                               boolean deleteOnClear,
                               java.util.concurrent.ExecutorService executorService)

Construct instance.

Parameters:

xmlFile - the XML file to read from

metadata - the metadata

deleteOnClear - if true then delete the xml file when clear() is called, otherwise do not

executorService - if provided, then will be used by returned XmlResource.getAsStream() method, to allow for returning large input streams via a PipedInputStream.

StaxXQuerySearchResults

public StaxXQuerySearchResults(java.io.Reader xmlStream,
                               XmlDb.SearchResultsMetadata metadata)

Construct instance from stream.

Parameters:

xmlStream - the XML data to read from

metadata - the metadata

Method Detail

listIterator

public java.util.ListIterator<XmlResource> listIterator(int index)

Specified by:

listIterator in interface java.util.List<XmlResource>

Specified by:

listIterator in class java.util.AbstractSequentialList<XmlResource>

size

public int size()

Specified by:

size in interface java.util.Collection<XmlResource>

Specified by:

size in interface java.util.List<XmlResource>

Specified by:

size in class java.util.AbstractCollection<XmlResource>

clear

public void clear()

Specified by:

clear in interface java.util.Collection<XmlResource>

Specified by:

clear in interface java.util.List<XmlResource>

Overrides:

clear in class java.util.AbstractList<XmlResource>

clearTempData

public void clearTempData()

Delete the temporary file associated with this instance.

This method can be called to delete the temp file holding the search results data. This might be useful in a running server, which does not terminate for a very long time but these objects are cached, even after this search results object might not be valid any more.

After calling this method, the instance is no longer valid and calls to other methods will fail. Repeated calls to this method have no effect.

getMetadata

public XmlDb.SearchResultsMetadata getMetadata()

Description copied from interface: XmlDb.XQuerySearchResults

Get the result metadata.

Specified by:

getMetadata in interface XmlDb.XQuerySearchResults

Returns:

metadata

toString

public java.lang.String toString()

Overrides:

toString in class java.util.AbstractCollection<XmlResource>

isSkipRootElement

public boolean isSkipRootElement()

Returns:

the skipXmlDbXQueryResultListRootElement

setSkipRootElement

public void setSkipRootElement(boolean skipXmlDbXQueryResultListRootElement)

Parameters:

skipXmlDbXQueryResultListRootElement - the skipXmlDbXQueryResultListRootElement to set