loaderimpl.java

xbrlapi的源码

     * 
     * @throws XBRLException
     */
    public void augmentChildren() throws XBRLException {
        incrementChildren();
    }

    /**
     * Add a new child tracking vector to the childrenStack to use for the new
     * fragment that is being built by the loader. Initialise it with a single
     * node containing the value of zero to signify that the root element of the
     * new fragment has not had any child elements found for it yet.
     * 
     * @throws XBRLException
     */
    public void prepareToTrackChildrenForNewFragment() throws XBRLException {
        Vector<Long> v = new Vector<Long>();
        v.add(new Long(0));
        childrenStack.add(v);
    }

    /**
     * The children vector contains an item for each element that has been started
     * and that has not yet been ended by the SAX content handler.
     * 
     * @return The vector of children or null if none exist (implying no parent
     *         fragments).
     * @throws XBRLException
     */
    public Vector<Long> getChildrenVector() throws XBRLException {
        if (childrenStack.isEmpty())
            return null;
        Vector<Long> children = childrenStack.peek();
        return children;
    }

    /**
     * Increment the children tracker to show that a new element has been found.
     * TODO make sure that the Loader incrementChildren method has its
     * properties initialised.
     * 
     * @throws XBRLException
     */
    public void incrementChildren() throws XBRLException {

        // Do nothing if the children stack is empty - we are at the root of a
        // document
        if (this.childrenStack.isEmpty()) {
            return;
        }

        // record a new child for the parent element
        long c = (getChildrenVector().lastElement()).longValue() + 1;
        getChildrenVector().setElementAt(new Long(c),
                getChildrenVector().size() - 1);
    }

    /**
     * Add a new node to the vector of children being tracked for the current
     * fragment. Initialise its value to zero to capture the fact that no
     * children have been found for the newly processed element - as yet.
     * 
     * @throws XBRLException
     */
    public void extendChildren() throws XBRLException {
        getChildrenVector().add(new Long(0));
    }

    /**
     * Remove the last element in the children vector. This is done when we are
     * finished with processing an element or fragment.
     * 
     * @throws XBRLException
     */
    private void reduceChildren() throws XBRLException {
        if (getChildrenVector().size() > 0)
            getChildrenVector().removeElementAt(getChildrenVector().size() - 1);
        else
            throw new XBRLException(
                    "The element being completed has a corrupted child count.");
    }

    /**
     * Check for completion of a fragment by comparing the depth parameter with
     * the depth recorded for the root element of the fragment currently being
     * built. 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.
     * 
     * @param depth
     *            The depth (in the document being parsed) of the element that
     *            has just been completed.
     * @throws XBRLException
     */
    public void updateState(long depth) throws XBRLException {
        if (depth == (depths.peek()).longValue()) {
            this.removeFragment();
        } else {
            this.reduceChildren();
        }
    }

    /**
     * Get the fragment that is currently being built by the DTS loader
     * 
     * @return the fragment being built currently by the DTS loader or null if
     *         no fragments are being built by the loader.
     * @throws XBRLException
     */
    public Fragment getFragment() throws XBRLException {
        if (fragments.isEmpty())
            return null;
        return fragments.peek();
    }

    /**
     * Push a new fragment onto the stack of fragments that are being built by
     * the loader. Record the depth of the fragment root element in the document
     * that is being parsed so that it is possible to decide when that fragment
     * has finished being parsed.
     * 
     * @param fragment
     *            The fragment to be added to the stack of fragments being built
     *            by the loader.
     * @throws XBRLException
     *             if the fragment cannot be added to the store.
     */
    public void addFragment(Fragment fragment, long depth, ElementState state)
            throws XBRLException {

        // Get the XPointer expressions that identify the root of this fragment
        // TODO Should the following xpointer code be contingent on children != null?
        Vector<String> pointers = state.getElementSchemePointers();
        for (String pointer : pointers) {
            fragment.appendElementSchemeXPointer(pointer);
        }

        // Set the metadata for the fragment to enable document reconstruction
        Vector<Long> children = getChildrenVector();
        if (children != null) {
            Fragment parent = getFragment();
            if (parent == null)
                throw new XBRLException("The parent fragment is missing.");
            String parentIndex = parent.getFragmentIndex();
            if (parentIndex == null)
                throw new XBRLException("The parent index is null.");
            fragment.setParentIndex(parentIndex);
            fragment.setSequenceToParentElement(children);
            fragment.setPrecedingSiblings(children);

        } else { // We have a document root fragment.
            fragment.setParentIndex("none");
        }
        fragment.setURL(getDocumentURL());

        // Push the fragment onto the stack of fragments
        fragments.add(fragment);

        // Push the depth of the fragment root onto the stack of fragment depths
        depths.add(new Long(depth));

        // Push a new child count vector onto the stack of child count vectors
        prepareToTrackChildrenForNewFragment();

        this.newFragmentAdded = true;

    }

    /**
     * Tests if the element that has just been found has triggered the addition
     * of a fragment. Sets the flag to false once it has been tested, ready for
     * the next element to be parsed.
     * 
     * @return true iff the element that has just been found has triggered the
     *         addition of a fragment.
     * @throws XBRLException.
     */
    public boolean addedAFragment() {
        boolean temp = this.newFragmentAdded;
        this.newFragmentAdded = false;
        return (temp);
    }

    /**
     * Remove a fragment from the stack of fragments that are being built by the
     * loader. TODO Make this method less public.
     * 
     * @throws XBRLException
     *             if their are no fragments being built.
     */
    public Fragment removeFragment() throws XBRLException {
        try {
            depths.pop();
            childrenStack.pop();
            Fragment f = fragments.pop();
            getStore().storeFragment(f);
            return f;
        } catch (EmptyStackException e) {
            throw new XBRLException(
                    "There are no fragments being built.  The stack of fragments is empty.",
                    e);
        }
    }

    /**
     * @see org.xbrlapi.loader.Loader#discover(List)
     */
    public void discover(List<URL> startingURLs) throws XBRLException {

        for (int i = 0; i < startingURLs.size(); i++) {
            Object object = startingURLs.get(i);
            // TODO Eliminate this check of URL object type now that generics
            // are being used.
            if (object instanceof java.net.URL)
                stashURL((URL) object);
            else
                throw new XBRLException(
                        "Loader discovery must be passed a list of java.net.URL objects.");
        }

        discover();
    }

    /**
     * @see org.xbrlapi.loader.Loader#discover(URL)
     */
    public void discover(URL url) throws XBRLException {
        stashURL(url);
        discover();
    }

    /**
     * @see org.xbrlapi.loader.Loader#discover(String)
     */
    public void discover(String url) throws XBRLException {
        try {
            discover(new URL(url));
        } catch (MalformedURLException e) {
            throw new XBRLException("The URL to discover, " + url + " is malformed.", e);
        }
    }

    /**
     * @see org.xbrlapi.loader.Loader#getDocumentsStillToAnalyse()
     */
    public List<String> getDocumentsStillToAnalyse() {
        List<String> documents = new LinkedList<String>();

        for (String document : documentQueue.keySet()) {
            if ((documentQueue.get(document)).equals(new Integer(0))) {
                documents.add(document);
            }
        }

        return documents;
    }

    /**
     * @see org.xbrlapi.loader.Loader#discover()
     */
    public void discover() throws XBRLException {

        if (isDiscovering()) return;
        setDiscovering(true);

        for (URL url: getStore().getDocumentsToDiscover()) {
            this.stashURL(url);
        }

        URL url = getNextDocumentToExplore();
        while (url != null) {
            if (!getStore().hasDocument(url.toString())) {
                setDocumentURL(url.toString());
                this.setNextFragmentId("1");
                double startTime = System.currentTimeMillis();
                int startIndex = this.fragmentId;
                parse(url);
                String time = (new Double(
                        (System.currentTimeMillis() - startTime)
                                / (fragmentId - startIndex))).toString();
                if (time.length() > 4) time = time.substring(0, 4);
                logger.info("Average time taken per fragment = " + time + " milliseconds");
                logger.info(this.fragmentId + " fragments in " + url);
            } else {
                logger.info(url + " is already in the data store.");
            }

            if (interruptRequested()) {
                cancelInterrupt();
                break;
            }

            url = getNextDocumentToExplore();
        }

        setDiscovering(false);

    }

    /**
     * @see org.xbrlapi.loader.Loader#discoverNext()
     */
    public void discoverNext() throws XBRLException {

        Store store = this.getStore();
        
        if (isDiscovering()) return;
        setDiscovering(true);

        URL url = getNextDocumentToExplore();
        while (store.hasDocument(url.toString()) && (url != null)) {
            url = getNextDocumentToExplore();
        }

        if (url != null) {
            logger.info("Up to fragment " + this.fragmentId + ". Now parsing " + url);
            setDocumentURL(url.toString());
            this.setNextFragmentId("1");
            parse(url);
        }

        setDiscovering(false);

    }

    /**
     * Perform a discovery starting with an XML document that is represented as
     * a string.
     * 
     * @param url
     *            The URL to be used for the document that is supplied as a
     *            string. This URL MUST be an absolute URL.
     * @param xml
     *            The string representation of the XML document to be parsed.
     * @throws XBRLException
     *             if the discovery process fails or if the supplied URL is not
     *             absolute or is not a valid URI syntax or the loader does not
     *             have a cache.
     */
    public void discover(URL url, String xml) throws XBRLException {

        logger.debug("Discovering a resource supplied as a string and with URL: " + url);

        try {
            if (!url.toURI().isAbsolute())
                throw new XBRLException("The URL " + url + " must be absolute.");
        } catch (URISyntaxException e) {
            throw new XBRLException("The URL " + url
                    + " must be a valid URI syntax.", e);
        }

        // Copy the XML to the local cache even if it is there already (possibly over-writing existing documents)
        this.getCache().copyToCache(url, xml);

        try {
            this.stashURL(new URL(