org.xbrlapi.loader
Interface Loader

All Superinterfaces:

Serializable

All Known Implementing Classes:

LoaderImpl, LoaderImpl

public interface Loader
extends Serializable

Loader defines the functions required to get a DTS into the data store ready for interactions via the XBRL API. In many regards, this performs a similar role to an XML parser in that it triggers the exploration process and eventually populates a data structure.

Author:

Geoffrey Shuetrim (geoff@galexy.net)

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.
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 DTS storage implementation
XLinkProcessor	getXlinkProcessor() Get the XLink processor
boolean	hasHistory()
boolean	isBuildingAFragment()
boolean	isDiscovering()
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 history)
void	setSchemaLocationAttributeUsage(boolean useThem)
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.

Method Detail

getStore

Store getStore()

Get the DTS storage implementation

Returns:

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

getXlinkProcessor

XLinkProcessor getXlinkProcessor()

Get the XLink processor

Returns:

The XLink processor used in the DTS discovery process

setEntityResolver

void setEntityResolver(EntityResolver resolver)

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

Parameters:

resolver - An entity resolver implementation or null if the loader is to use a default entity resolver that does not allow for caching.

setCache

void setCache(Cache cache)

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.

Parameters:

cache - The cache to use in the loader.

getCache

Cache getCache()
               throws XBRLException

Returns:

The cache to be used by the loader.

Throws:

XBRLException - if the cache is null.

getBuilderDOM

Document getBuilderDOM()
                       throws XBRLException

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

getDocumentsStillToAnalyse

List<URI> getDocumentsStillToAnalyse()

Returns:

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

discover

void discover()
              throws XBRLException

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.

Throws:

XBRLException - if the discovery process fails.

discoverNext

void discoverNext()
                  throws XBRLException

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.

Throws:

XBRLException - if the discovery process fails.

discover

void discover(URI uri,
              String xml)
              throws XBRLException

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

Parameters:

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

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

Throws:

XBRLException - if the discovery process fails.

discover

void discover(List<URI> startingURIs)
              throws XBRLException

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

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.

discover

void discover(URI uri)
              throws XBRLException

Trigger the discovery process given a single URI.

Parameters:

uri - The URI to discover.

Throws:

XBRLException

discover

void discover(String uri)
              throws XBRLException

Trigger the discovery process given a single URI.

Parameters:

uri - The URI to discover.

Throws:

XBRLException

stashURI

void stashURI(URI uri)
              throws XBRLException

Stash a URI to await loading into DTS.

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.

stashURIs

void stashURIs(List<URI> uris)
               throws XBRLException

Parameters:

uris - The list of URIs to be stashed.

Throws:

XBRLException

getFragment

Fragment getFragment()
                     throws XBRLException

Returns:

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

Throws:

XBRLException

replaceCurrentFragment

void replaceCurrentFragment(Fragment replacement)
                            throws XBRLException

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.

Parameters:

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

Throws:

XBRLException - if there is no current fragment.

isBuildingAFragment

boolean isBuildingAFragment()

Returns:

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

isDiscovering

boolean isDiscovering()

Returns:

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

add

void add(Fragment fragment,
         ElementState state)
         throws XBRLException

Push a new fragment onto the stack of fragments that are being built by the 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

updateState

void updateState(ElementState state)
                 throws XBRLException

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.

Parameters:

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

Throws:

XBRLException

getNextFragmentId

String getNextFragmentId()
                         throws XBRLException

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

Returns:

the next unique fragment index

Throws:

XBRLException

getCurrentFragmentId

String getCurrentFragmentId()
                            throws XBRLException

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

Returns:

the next unique fragment index

Throws:

XBRLException

getDocumentURI

URI getDocumentURI()

Get the URI for the document being parsed.

Returns:

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

getEntityResolver

EntityResolver getEntityResolver()

Return the entity resolver being used by the loader.

Returns:

the entity resolver being used by the loader.

useSchemaLocationAttributes

boolean useSchemaLocationAttributes()

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

Returns:

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

setSchemaLocationAttributeUsage

void setSchemaLocationAttributeUsage(boolean useThem)

Parameters:

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

requestInterrupt

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.

cancelInterrupt

void cancelInterrupt()

Cancels a request for an interrupt.

storeDocumentsToAnalyse

void storeDocumentsToAnalyse()
                             throws XBRLException

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

Throws:

XBRLException

setHistory

void setHistory(History history)

Parameters:

history - 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.

getHistory

History getHistory()

Returns:

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

hasHistory

boolean hasHistory()

Returns:

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