org.xbrlapi.loader
Class LoaderImpl

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

All Implemented Interfaces:

Serializable, Loader

Direct Known Subclasses:

LoaderImpl

public class LoaderImpl
extends Object
implements Loader

Implementation of the XBRL API Loader interface that validates using a pool of preparsed XML Schemas for XBRL documents.

Author:

Geoffrey Shuetrim (geoff@galexy.net)

See Also:

Serialized Form

Field Summary

static int	BIG_PRIME
static String	GRAMMAR_POOL Property identifier: grammar pool.
static String	SYMBOL_TABLE Property identifier: symbol table.

Constructor Summary

LoaderImpl(Store store, XLinkProcessor xlinkProcessor, EntityResolver entityResolver)

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

Method Summary

void	add(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.
boolean	equals(Object obj)
Document	getBuilderDOM()
Cache	getCache()
String	getCurrentFragmentId() Returns the current fragment index (the one before the next fragment index)
List<URI>	getDocumentsStillToAnalyse()
URI	getDocumentURI() Get the URI for the document being parsed.
EntityResolver	getEntityResolver() Return the entity resolver being used by the loader.
Fragment	getFragment()
History	getHistory()
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
int	hashCode()
boolean	hasHistory()
void	incrementFragmentId()
boolean	isBuildingAFragment()
boolean	isDiscovering()
protected void	markDocumentAsExplored(URI uri) Flag the document as being explored.
protected void	parse(URI uri) Parse an XML Document supplied as a URI.
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	replaceCurrentFragment(Fragment replacement) This is particularly useful when you can only fully determine the fragment type by reading in the complex element content of the data corresponding to the fragment.
void	requestInterrupt() Interrupts the loading process once the current document discovery has been completed.
void	setCache(Cache 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	setHistory(History newHistory)
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	stashURIs(List<URI> uris)
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, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

SYMBOL_TABLE

public static final String SYMBOL_TABLE

Property identifier: symbol table.

See Also:

Constant Field Values

GRAMMAR_POOL

public static final String GRAMMAR_POOL

Property identifier: grammar pool.

See Also:

Constant Field Values

BIG_PRIME

public static final int BIG_PRIME

See Also:

Constant Field Values

Constructor Detail

LoaderImpl

public LoaderImpl(Store store,
                  XLinkProcessor xlinkProcessor,
                  EntityResolver entityResolver)
           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,
                  EntityResolver entityResolver,
                  List<URI> uris)
           throws XBRLException

Parameters:

store - The data store to hold the DTS

xlinkProcessor - The XLink processor to use for link resolution

entityResolver - The entity resolver to use for resources being loaded.

uris - The array of URIs for loading.

Throws:

XBRLException - if the loader cannot be instantiated.

Method Detail

requestInterrupt

public void requestInterrupt()

Description copied from interface: Loader

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

See Also:

Loader.requestInterrupt()

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()

setCache

public void setCache(Cache 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(Cache)

getCache

public Cache 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()

getBuilderDOM

public Document getBuilderDOM()
                       throws XBRLException

Specified by:

getBuilderDOM in interface Loader

Returns:

The document node of the XML DOM used by this loader's fragment builders. This should only be used when creating a new fragment using the loader.

Throws:

XBRLException

See Also:

Loader.getBuilderDOM()

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()

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 URI 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()

Description copied from interface: Loader

Get the XLink processor

Specified by:

getXlinkProcessor in interface Loader

Returns:

The XLink processor used in the DTS discovery process

See Also:

Loader.getXlinkProcessor()

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

Specified by:

getFragment in interface Loader

Returns:

the fragment being built currently by the loader or null if no fragments are currently being build by the loader.

Throws:

XBRLException

See Also:

Loader.getFragment()

replaceCurrentFragment

public void replaceCurrentFragment(Fragment replacement)
                            throws XBRLException

Description copied from interface: Loader

This is particularly useful when you can only fully determine the fragment type by reading in the complex element content of the data corresponding to the fragment. A case in point is the fractionItem fragment type.

Specified by:

replaceCurrentFragment in interface Loader

Parameters:

replacement - the fragment to replace the current fragment being build with.

Throws:

XBRLException - if there is no current fragment.

See Also:

Loader.replaceCurrentFragment(Fragment)

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()

add

public void add(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:

add 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.add(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<URI> 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. If the store is using persisted networks, then once a discovery process completes without having any failures and without being interrupted, then it will automatically update the persisted networks to reflect relationships defined by all newly added XLink arcs.

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. Note that this does not update the persisted relationships because there is no guarantee that when the method finishes the data store represents an actual DTS.

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.

markDocumentAsExplored

protected void markDocumentAsExplored(URI uri)

Flag the document as being explored. Ensure that loading rights for this document have been recinded so that other loaders can act as they deem appropriate.

Throws:

XBRLException

parse

protected void parse(URI uri)
              throws XBRLException,
                     SAXException,
                     IOException

Parse an XML Document supplied as a URI.

Parameters:

uri - The URI of the document to parse.

Throws:

XBRLException - IOException ParserConfigurationException SAXException

ParserConfigurationException

SAXException

IOException

parse

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

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 - IOException SAXException ParserConfigurationException

SAXException

IOException

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

Description copied from interface: Loader

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.

Throws:

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

See Also:

Loader.stashURI(URI)

stashURIs

public void stashURIs(List<URI> uris)
               throws XBRLException

Specified by:

stashURIs in interface Loader

Parameters:

uris - The list of URIs to be stashed.

Throws:

XBRLException

See Also:

Loader.stashURIs(List)

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 or null if you want to use a default entity resolver (without any caching facilities)

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()

hashCode

public int hashCode()

Overrides:

hashCode in class Object

See Also:

Object.hashCode()

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

See Also:

Object.equals(java.lang.Object)

setHistory

public void setHistory(History newHistory)

Specified by:

setHistory in interface Loader

Parameters:

newHistory - The history recording system to use for all new documents being loaded. If this is null then the history is set to a naive history that just logs the historic information.

See Also:

Loader.setHistory(History)

getHistory

public History getHistory()

Specified by:

getHistory in interface Loader

Returns:

the history recording system being used to record the documents being loaded.

See Also:

Loader.getHistory()

hasHistory

public boolean hasHistory()

Specified by:

hasHistory in interface Loader

Returns:

true if the loader is using a history recording system to record the URIs being loaded and their document identifiers.

See Also:

Loader.hasHistory()

parse

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

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 - SAXException IOException

SAXException

IOException