org.xbrlapi.loader
Class LoaderImpl

java.lang.Object
  org.xbrlapi.loader.LoaderImpl

All Implemented Interfaces:

Loader

Direct Known Subclasses:

LoaderImpl

public class LoaderImpl
extends Object
implements Loader

Implementation of the XBRL API Loader interface. The loader is responsible for managing the DTS discovery process. It manages: 1. the queue of documents to be explored 2. the document discovery process 3. the stack of fragments being built and stored 4. The fragment naming scheme Features of the loader include: 1. The ability to interupt the document discovery process between documents without losing track of the documents remaining to be discovered. Interrupts can be requested and cancelled.

Author:

Geoffrey Shuetrim (geoff@galexy.net)

Constructor Summary

LoaderImpl(Store store, XLinkProcessor xlinkProcessor)

LoaderImpl(Store store, XLinkProcessor xlinkProcessor, List<URI> uris)

Method Summary

void	addFragment(Fragment fragment, ElementState state) Push a new fragment onto the stack of fragments that are being built by the loader.
void	cancelInterrupt() Cancels a request for an interrupt.
void	discover() Begin the XBRL DTS discovery process with the URIs that are already in the loading/discovery queue.
void	discover(List<URI> startingURIs) Begin the XBRL DTS discovery process with the specified URIs given in the provided list.
void	discover(String uri) Trigger the discovery process given a single URI.
void	discover(URI uri) Trigger the discovery process given a single URI.
void	discover(URI uri, String xml) Perform a discovery starting with an XML document that is represented as a string.
void	discoverNext() Parses the next document in the queue of documents to be discovered.
void	extendChildren() Add a new node to the vector of children being tracked for the current fragment.
CacheImpl	getCache()
Vector<Long>	getChildrenVector() The children vector contains an item for each element that has been started and that has not yet been ended by the SAX content handler.
String	getCurrentFragmentId() Returns the current fragment index (the one before the next fragment index)
List<String>	getDocumentsStillToAnalyse()
String	getDocumentURI() Get the URI for the document being parsed.
EntityResolver	getEntityResolver() Return the entity resolver being used by the loader.
Fragment	getFragment() Get the fragment that is currently being built by the DTS loader
String	getNextFragmentId() Also increments the fragment index as a side-effect.
Store	getStore() Get the data store used by a loader.
XLinkProcessor	getXlinkProcessor() Get the Xlink processor used by the loader.
void	incrementChildren() Increment the children tracker to show that a new element has been found.
void	incrementFragmentId()
boolean	isBuildingAFragment()
boolean	isDiscovering()
protected void	parse(URI uri) Parse an XML Document supplied as a URI the next part of the DTS.
protected void	parse(URI uri, InputSource inputSource, ContentHandler contentHandler) Parse the supplied input source.
protected void	parse(URI uri, String xml) Parse an XML Document supplied as a string the next part of the DTS.
void	prepareToTrackChildrenForNewFragment() Add a new child tracking vector to the childrenStack to use for the new fragment that is being built by the loader.
void	requestInterrupt() Interrupts the loading process once the current document discovery has been completed.
void	setCache(CacheImpl cache) This method specifies a cache to use when loading data into the data store.
void	setEntityResolver(EntityResolver resolver) Set the resolver for the resolution of entities found during the loading and XLink processing
void	setSchemaLocationAttributeUsage(boolean useThem)
protected void	setStartingURIs(List<URI> uris) Set the starting points for DTSImpl discovery using a linked list
void	stashURI(URI uri) Stash a URI to await loading into DTS.
void	storeDocumentsToAnalyse() Stores the stubs for the documents still to be analysed in the data store being used by the loader.
void	updateState(ElementState state) If a fragment is completed, remove the fragment from the stack being maintained by the loader, store it in the data store and make the necessary update to the stack of child counts for the fragments.
boolean	useSchemaLocationAttributes() The default behaviour is to ignore the content of XML Schema instance schemaLocation attributes.

Methods inherited from class java.lang.Object

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

Constructor Detail

LoaderImpl

public LoaderImpl(Store store,
                  XLinkProcessor xlinkProcessor)
           throws XBRLException

Parameters:

store - The data store to hold the DTS

xlinkProcessor - The XLink processor to use for link resolution

Throws:

XBRLException - if the loader cannot be instantiated.

LoaderImpl

public LoaderImpl(Store store,
                  XLinkProcessor xlinkProcessor,
                  List<URI> uris)
           throws XBRLException

Parameters:

store - The data store to hold the DTS

xlinkProcessor - The XLink processor to use for link resolution

uris - The array of URIs for loading.

Throws:

XBRLException - if the loader cannot be instantiated.

Method Detail

setCache

public void setCache(CacheImpl cache)

Description copied from interface: Loader

This method specifies a cache to use when loading data into the data store. The cache is only useful (and thus only needs to be specified) when discovering XML that is provided as a string rather than a resource that actually exists at a specified URI. This is because generally the caching mechanism available via the entityResolver will handle caching for documents that actually exist at the specified URI. care must be taken to ensure that the cache used by the loader is using the same local root folder as the cache used by the entityResolver. This is because the documents cached by the loader can then be sought in the cache by the entity resolver.

Specified by:

setCache in interface Loader

Parameters:

cache - The cache to use in the loader

See Also:

Loader.setCache(CacheImpl)

getCache

public CacheImpl getCache()
                   throws XBRLException

Specified by:

getCache in interface Loader

Returns:

The cache to be used by the loader.

Throws:

XBRLException - if the cache is null.

See Also:

Loader.getCache()

isDiscovering

public boolean isDiscovering()

Specified by:

isDiscovering in interface Loader

Returns:

true if the loader is current engaged in document discovery and false otherwise.

See Also:

Loader.isDiscovering()

requestInterrupt

public void requestInterrupt()

Interrupts the loading process once the current document discovery has been completed. This can be useful when the loader is shared among several threads.

Specified by:

requestInterrupt in interface Loader

cancelInterrupt

public void cancelInterrupt()

Description copied from interface: Loader

Cancels a request for an interrupt.

Specified by:

cancelInterrupt in interface Loader

See Also:

Loader.cancelInterrupt()

getStore

public Store getStore()

Get the data store used by a loader.

Specified by:

getStore in interface Loader

Returns:

The DTS store to be used for holding the information in the DTS

getDocumentURI

public String getDocumentURI()

Get the URI for the document being parsed.

Specified by:

getDocumentURI in interface Loader

Returns:

The original (non-cache) URI of the document being parsed.

getXlinkProcessor

public XLinkProcessor getXlinkProcessor()

Get the Xlink processor used by the loader. TODO Should the getter for the loader Xlink Processor be public?

Specified by:

getXlinkProcessor in interface Loader

Returns:

The XLink processor used in the DTS discovery process

prepareToTrackChildrenForNewFragment

public void prepareToTrackChildrenForNewFragment()
                                          throws XBRLException

Add a new child tracking vector to the childrenStack to use for the new fragment that is being built by the loader. Initialise it with a single node containing the value of zero to signify that the root element of the new fragment has not had any child elements found for it yet.

Specified by:

prepareToTrackChildrenForNewFragment in interface Loader

Throws:

XBRLException

getChildrenVector

public Vector<Long> getChildrenVector()

The children vector contains an item for each element that has been started and that has not yet been ended by the SAX content handler.

Specified by:

getChildrenVector in interface Loader

Returns:

The vector of children or null if none exist (implying no parent fragments).

incrementChildren

public void incrementChildren()

Description copied from interface: Loader

Increment the children tracker to show that a new element has been found.

Specified by:

incrementChildren in interface Loader

See Also:

Loader.incrementChildren()

extendChildren

public void extendChildren()
                    throws XBRLException

Add a new node to the vector of children being tracked for the current fragment. Initialise its value to zero to capture the fact that no children have been found for the newly processed element - as yet.

Specified by:

extendChildren in interface Loader

Throws:

XBRLException

updateState

public void updateState(ElementState state)
                 throws XBRLException

Description copied from interface: Loader

If a fragment is completed, remove the fragment from the stack being maintained by the loader, store it in the data store and make the necessary update to the stack of child counts for the fragments.

Specified by:

updateState in interface Loader

Parameters:

state - The element state for the element currently being parsed.

Throws:

XBRLException

See Also:

Loader.updateState(ElementState)

getFragment

public Fragment getFragment()
                     throws XBRLException

Description copied from interface: Loader

Get the fragment that is currently being built by the DTS loader

Specified by:

getFragment in interface Loader

Returns:

the fragment being built currently by the DTS loader.

Throws:

XBRLException - if the loader is not building any fragments.

See Also:

Loader.getFragment()

isBuildingAFragment

public boolean isBuildingAFragment()

Specified by:

isBuildingAFragment in interface Loader

Returns:

true if and only if the loader has one or more fragments on the stack of fragments being built.

See Also:

Loader.isBuildingAFragment()

addFragment

public void addFragment(Fragment fragment,
                        ElementState state)
                 throws XBRLException

Description copied from interface: Loader

Push a new fragment onto the stack of fragments that are being built by the loader.

Specified by:

addFragment in interface Loader

Parameters:

fragment - The fragment to be added to the stack of fragments being built by the loader.

state - The state of the element that is the root of the fragment.

Throws:

XBRLException

See Also:

Loader.addFragment(Fragment, ElementState)

discover

public void discover(List<URI> startingURIs)
              throws XBRLException

Description copied from interface: Loader

Begin the XBRL DTS discovery process with the specified URIs given in the provided list.

Specified by:

discover in interface Loader

Parameters:

startingURIs - The starting point URIs for the DTS discovery process Trigger the discovery process given the starting URIs.

Throws:

XBRLException - if the input list contains objects other than java.net.URIs.

See Also:

Loader.discover(List)

discover

public void discover(URI uri)
              throws XBRLException

Description copied from interface: Loader

Trigger the discovery process given a single URI.

Specified by:

discover in interface Loader

Parameters:

uri - The URI to discover.

Throws:

XBRLException

See Also:

Loader.discover(URI)

discover

public void discover(String uri)
              throws XBRLException

Description copied from interface: Loader

Trigger the discovery process given a single URI.

Specified by:

discover in interface Loader

Parameters:

uri - The URI to discover.

Throws:

XBRLException

See Also:

Loader.discover(String)

getDocumentsStillToAnalyse

public List<String> getDocumentsStillToAnalyse()

Specified by:

getDocumentsStillToAnalyse in interface Loader

Returns:

the list of documents that are known to still need parsing into the data store.

See Also:

Loader.getDocumentsStillToAnalyse()

discover

public void discover()
              throws XBRLException

Description copied from interface: Loader

Begin the XBRL DTS discovery process with the URIs that are already in the loading/discovery queue.

Specified by:

discover in interface Loader

Throws:

XBRLException - if the discovery process fails.

See Also:

Loader.discover()

discoverNext

public void discoverNext()
                  throws XBRLException

Description copied from interface: Loader

Parses the next document in the queue of documents to be discovered. This updates the data store and updates the queue with any new documents that are identified.

Specified by:

discoverNext in interface Loader

Throws:

XBRLException - if the discovery process fails.

See Also:

Loader.discoverNext()

discover

public void discover(URI uri,
                     String xml)
              throws XBRLException

Perform a discovery starting with an XML document that is represented as a string.

Specified by:

discover in interface Loader

Parameters:

uri - The URI to be used for the document that is supplied as a string. This URI MUST be an absolute URI.

xml - The string representation of the XML document to be parsed.

Throws:

XBRLException - if the discovery process fails or if the supplied URI is not absolute or is not a valid URI syntax or the loader does not have a cache.

parse

protected void parse(URI uri)
              throws XBRLException

Parse an XML Document supplied as a URI the next part of the DTS.

Parameters:

uri - The URI of the document to parse.

Throws:

XBRLException

parse

protected void parse(URI uri,
                     String xml)
              throws XBRLException

Parse an XML Document supplied as a string the next part of the DTS.

Parameters:

uri - The URI to associate with the supplied XML.

xml - The XML document as a string.

Throws:

XBRLException

parse

protected void parse(URI uri,
                     InputSource inputSource,
                     ContentHandler contentHandler)
              throws XBRLException

Parse the supplied input source.

Parameters:

uri - The URI to be associated with the supplied input source.

inputSource - The input source to parse.

contentHandler - The content handler to use for SAX parsing.

Throws:

XBRLException

setStartingURIs

protected void setStartingURIs(List<URI> uris)
                        throws XBRLException

Set the starting points for DTSImpl discovery using a linked list

Parameters:

uris - A list of starting point document URIs for DTSImpl discovery

Throws:

XBRLException

stashURI

public void stashURI(URI uri)
              throws XBRLException

Stash a URI to await loading into DTS.

Specified by:

stashURI in interface Loader

Parameters:

uri - The absolute URI to be stashed (any relative URI gets resolved against the Base URI before stashing. TODO put this functionality at the SAX parse call for the document. TODO make sure that the fragment after the # is handled for stashed URIs in the loader.

Throws:

XBRLException - if the URI cannot be stored for later exploration or if the URI is not absolute

setEntityResolver

public void setEntityResolver(EntityResolver resolver)

Set the resolver for the resolution of entities found during the loading and XLink processing

Specified by:

setEntityResolver in interface Loader

Parameters:

resolver - An entity resolver implementation

getNextFragmentId

public String getNextFragmentId()
                         throws XBRLException

Description copied from interface: Loader

Also increments the fragment index as a side-effect. TODO eliminate the side-effect of the getNextFragmentId method.

Specified by:

getNextFragmentId in interface Loader

Returns:

the next unique fragment index

Throws:

XBRLException

getCurrentFragmentId

public String getCurrentFragmentId()

Description copied from interface: Loader

Returns the current fragment index (the one before the next fragment index)

Specified by:

getCurrentFragmentId in interface Loader

Returns:

the next unique fragment index

incrementFragmentId

public void incrementFragmentId()

getEntityResolver

public EntityResolver getEntityResolver()

Return the entity resolver being used by the loader.

Specified by:

getEntityResolver in interface Loader

Returns:

the entity resolver being used by the loader.

useSchemaLocationAttributes

public boolean useSchemaLocationAttributes()

Description copied from interface: Loader

The default behaviour is to ignore the content of XML Schema instance schemaLocation attributes.

Specified by:

useSchemaLocationAttributes in interface Loader

Returns:

true if the loader is required to discover documents identified in XML Schema instance schemaLocation attributes.

See Also:

Loader.useSchemaLocationAttributes()

setSchemaLocationAttributeUsage

public void setSchemaLocationAttributeUsage(boolean useThem)

Specified by:

setSchemaLocationAttributeUsage in interface Loader

Parameters:

useThem - must be set to true if you want to discover documents identified in XML Schema instance schemaLocation attributes and false otherwise.

See Also:

Loader.setSchemaLocationAttributeUsage(boolean)

storeDocumentsToAnalyse

public void storeDocumentsToAnalyse()
                             throws XBRLException

Description copied from interface: Loader

Stores the stubs for the documents still to be analysed in the data store being used by the loader.

Specified by:

storeDocumentsToAnalyse in interface Loader

Throws:

XBRLException

See Also:

Loader.storeDocumentsToAnalyse()