store.java

xbrlapi的源码

package org.xbrlapi.data;

import java.io.File;
import java.io.OutputStream;
import java.net.URL;
import java.util.List;

import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.xbrlapi.Fragment;
import org.xbrlapi.FragmentList;
import org.xbrlapi.Language;
import org.xbrlapi.Networks;
import org.xbrlapi.data.resource.Matcher;
import org.xbrlapi.utilities.XBRLException;

/**
 * The data store interface, defining all methods that need to be 
 * implemented by a data store to support the XBRLAPI.
 * 
 * The store constructor needs to initialise the data structure.  
 * For example, the constructor would be required to
 * establish a database connection if an XML database is being
 * used to handle the underlying data.  Alternatively, the constructor
 * would establish an XML DOM document if an XML DOM were being used
 * as the underlying data structure.  Similarly, initialisation
 * steps would be taken if XML data binding to Java objects were
 * being used to handle the underlying data.
 *
 * @author Geoffrey Shuetrim ([e-mail])
 */

public interface Store {

	/**
	 * Close the data store.
	 * Throws XBRLException if the data store cannot be closed. 
	 */
	public void close() throws XBRLException;

	/**
	 * Store a fragment.  
	 * @param fragment The fragment to be added to the store.
	 * @throws XBRLException if the fragment cannot be added to the store.
	 */
    public void storeFragment(Fragment fragment) throws XBRLException;    

    /**
     * Test if a store contains a specific fragment, as identified by
     * its index.
     * @param index The index of the fragment to test for.
     * @return true iff the store contains a fragment with the specified 
     * fragment index.
     * @throws XBRLException If the test cannot be conducted.
     */
    public boolean hasFragment(String index) throws XBRLException;
    
    /**
     * Retrieves a fragment from a data store.
     * @param index The index of the fragment.
     * @return The fragment corresponding to the specified index.
     * @throws XBRLException if the fragment cannot be retrieved.
     */
    public Fragment getFragment(String index) throws XBRLException;

	/**
	 * Remove a fragment from the underlying data structure.  
	 * If a fragment with the same ID does not already exist in the 
	 * DTs then no action is required.
	 * @param index The index of the fragment to be removed from the DTS store.
	 * @throws XBRLException if the fragment cannot be removed from the store.
	 */
	public void removeFragment(String index) throws XBRLException;
	
	/**
	 * @param namespace The namespace to bind a prefix to for querying
	 * @param prefix The prefix to bind to the namespace for querying
	 * @throws XBRLException if either argument is null.
	 */
    public void setNamespaceBinding(String namespace, String prefix) throws XBRLException;
	

    
    /**
     * 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.
     * @param url The URL of the document to delete from the data store.
     * @throws XBRLException
     */
    public void deleteDocument(String url) throws XBRLException;
    

	 /**
	  * This deletion method ensures that all related documents
	  * are also deleted from the data store. 
	  * @param url The URL of the document to delete.
	  * @throws XBRLException
	  */
    public void deleteRelatedDocuments(String url) throws XBRLException;
    

    




	/**
	 * Run a query against the collection of all fragments in the store.
	 * @param query The XPath query to run against the set of fragments.
	 * @return a list of matching fragments or the empty list if no matching fragments
	 * exist.
	 * @throws XBRLException if the query cannot be executed.
	 */
	public <F extends Fragment> FragmentList<F> query(String query) throws XBRLException;	

    /**
     * Serialize the specified XML DOM to the specified destination.
     * @param what the root element of the DOM to be serialised.
     * @param 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.
     */
    public void serialize(Element what, OutputStream destination) throws XBRLException;

    /**
     * Serialize the specified XML DOM to the specified destination.
     * @param what the root element of the DOM to be serialised.
     * @param 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.
	 */
	public void serialize(Element what, File destination) throws XBRLException;
    
    /**
     * Serialize the specified XML DOM to the specified destination.
     * @param what the root element of the DOM to be serialised.
     * @param 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.
	 */
	public void serialize(Element what, String destination) throws XBRLException;
	
    /**
     * Serialize the specified XML DOM to System.out.
     * @param what the root element of the DOM to be serialised.
     * @throws XBRLException
     */
    public void serialize(Element what) throws XBRLException;
    
    /**
     * Serialize the specified fragment
     * @param fragment The fragment to be serialised.
     * @throws XBRLException
     */
    public void serialize(Fragment fragment) throws XBRLException;
    
    /**
     * Serialize the specified XML DOM node.
     * @param what the root element of the DOM to be serialised.
     * @return a string containing the serialized XML.
     * @throws XBRLException
     */
    public String serializeToString(Element what) throws XBRLException;    

    /**
     * Get a single document in the store as a DOM.
     * @param url The string representation of the URL of the 
     * document to be retrieved.
     * @return a DOM Document containing the XML representation of the
     * file at the specified URL.  Returns null if the store does not
     * contain a document with the given URL.
     * @throws XBRLException if the document cannot be constructed as a DOM.
     */
    public Element getDocumentAsDOM(String url) throws XBRLException;
    
	/**
	 * Serializes the individual documents in the data store, 
	 * saving them into a directory structure that is placed into
	 * the specified directory.  The directory structure that is 
	 * created mirrors the structure of the URLs of the documents. 
	 * Note that the URLs 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.
	 * @param 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.
	 */
	public void saveDocuments(File destination) throws XBRLException;
	
	/**
	 * Serializes those documents in the data store with a URL that
	 * begins with the specified URL 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.
	 * @param destination The folder in which the directory structure and
	 * the documents in the data store are to be saved.
	 * @param urlPrefix All documents in the data store with a URL that begins 
	 * with the string specified by urlPrefix 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.
	 */
	public void saveDocuments(File destination, String urlPrefix) throws XBRLException;
	
	/**