org.xbrlapi.data
Class BaseStoreImpl

java.lang.Object
  org.xbrlapi.data.BaseStoreImpl

All Implemented Interfaces:

Serializable, Store

Direct Known Subclasses:

XBRLStoreImpl

public abstract class BaseStoreImpl
extends Object
implements Store, Serializable

Abstract base implementation of the data store providing all methods of the store interface that do not depend on the nature of the underlying data store implementation.

Author:

Geoffrey Shuetrim (geoff@galexy.net)

See Also:

Serialized Form

Field Summary

protected static org.apache.log4j.Logger	logger
protected Matcher	matcher Resource matcher
protected HashMap<String,String>	namespaceBindings Namespace bindings
protected Document	storeDOM The DOM document used to construct DOM representations of subtrees of documents in the store.

Constructor Summary

BaseStoreImpl()

Method Summary

void	clearFilteringURIs() Specify that the data store is not to filter query results to only come from a specified set of URIs.
void	close() Close the data store.
void	deleteDocument(String uri) This deletion method does not ensure that all other documents that link to the document being deleted are also deleted.
void	deleteRelatedDocuments(String uri) This deletion method ensures that all related documents are also deleted from the data store.
protected String	DOM2String(Element element) Convert a DOM element (and its descendents) to a string.
Document	formCompositeDocument() Get all data in the store as a single XML DOM object including the annotations used in the XBRLComposer project.
<F extends Fragment> FragmentList<F>	getChildFragments(String interfaceName, String parentIndex)
Element	getDocumentAsDOM(String uri) Get a single document in the store as a DOM.
String	getDocumentId(String document)
List<URI>	getDocumentsToDiscover()
FragmentList<Fact>	getFacts()
FragmentList<Fact>	getFacts(URI uri)
List<String>	getFilteringURIs()
protected Element	getFollowingSibling(Element parentElement, int precedingSiblings) Get the following sibling of this fragment's root in the parent fragment's data.
<F extends Fragment> FragmentList<F>	getFragments(String interfaceName) Utility method to return a list of fragments in a data store that have a type corresponding to the specified fragment interface name.
<F extends Fragment> FragmentList<F>	getFragmentsFromDocument(URI uri, String interfaceName) Utility method to return a list of fragments in a data store that have a type corresponding to the specified fragment interface name and that are in the document with the specified URI.
FragmentList<Item>	getItems()
FragmentList<Item>	getItems(URI uri)
Language	getLanguage(String encoding, String code)
FragmentList<Language>	getLanguages(String code)
Matcher	getMatcher()
Networks	getNetworks(String arcRole)
Networks	getNetworks(String linkrole, String arcrole)
String	getNextFragmentId() Get the next fragment ID to use when extending a DTS, instead of starting at 1 again and corrupting the DTS data store with duplicate fragment IDs.
List<String>	getReferencedDocuments(String uri) Override this method in a data store implementation if the data store implementation supports XQuery (rather than XPath).
List<String>	getReferencingDocuments(String uri) Override this method in a data store implementation if the data store implementation supports XQuery (rather than XPath).
<F extends Fragment> F	getRootFragmentForDocument(String uri)
<F extends Fragment> FragmentList<F>	getRootFragments()
Document	getStoreAsDOM() Get all documents in the store as a single DOM.
Networks	getStoredNetworks()
List<String>	getStoredURIs() Get a list of the URIs that have been stored.
Fragment	getStub(String uri)
FragmentList<Fragment>	getStubs()
Element	getSubtree(Fragment f) Returns the root element of the subtree starting with the fragment with the specified index.
protected String	getURIFilteringQueryClause()
boolean	hasDocument(String uri) Test if a particular URI is already in the data store.
boolean	hasStoredNetworks()
boolean	isFilteringByURIs()
void	removeStub(String stubId)
void	saveDocuments(File destination) Saves the individual documents in the data store into a directory structure that is placed into the specified directory.
void	saveDocuments(File destination, String uriPrefix) Serializes those documents in the data store with a URI that begins with the specified URI prefix.
void	saveStoreAsSingleDocument(File file) Creates a single DOM structure from all documents in the data store and saves this single XML structure in the specified file.
void	serialize(Element what) Serialize the specified XML DOM to System.out.
void	serialize(Element what, File destination) Serialize the specified XML DOM to the specified destination.
void	serialize(Element what, OutputStream destination) Serialize the specified XML DOM to the specified destination.
void	serialize(Element what, String destination) Serialize the specified XML DOM to the specified destination file.
void	serialize(Fragment fragment) Serialize the specified fragment.
String	serializeToString(Element what) Serialize the specified XML DOM node.
void	setFilteringURIs(List<String> uris)
void	setMatcher(Matcher matcher) Sets the matcher for the store to use.
void	setNamespaceBinding(String namespace, String prefix)
void	setStoredNetworks(Networks networks)
void	storeLoaderState(List<String> documents) Stores the state of the document discovery process.
void	storeStub(String document)

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.xbrlapi.data.Store

delete, getFragment, hasFragment, query, queryForIndices, removeFragment, storeFragment

Field Detail

logger

protected static org.apache.log4j.Logger logger

storeDOM

protected Document storeDOM

The DOM document used to construct DOM representations of subtrees of documents in the store.

matcher

protected Matcher matcher

Resource matcher

namespaceBindings

protected HashMap<String,String> namespaceBindings

Namespace bindings

Constructor Detail

BaseStoreImpl

public BaseStoreImpl()

Method Detail

setMatcher

public void setMatcher(Matcher matcher)
                throws XBRLException

Description copied from interface: Store

Sets the matcher for the store to use. Care should be taken to ensure that the one matcher is used for all documents in the store.

Specified by:

setMatcher in interface Store

Parameters:

matcher - the matcher to use to identify identical resources.

Throws:

XBRLException - if the matcher is null;

See Also:

Store.setMatcher(Matcher)

getMatcher

public Matcher getMatcher()

Specified by:

getMatcher in interface Store

Returns:

the matcher used by the store to identify identical resources.

See Also:

Store.getMatcher()

setNamespaceBinding

public void setNamespaceBinding(String namespace,
                                String prefix)
                         throws XBRLException

Specified by:

setNamespaceBinding in interface Store

Parameters:

namespace - The namespace to bind a prefix to for querying

prefix - The prefix to bind to the namespace for querying

Throws:

XBRLException - if either argument is null.

See Also:

Store.setNamespaceBinding(String,String)

setFilteringURIs

public void setFilteringURIs(List<String> uris)

Specified by:

setFilteringURIs in interface Store

Parameters:

uris - The list of URIs to restrict query results to coming from.

See Also:

Store.setFilteringURIs(List)

getFilteringURIs

public List<String> getFilteringURIs()

Specified by:

getFilteringURIs in interface Store

Returns:

the list of URIs to filter query results using or null if no such list of URIs is being used by the data store.

See Also:

Store.getFilteringURIs()

clearFilteringURIs

public void clearFilteringURIs()

Description copied from interface: Store

Specify that the data store is not to filter query results to only come from a specified set of URIs.

Specified by:

clearFilteringURIs in interface Store

See Also:

Store.clearFilteringURIs()

isFilteringByURIs

public boolean isFilteringByURIs()

Specified by:

isFilteringByURIs in interface Store

Returns:

true if the data store is restricting query results to come from a specific set of documents and false otherwise.

See Also:

Store.isFilteringByURIs()

getURIFilteringQueryClause

protected String getURIFilteringQueryClause()

Returns:

an X Query clause that restricts the set of fragments returned by a query to those from a specific set of URIs.

close

public void close()
           throws XBRLException

Close the data store. Throws XBRLException if the data store cannot be closed.

Specified by:

close in interface Store

Throws:

XBRLException

storeLoaderState

public void storeLoaderState(List<String> documents)
                      throws XBRLException

Description copied from interface: Store

Stores the state of the document discovery process.

Specified by:

storeLoaderState in interface Store

Parameters:

documents - The list of URIs of the documents remaining to be discovered.

Throws:

XBRLException

See Also:

Store.storeLoaderState(List)

storeStub

public void storeStub(String document)
               throws XBRLException

Specified by:

storeStub in interface Store

Parameters:

document - The document to store a stub for.

Throws:

XBRLException

See Also:

Store.storeStub(String)

getDocumentId

public String getDocumentId(String document)
                     throws XBRLException

Specified by:

getDocumentId in interface Store

Parameters:

document - The string representation of the document content.

Returns:

the hash value for the string representing the content of the document.

Throws:

XBRLException

See Also:

Store.getDocumentId(String)

serialize

public void serialize(Element what,
                      OutputStream destination)
               throws XBRLException

Serialize the specified XML DOM to the specified destination.

Specified by:

serialize in interface Store

Parameters:

what - the root element of the DOM to be serialised.

destination - The destination output stream to be serialised to.

Throws:

XBRLException - if the DOM cannot be serialised because the destination cannot be written to or some other different problem occurs during serialisation.

serialize

public void serialize(Element what)
               throws XBRLException

Serialize the specified XML DOM to System.out.

Specified by:

serialize in interface Store

Parameters:

what - the root element of the DOM to be serialised.

Throws:

XBRLException

serialize

public void serialize(Fragment fragment)
               throws XBRLException

Serialize the specified fragment.

Specified by:

serialize in interface Store

Parameters:

fragment - The fragment to be serialised.

Throws:

XBRLException

serializeToString

public String serializeToString(Element what)
                         throws XBRLException

Serialize the specified XML DOM node.

Specified by:

serializeToString in interface Store

Parameters:

what - the root element of the DOM to be serialised.

Returns:

a string containing the serialized XML.

Throws:

XBRLException

deleteDocument

public void deleteDocument(String uri)
                    throws XBRLException

Description copied from interface: Store

This deletion method does not ensure that all other documents that link to the document being deleted are also deleted. This can cause relationships in the data store to be non-resolvable.

Specified by:

deleteDocument in interface Store

Parameters:

uri - The URI of the document to delete from the data store.

Throws:

XBRLException

See Also:

Store.deleteDocument(String)

deleteRelatedDocuments

public void deleteRelatedDocuments(String uri)
                            throws XBRLException

Description copied from interface: Store

This deletion method ensures that all related documents are also deleted from the data store.

Specified by:

deleteRelatedDocuments in interface Store

Parameters:

uri - The URI of the document to delete.

Throws:

XBRLException

getReferencingDocuments

public List<String> getReferencingDocuments(String uri)
                                     throws XBRLException

Description copied from interface: Store

Override this method in a data store implementation if the data store implementation supports XQuery (rather than XPath).

Specified by:

getReferencingDocuments in interface Store

Parameters:

uri - The URI of the referenced document.

Returns:

a list of the URIs of the documents directly referencing the specified document as targets of their XLinks (custom or otherwise).

Throws:

XBRLException - if the list of referencing documents cannot be populated.

See Also:

Store.getReferencingDocuments(String)

getReferencedDocuments

public List<String> getReferencedDocuments(String uri)
                                    throws XBRLException

Description copied from interface: Store

Override this method in a data store implementation if the data store implementation supports XQuery (rather than XPath).

Specified by:

getReferencedDocuments in interface Store

Parameters:

uri - The URI of the referencing document.

Returns:

a list of the documents directly referenced by this document.

Throws:

XBRLException - if the list of referenced documents cannot be populated.

See Also:

Store.getReferencedDocuments(String)

serialize

public void serialize(Element what,
                      File destination)
               throws XBRLException

Serialize the specified XML DOM to the specified destination. create the necessary directory if it does not exist. Use the file to create a file outputstream.

Specified by:

serialize in interface Store

Parameters:

what - the root element of the DOM to be serialised.

destination - The destination file to be serialised to.

Throws:

XBRLException - if the DOM cannot be serialised because the destination cannot be written to or some other different problem occurs during serialisation.

serialize

public void serialize(Element what,
                      String destination)
               throws XBRLException

Serialize the specified XML DOM to the specified destination file.

Specified by:

serialize in interface Store

Parameters:

what - the root element of the DOM to be serialised.

destination - The destination file to be serialised to.

Throws:

XBRLException - if the DOM cannot be serialised because the destination cannot be written to or some other different problem occurs during serialisation.

getStoredURIs

public List<String> getStoredURIs()
                           throws XBRLException

Get a list of the URIs that have been stored.

Specified by:

getStoredURIs in interface Store

Returns:

a list of the URIs in the data store.

Throws:

XBRLException - if the list cannot be constructed.

hasDocument

public boolean hasDocument(String uri)
                    throws XBRLException

Description copied from interface: Store

Test if a particular URI is already in the data store.

Specified by:

hasDocument in interface Store

Parameters:

uri - the string representation of the URI to be tested for.

Returns:

true if the document is in the store and false otherwise.

Throws:

XBRLException - if the document cannot be constructed as a DOM.

See Also:

Store.hasDocument(String)

getDocumentAsDOM

public Element getDocumentAsDOM(String uri)
                         throws XBRLException

Get a single document in the store as a DOM. Note that this will not reflect the original document in some ways. Importantly, entities will be resolved and document type declarations will be missing. Document encodings may also differ. If the original document is required, simply use the supplied URI to get a copy of the original document.

Specified by:

getDocumentAsDOM in interface Store

Parameters:

uri - The string representation of the URI of the document to be retrieved.

Returns:

a DOM Document containing the XML representation of the file at the specified URI. Returns null if the store does not contain a document with the given URI.

Throws:

XBRLException - if the document cannot be constructed as a DOM.

getSubtree

public Element getSubtree(Fragment f)
                   throws XBRLException

Returns the root element of the subtree starting with the fragment with the specified index. All subtrees for a given store instance are produced from the one XML DOM and so can be appended to eachother as required.

Specified by:

getSubtree in interface Store

Parameters:

f - The fragment at the root of the subtree.

Returns:

The root element of the subtree headed by the fragment with the specified index.

Throws:

XBRLException - if the subtree cannot be constructed.

getFollowingSibling

protected Element getFollowingSibling(Element parentElement,
                                      int precedingSiblings)

Get the following sibling of this fragment's root in the parent fragment's data.

Parameters:

parentElement - The parent element in the parent fragment's data.

precedingSiblings - The number of sibling elements preceding the element of interest.

Returns:

the following sibling of this fragment's root (or null if there is no preceding sibling).

getStoreAsDOM

public Document getStoreAsDOM()
                       throws XBRLException

Get all documents in the store as a single DOM. Note that this will not reflect the original documents in some ways. Importantly, entities will be resolved and document type declarations will be missing. Document encodings may also differ. If the original documents are required, simply use the URIs captured in the data store to get a copy of the original document. @see org.xbrlapi.data.Store#getStoredURIs() for more details. Get all data in the store as a single XML DOM object.

Specified by:

getStoreAsDOM in interface Store

Returns:

the XML DOM representation of the XBRL information in the data store.

Throws:

XBRLException - if the DOM cannot be constructed.

formCompositeDocument

public Document formCompositeDocument()
                               throws XBRLException

Get all data in the store as a single XML DOM object including the annotations used in the XBRLComposer project.

Specified by:

formCompositeDocument in interface Store

Returns:

the composed data store as a DOM object.

Throws:

XBRLException - if the composed data store cannot be constructed.

getNextFragmentId

public String getNextFragmentId()
                         throws XBRLException

Description copied from interface: Store

Get the next fragment ID to use when extending a DTS, instead of starting at 1 again and corrupting the DTS data store with duplicate fragment IDs.

Specified by:

getNextFragmentId in interface Store

Returns:

The next ID to use for the next fragment to be added to the DTS.

Throws:

XBRLException

See Also:

Store.getNextFragmentId()

getStubs

public FragmentList<Fragment> getStubs()
                                throws XBRLException

Specified by:

getStubs in interface Store

Returns:

a list of stub fragments (Those fragments indicating a document that needs to be added to the data store).

Throws:

XBRLException

See Also:

Store.getStubs()

getStub

public Fragment getStub(String uri)
                 throws XBRLException

Specified by:

getStub in interface Store

Parameters:

uri - The string value of the URI of the document to get the stub for.

Returns:

the stub fragment or null if none exists.

Throws:

XBRLException - if there is more than one stub.

See Also:

Store.getStub(String)

removeStub

public void removeStub(String stubId)
                throws XBRLException

Specified by:

removeStub in interface Store

Parameters:

stubId - The URI of the document for which the stub fragment is to be removed from the data store.

Throws:

XBRLException

See Also:

Store.getStub(String stubId)

getDocumentsToDiscover

public List<URI> getDocumentsToDiscover()
                                 throws XBRLException

Specified by:

getDocumentsToDiscover in interface Store

Returns:

the list of URIs of the documents remaining to be analysed.

Throws:

XBRLException - if any of the document URIs are malformed.

See Also:

Store.getDocumentsToDiscover()

saveDocuments

public void saveDocuments(File destination)
                   throws XBRLException

Saves the individual documents in the data store into a directory structure that is placed into the specified directory. The directory structure that is created mirrors the structure of the URIs of the documents. Note that the URIs of the documents that are written out will be reflected in the paths to those documents using the same rules as those applied for document caching.

Specified by:

saveDocuments in interface Store

Parameters:

destination - The folder in which the directory structure and the documents in the data store are to be saved.

Throws:

XBRLException - If the root folder does not exist or is not a directory or if the documents in the store cannot be saved to the local file system.

saveDocuments

public void saveDocuments(File destination,
                          String uriPrefix)
                   throws XBRLException

Serializes those documents in the data store with a URI that begins with the specified URI prefix. They are saved to the local file system in the same manner as is applied for the saveDocuments method that operates on all documents in the data store.

Specified by:

saveDocuments in interface Store

Parameters:

destination - The folder in which the directory structure and the documents in the data store are to be saved.

uriPrefix - All documents in the data store with a URI that begins with the string specified by uriPrefix will be saved to the local file system.

Throws:

XBRLException - If the root folder does not exist or is not a directory or if the documents in the store cannot be saved to the local file system.

saveStoreAsSingleDocument

public void saveStoreAsSingleDocument(File file)
                               throws XBRLException

Creates a single DOM structure from all documents in the data store and saves this single XML structure in the specified file.

Specified by:

saveStoreAsSingleDocument in interface Store

Parameters:

file - The file to save the Store content to.

Throws:

XBRLException - if the documents in the store cannot be saved to the single file.

DOM2String

protected String DOM2String(Element element)

Convert a DOM element (and its descendents) to a string.

Parameters:

element - The element to convert to a string.

Returns:

The string that is the serialised element.

Throws:

XBRLException - if an IO exception occurs.

getFragments

public <F extends Fragment> FragmentList<F> getFragments(String interfaceName)
                                              throws XBRLException

Description copied from interface: Store

Utility method to return a list of fragments in a data store that have a type corresponding to the specified fragment interface name.

Specified by:

getFragments in interface Store

Parameters:

interfaceName - The name of the interface. EG: If a list of org.xbrlapi.impl.ReferenceArcImpl fragments is required then this parameter would have a value of "ReferenceArc". Note that if the parameter contains full stops, then it is used directly as the value for the fragment type, enabling fragment extensions to exploit this method without placing fragment implementations in the org.xbrlapi package.

Returns:

a list of fragments with the given fragment type.

Throws:

XBRLException

See Also:

Store.getFragments(String)

getChildFragments

public <F extends Fragment> FragmentList<F> getChildFragments(String interfaceName,
                                                              String parentIndex)
                                                   throws XBRLException

Specified by:

getChildFragments in interface Store

Parameters:

interfaceName - The name of the interface. EG: If a list of org.xbrlapi.impl.ReferenceArcImpl fragments is required then this parameter would have a value of "ReferenceArc". Note that this method does not yet recognise fragment subtypes so a request for an Arc would not return all ReferenceArcs as well as other types of arcs.

parentIndex - The index of the parent fragment.

Returns:

a list of fragments with the given fragment type and with the given parent fragment.

Throws:

XBRLException

See Also:

Store.getChildFragments(String, String)

getNetworks

public Networks getNetworks(String arcRole)
                     throws XBRLException

Specified by:

getNetworks in interface Store

Parameters:

arcRole - The XLink arcrole value.

Returns:

the collection of networks expressed using arcs that involve this arc role.

Throws:

XBRLException

See Also:

Store.getNetworks(String)

getNetworks

public Networks getNetworks(String linkrole,
                            String arcrole)
                     throws XBRLException

Specified by:

getNetworks in interface Store

Parameters:

linkrole - The linkrole of the networks.

arcrole - The arcrole of the networks.

Returns:

the collection of networks expressed using arcs that involve this linkrole and arcrole.

Throws:

XBRLException

See Also:

Store.getNetworks(String,String)

getFragmentsFromDocument

public <F extends Fragment> FragmentList<F> getFragmentsFromDocument(URI uri,
                                                                     String interfaceName)
                                                          throws XBRLException

Utility method to return a list of fragments in a data store that have a type corresponding to the specified fragment interface name and that are in the document with the specified URI.

Specified by:

getFragmentsFromDocument in interface Store

Parameters:

uri - The URI of the document to get the fragments from.

interfaceName - The name of the interface. EG: If a list of org.xbrlapi.impl.ReferenceArcImpl fragments is required then this parameter would have a value of "ReferenceArc". Note that this method does not yet recognise fragment subtypes so a request for an Arc would not return all ReferenceArcs as well as other types of arcs.

Returns:

a list of fragments with the given fragment type and in the given document.

Throws:

XBRLException

See Also:

ArcImpl

getFacts

public FragmentList<Fact> getFacts()
                            throws XBRLException

Returns:

a list of all of the root-level facts in the data store (those facts that are children of the root element of an XBRL instance). Returns an empty list if no facts are found.

Throws:

XBRLException

getItems

public FragmentList<Item> getItems()
                            throws XBRLException

Returns:

a list of all of the root-level items in the data store(those items that are children of the root element of an XBRL instance). TODO eliminate the redundant retrieval of tuples from the getItems methods.

Throws:

XBRLException

getFacts

public FragmentList<Fact> getFacts(URI uri)
                            throws XBRLException

Parameters:

uri - The URI of the document to get the facts from.

Returns:

a list of all of the root-level facts in the specified document.

Throws:

XBRLException

getItems

public FragmentList<Item> getItems(URI uri)
                            throws XBRLException

Parameters:

uri - The URI of the document to get the items from.

Returns:

a list of all of the root-level items in the data store.

Throws:

XBRLException

getRootFragmentForDocument

public <F extends Fragment> F getRootFragmentForDocument(String uri)
                                              throws XBRLException

Specified by:

getRootFragmentForDocument in interface Store

Type Parameters:

F - The fragment extension class

Parameters:

uri - The URI of the document to get the root fragment for.

Returns:

the root fragment of the document with the given URI or null if no root fragment is available for the given URI.

Throws:

XBRLException - if more than one root fragment is found in the data store.

See Also:

Store.getRootFragmentForDocument(String)

getRootFragments

public <F extends Fragment> FragmentList<F> getRootFragments()
                                                  throws XBRLException

Specified by:

getRootFragments in interface Store

Type Parameters:

F - The fragment extension class

Returns:

the list of root fragments of the documents in the store.

Throws:

XBRLException - if more than one root fragment is found in the data store.

See Also:

Store.getRootFragments()

getLanguage

public Language getLanguage(String encoding,
                            String code)
                     throws XBRLException

Specified by:

getLanguage in interface Store

Parameters:

encoding - The code identifying the language that the name of the language is expressed in.

code - The code that identifies the language being named.

Returns:

the Language fragment that specifies the name of the language for the given code, expressed in the language identified by the encoding or null or if there is no matching language name in the data store. The input parameters are converted to upper case before processing.

Throws:

XBRLException - if either parameter equals null.

See Also:

Store.getLanguage(String, String)

getLanguages

public FragmentList<Language> getLanguages(String code)
                                    throws XBRLException

Specified by:

getLanguages in interface Store

Parameters:

code - The language code to get the language fragments for. The code is converted to upper case before processing.

Returns:

the list of language fragments giving names for the language associated with the specified language code.

Throws:

XBRLException - if the language code is null.

See Also:

Store.getLanguages(String)

getStoredNetworks

public Networks getStoredNetworks()

Specified by:

getStoredNetworks in interface Store

Returns:

the Networks object incorporated into the data store, if there is one, and null otherwise This is used to centralise all networks creation into the one networks object, should that be desired. Otherwise ensure that this is set to null.

See Also:

Store.getStoredNetworks()

hasStoredNetworks

public boolean hasStoredNetworks()

Specified by:

hasStoredNetworks in interface Store

Returns:

true iff the store incorporates a central networks object.

See Also:

Store.hasStoredNetworks()

setStoredNetworks

public void setStoredNetworks(Networks networks)

Specified by:

setStoredNetworks in interface Store

Parameters:

networks - The networks to incorporate into the data store object.

See Also:

Store.setStoredNetworks(org.xbrlapi.networks.Networks)