/*
 *                 Sun Public License Notice
 * 
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 * 
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2000 Sun
 * Microsystems, Inc. All Rights Reserved.
 */

package org.netbeans.modules.java.codegen;

import java.util.Collection;
import java.io.IOException;

import org.openide.cookies.SourceCookie;

import org.openide.src.SourceException;
import org.openide.src.Element;

import org.openide.text.CloneableEditorSupport;
import org.openide.text.PositionBounds;
import org.openide.text.PositionRef;

import org.netbeans.modules.java.bridge.Binding;
import org.netbeans.modules.java.bridge.BindingFactory;

/**
 * Definition of code generation package. The package exports those functions of
 * the BindingFactory and several management functions.
 *
 * @author  Svatopluk Dedic 
 * @version 0.1
 */
public interface DocumentBinding extends BindingFactory {
    /**
     * Finds and returns the CloneableEditorSupport. This method siply delegates
     * to the environment's findEditorSupport() method.
     * @return CloneableEditorSupport instance used for binding of the model.
     */
    public CloneableEditorSupport    getEditorSupport();
    
    /**
     * Causes the operation to run atomically on the document. The document
     * will be locked out for writing for the length of the operation.
     * @throw SourceException if the document cannot be loaded, locked or if some
     * of the Runnable's operation fails.
     */
    public void runAtomic(Runnable r) throws SourceException;
    
    /**
     * Causes the operation to run atomically on the document at the user-level. The document
     * will be locked out for writing for the length of the operation.
     * @throw SourceException if the document cannot be loaded, locked or if some
     * of the Runnable's operation fails.
     */
    public void enableAtomicAsUser(boolean enable);

    /**
     * Atomically updates bindings in the source, possibly inserting new ones. The 
     * hierarchy of Bindings is locked for the length of the operation. This will lock out
     * operations like get
     */
    public void updateBindings(Runnable r);
    
    /**
     * Enables or disables the code generator. If the calling code disables the generation,
     * it is responsible to reenable it again at the appropriate time. For example,
     * parsing updater should disable code generation before it starts to update the
     * source text model.
     */
    public void enableGenerator(boolean enableFlag);

    /**
     * Environment for the document generation package.
     */
    public static interface Env {
        /**
         * Finds CloneableEditorSupport for the code generator. The support is used
         * to load/access the document.
         */
        public CloneableEditorSupport findEditorSupport();

        /** Attempts to find "free" position in the source text, between (inclusive)
         * the given bounds. This is, actually, a test for a guarded block - it is
         * deferred to the user of the code generation suite.
         */
        public PositionRef  findFreePosition(PositionBounds bounds);

        /**
         * @throws IOException
         */
        public void         takeLock() throws IOException;
    }
}