fragment.java

xbrlapi的源码

package org.xbrlapi;

import java.util.HashMap;
import java.util.Vector;

import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.Node;
import org.xbrlapi.builder.Builder;
import org.xbrlapi.data.Store;
import org.xbrlapi.utilities.XBRLException;

/**
 * Defines the functionality exposed by any fragment.
 * @author Geoff Shuetrim ([e-mail])
 */

public interface Fragment {

	/**
	 * Set the data store that manages this fragment.
	 * @param store The data store.
	 * @throws XBRLException if the data store has already been set.
	 */
	public void setStore(Store store) throws XBRLException;
	
	/**
	 * Set the builder that constructs the fragment XML during parsing.
	 * @param builder The builder object used to construct the fragment XML.
	 * @throws XBRLException if the builder cannot be set or is null.
	 */
	public void setBuilder(Builder builder) throws XBRLException;	
	/**
	 * Get the data store that manages this fragment.
	 * @return the data store that manages this fragment or 
	 * null if the fragment has not been stored.
	 */
	public Store getStore();
	
	/**
	 * Get the fragment builder.  Note that the builder is null
	 * if the fragment has already been stored in a data store.
	 * TODO Should fragments hide the builder property?
	 * @return the fragment builder or null if one is not available.
	 */
	public Builder getBuilder();
    
	/**
     * Get the XML resource that is the fragment from the data store.
     * @return the DOM root element of the fragment or null if the resource
     * has not been initialised to a DOM root element.
     */
    public Element getResource() throws XBRLException;    
    
	/**
	 * Closes down the fragment builder and sets the data and metadata
	 * resources for the fragment.  This should only be used by Store implementations
	 * at the point where a newly built fragment is stored.
	 * @param rootElement The fragment data.
	 * @throws XBRLException If the builder cannot be shut down or if the 
	 * resource cannot be set or is null.
	 */
	public void setResource(Element rootElement) throws XBRLException;
    
    /**
     * Get the root element of the fragment data.
     * @return an XML DOM Element that is the root of the fragment data
     * or null if none exists.
     * @throws XBRLException
     */
    public Element getDataRootElement() throws XBRLException;

    /**
     * Get the XML DOM Document for the fragment data.
     * @return an XML DOM document for the fragment or null if none exists.
     * @throws XBRLException if the fragment has not yet been stored.
     */
    public Document getDocumentNode() throws XBRLException;
    
    /**
     * Get the root element of the fragment data.
     * @return an XML Element that is the root of the fragment data
     * or null if none exists.
     * @throws XBRLException
     */
    public Element getMetadataRootElement() throws XBRLException;

    /**
     * Tests if a fragment is new in the sense that it does not have a root data element.
     * This is only used by the SAX content builder to keep track of where the fragment
     * construction process is at.
     * TODO Decide if this can be eliminated by better decoupling the SAX content handler from the fragment implementation.
     * @return true if the fragment is new.
     * @throws XBRLException
     */
    public boolean isNewFragment() throws XBRLException;
    
    /**
     * Get the Fragment type.  The fragment type is immutable. 
     * No public method is available to set the fragment type.
     * @return The full class name of the fragment.
     */
    public String getType();

    /**
     * Get the fragment index from the fragment metadata.
     */
    public String getFragmentIndex();

    /**
     * Set the fragment index.  Note that no checks are
     * performed to ensure that the fragment index is
     * unique within the data store.
     * This method instantiates a fragment builder for fragments that do
     * not have a resource property.
     * @throws an XBRLException if the index is null or an empty string.
     */
    public void setFragmentIndex(String index) throws XBRLException;
    
    
    /**
     * Set a fragment metadata attribute.
     * @param name the name of the attribute
     * @param value the value to give to the metadata attribute
     * @throws XBRLException
     */
    public void setMetaAttribute(String name, String value) throws XBRLException;

    /**
     * Get a fragment metadata attribute.
     * @param name the name of the attribute.
     * @return The value of the metadata attribute or null if none exists.
     * @throws XBRLException
     */
    public String getMetaAttribute(String name) throws XBRLException;

	/**
	 * Removes a metadata attribute
	 * @param name The name of the attribute to remove
	 * @throws XBRLException
	 */
    public void removeMetaAttribute(String name) throws XBRLException;
    
    /**
     * Appends a child element to the root metadata element.
     * @param eName Name of the element to be added (no namespaces are used).
     * @param attributes A hashmap from attribute name keys to attribute values.
     * @throws XBRLException.
     */
    public void appendMetadataElement(String eName, HashMap<String,String> attributes) throws XBRLException;
    
    /**
     * removes a child element from the metadata root element by specifying the name of the child and
     * the value of the element's text content and/or the value of a named attribute.  All specified information
     * must match for the deletion to succeed.
     * @param eName Name of the element to be added (no namespaces are used).
     * @param attributes A hashmap from attribute name keys to attribute values.
     * @throws XBRLException If no deletion happens.
     */
    public void removeMetadataElement(String eName, HashMap<String,String> attributes) throws XBRLException;
    
    /**
     * Get the URL of the document containing this fragment.
     * @throws XBRLException
     */
    public String getURL() throws XBRLException;
    

	
    /**
     * Set the URL of the fragment's document.
     * @param url The string value of the document's absolute URL
     * @throws XBRLException.
     */
    public void setURL(String url) throws XBRLException;
    
    /**
     * Retrieves a list of all locators that target this fragment.
     * @return a list of all locators that target this fragment.  The list can be empty.
     * @throws XBRLException.
     */
    public FragmentList<Locator> getReferencingLocators() throws XBRLException;    
    
    /**
     * Get the index of the parent fragment or null if the fragment
     * does not have a parent fragment.
     * @return The index of the parent fragment or null if the 
     * fragment does not have a parent fragment.
     * @throws XBRLException if the parent fragment index is not available.
     */
    public String getParentIndex() throws XBRLException;
    
    /**
     * Get the sequence of steps through the parent fragment DOM to the parent element.
     * @return The sequence through the parent fragment data to the parent element of this fragment.
     * @throws XBRLException
     */
    public String[] getSequenceToParentElement() throws XBRLException;
    
    /**
     * Override the Object hashCode method to provide for equality comparisons
     * that are based on the fragment index.
     */
	public int hashCode();    
    
    /**
     * Get the sequence of steps through the parent fragment DOM to the parent element as a string.
     * @return The sequence through the parent fragment data to the parent element of this fragment.
     * @throws XBRLException
     */
    public String getSequenceToParentElementAsString() throws XBRLException;
    
    /**
     * Set the index of the parent fragment.
     * @param index The index of the parent fragment.
     * @throws XBRLException if the parent fragment index cannot be set.
     */
    public void setParentIndex(String index) throws XBRLException;    
    
    /**
     * Get the XPath to the element in the parent fragment that is the 
     * parent element of this fragment's root element.
     * @return The required xpath.
     * @throws XBRLException
     */
    public String getXPath() throws XBRLException;