<change id="Source.Context.Lookup">

          <api name="ParsingAPI"/>

          <summary>Source provides access to Lookup</summary>

          <version major="9" minor="2"/>

          <date day="18" month="6" year="2014"/>

          <author login="sdedic"/>

          <compatibility source="compatible" binary="compatible" addition="yes"/>

          <description>

              <p>

                  In the presence of multiple scopes or users, the parsing system needs

                  to access the proper context even though the work is done by different 

                  threads. It also has to propagate the proper context back to the user

                  tasks.

              </p>

              <p>

                  Source can now be created with a Lookup that provides such proper context,

                  or automatically uses Lookup.getDefault if no explicit Lookup is given.

              </p>

          </description>

          <issue number="247161"/>

      </change>

    <change id="Parsing.Netbeans.Cleanup">

          <api name="ParsingAPI"/>

          <summary>Parsing API cleaned up from IDE dependencies</summary>

          <version major="9" minor="1"/>

          <date day="6" month="5" year="2014"/>

          <author login="sdedic"/>

          <compatibility source="compatible" binary="compatible" semantic="incompatible" modification="yes"/>

          <description>

              <p>

                The Parsing API dependended on Windows System, Editor Registry, Data Systems and other IDE artifacts. All those

                dependencies were externalized as 'private SPIs' in the package <code>org.netbeans.modules.parsing.impspi</code>.

                The implementation that uses the other NetBeans IDE APIs resides in module <code>parsing.nb</code>.

                No API change was done, but the execution now relies on a proper binding to be present in the running application

                or a testsuite.

              </p>

              <p>

                Basic testing environment was provided in unit tests, which implements basic of the externalized functions. However

                if a test need to check reparsing after document change, or data object change. Full implementation may be needed -

                the implementor can use a <code>test-dependency</code> to the <code>org.netbeans.modules.parsing.nb</code> module.

              </p>

          </description>

      </change>

      <change id="Separate.Parsing.Indexing">

          <api name="ParsingAPI"/>

          <summary>Indexing API separated to its own module</summary>

          <version major="9" minor="0"/>

          <date day="20" month="4" year="2014"/>

          <author login="sdedic"/>

          <compatibility source="incompatible" binary="compatible" semantic="compatible" modification="yes"/>

          <description>

              <p>

                  Historically the module offered both APIs for Parsing (invoking parser, implementing parser) and

                  Indexing (refresh index, index SPIs). Those APIs are typically used by unrelated pieces of code,

                  possibly with the exception of "refresh" actions.

              </p>

              <p>

                  The indexing now resides separately in its <code>parsing.indexing</code> module. Binary compatibility

                  is kept by using module-auto-deps.xml.

              </p>

          </description>

      </change>

<?xml version="1.0" encoding="UTF-8"?>

<!--

DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

Copyright 1997-2010 Oracle and/or its affiliates. All rights reserved.

Oracle and Java are registered trademarks of Oracle and/or its affiliates.

Other names may be trademarks of their respective owners.

The contents of this file are subject to the terms of either the GNU

General Public License Version 2 only ("GPL") or the Common

Development and Distribution License("CDDL") (collectively, the

"License"). You may not use this file except in compliance with the

License. You can obtain a copy of the License at

http://www.netbeans.org/cddl-gplv2.html

or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

specific language governing permissions and limitations under the

License.  When distributing the software, include this License Header

Notice in each file and include the License file at

nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

particular file as subject to the "Classpath" exception as provided

by Oracle in the GPL Version 2 section of the License file that

accompanied this code. If applicable, add the following below the

License Header, with the fields enclosed by brackets [] replaced by

your own identifying information:

"Portions Copyrighted [year] [name of copyright owner]"

Contributor(s):

The Original Software is NetBeans. The Initial Developer of the Original

Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun

Microsystems, Inc. All Rights Reserved.

If you wish your version of this file to be governed by only the CDDL

or only the GPL Version 2, indicate your decision by adding

"[Contributor] elects to include this software in this distribution

under the [CDDL or GPL Version 2] license." If you do not indicate a

single choice of license, a recipient has the option to distribute

your version of this file under either the CDDL, the GPL Version 2 or

to extend the choice of license to its licensees as provided above.

However, if you add GPL Version 2 code and therefore, elected the GPL

Version 2 license, then the option applies only if the new code is

made subject to such option by the copyright holder.

-->

<!DOCTYPE transformations PUBLIC "-//NetBeans//DTD Module Automatic Dependencies 1.0//EN" "http://www.netbeans.org/dtds/module-auto-deps-1_0.dtd">

<transformations version="1.0">

    <transformationgroup>

        <description>Separation of Parsing and Indexing APIs</description>

        <transformation>

            <trigger-dependency type="older">

                <module-dependency codenamebase="org.netbeans.modules.parsing.api" major="1" spec="9.0"/>

            </trigger-dependency>

            <implies>

                <result>

                    <module-dependency codenamebase="org.netbeans.modules.parsing.indexing" spec="9.0"/>

                </result>

            </implies>

        </transformation>

    </transformationgroup>

</transformations>

                        <code-name-base>org.netbeans.modules.projectapi.nb</code-name-base>

                    </test-dependency>

                    <test-dependency>

                    <!--                    <test-dependency>

                        <code-name-base>org.netbeans.modules.parsing.indexing</code-name-base>

                        <compile-dependency/>

                        <test/>

                    </test-dependency>-->

                    <test-dependency>

                        <code-name-base>org.netbeans.api.progress.nb</code-name-base>

                    </test-dependency>

 * <p>

 * The Source can be created with a {@link Lookup} instance. This Lookup should be used

 * by parsing system, or callback tasks to locate services, that depend on the execution

 * context (ie which user is executing the task). Check the specific service's documentation 

 * on details of the service's context dependencies.

 * @since 9.2 implements Lookup.Provider

     * Gets a <code>Source</code> instance for a file. The <code>FileObject</code>

     * passed to this method has to be a valid data file. There is no <code>Source</code>

     * representation for a folder.

     * <p/>

     * This form allows to specify Lookup that provides access to context-dependent

     * services for the parsing system and the user tasks called from parsing API.

     * 

     * @param fileObject The file to get <code>Source</code> for.

     * @param lkp The Lookup that provides the context

     * @return The <code>Source</code> for the given file or <code>null</code>

     *   if the file doesn't exist.

     * @since 9.2

     */

    public static Source create (

        FileObject          fileObject, Lookup lkp

    ) {

        Parameters.notNull("fileObject", fileObject); //NOI18N

        Parameters.notNull("lkp", lkp); //NOI18N

        if (!fileObject.isValid() || !fileObject.isData()) {

            return null;

        }

        return _get(fileObject.getMIMEType(), fileObject, lkp);

    }

    /**

        return create(document, Lookup.getDefault());

    }

    /**

     * Gets a <code>Source</cide> instance for a <code>Document</code>. For details, please 

     * see {@link #create(javax.swing.text.Document)}; this form allows to specify

     * a Lookup that provides access to user or context-dependent services.

     * 

     * @param document the document to get <code>Source</code> for

     * @param lkp the context for the source

     * @return the Source instance

     * @see #create(javax.swing.text.Document) 

     * @since 9.2

     */

    public static Source create (

        Document            document, Lookup lkp

    ) {

    private final Lookup context;

    /**

     * SourceEnvironment callback

     */

    private final SourceControl ctrl = new SourceControl(this);

    /**

     * Binding of source to its environment

     */

    private final SourceEnvironment sourceEnv;

    /**

     * Demultiplexes events from all parsers to SourceEnvironment.

     */

    private final ParserEventForward peFwd;

    @SuppressWarnings("LeakingThisInConstructor")

        this.context =      context;

        this.peFwd = new ParserEventForward();

        this.sourceEnv = Utilities.createEnvironment(this, ctrl);

            assert source.context == context;

    private void setFlags(final Set<SourceFlags> flags) {

        // synchronized because of eventId

        synchronized (flags) {

            this.flags.addAll(flags);

            eventId++;

        }

    }

    private void setSourceModification (boolean sourceChanged, int startOffset, int endOffset) {

        ASourceModificationEvent oldSourceModificationEvent;

        ASourceModificationEvent newSourceModificationEvent;

        do {

            oldSourceModificationEvent = sourceModificationEvent.get();

            boolean mergedChange = sourceChanged | (oldSourceModificationEvent == null ? false : oldSourceModificationEvent.sourceChanged());

            newSourceModificationEvent = new ASourceModificationEvent (this, mergedChange, startOffset, endOffset);                

        } while (!sourceModificationEvent.compareAndSet(oldSourceModificationEvent, newSourceModificationEvent));

    }

    private void mimeTypeMayChanged() {

        final FileObject file = getFileObject();

        if (file != null && !Objects.equals(getMimeType(), file.getMIMEType())) {

            synchronized (Source.class) {

                instances.remove(file);

            }

        }

    }

    private SourceCache getCache() {

        synchronized (TaskProcessor.INTERNAL_LOCK) {

            if (cache == null)

                cache = new SourceCache (this, null);

            return cache;

        }

    }

    @SuppressWarnings("AccessingNonPublicFieldOfAnotherObject") // accessing internals is accessor's job

        public void revalidate(Source source, int delay) {

            source.ctrl.revalidate(delay);

        }

        @Override

        @Override

        public void attachScheduler(Source src, SchedulerControl sched, boolean attach) {

            src.sourceEnv.attachScheduler(sched, attach);

        }

        @Override

        @NonNull

        public ParserEventForward getParserEventForward(@NonNull final Source source) {

            return source.peFwd;

        }

    /**

     * Returns a Lookup providing a context for the source.

     * In the presence of multiple scopes or users in the system, this Lookup may

     * provide access to necessary context-dependent services or scope-dependent data.

     * <p/>

     * A Source may be created with a Lookup, or it will use the default Lookup as a context

     * @return Lookup.

     * @since 9.2

     */

    public Lookup getLookup() {

        return context;

    }

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2014 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2014 Sun Microsystems, Inc.

 */

package org.netbeans.modules.parsing.impl;

/**

 * This interface is a pseudoAPI between Parsing and Indexing support.

 * The Parsing support needs to communicate with Indexing and coordinate task planning.

 * Indexing API can use impl dependency on Parsing API to call the necessary services,

 * but Parsing API must use a bridge implemented by Indexing to call back.

 * <p/>

 * This pseudoAPI can be changed at any time without any warning! 

 * 

 * @author sdedic

 * @since 9.2

 */

public interface IndexerBridge {

    /**

     * @return True if the indexer is in any other state than idle.

     */

    public boolean isIndexing();

    /**

     * 

     * @return true, if the calling thread executes in the indexer's protected mode.

     */

    public boolean ownsProtectedMode();

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2014 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2014 Sun Microsystems, Inc.

 */

package org.netbeans.modules.parsing.implspi;

import java.util.Collection;

import java.util.concurrent.Callable;

import org.netbeans.api.annotations.common.CheckForNull;

import org.netbeans.api.annotations.common.NonNull;

import org.netbeans.api.annotations.common.NullAllowed;

import org.netbeans.modules.parsing.api.Source;

import org.netbeans.modules.parsing.spi.Parser;

import org.netbeans.modules.parsing.spi.Scheduler;

import org.openide.util.Lookup;

/**

 * Factory for {@link SourceEnvironment} instances. The Factory method is given

 * a {@link Source.EnvControl} object so the created SourceEnvironment may

 * manipulate the Source state using privileged APIs.

 * <p/>

 * An instance of this Provider must be registered in the default Lookup. The first

 * instance found will be used.

 * @since 9.2

 */

public interface EnvironmentFactory {

    /**

     * Provides access to context-dependent Lookup, to multi-user environment

     * @return context-depedent Lookup

     */

    public Lookup   getContextLookup();

    /**

     * Parovides a class of a predefined Scheduler.

     * The predefined Schedulers are available as final field values.

     *

     * @param schedulerName

     * @return

     */

    @CheckForNull

    public Class<? extends Scheduler> findStandardScheduler(@NonNull String schedulerName);

    /**

     * Creates parser for the mime type

     * @param mimeType

     * @return 

     */

    public Parser   findMimeParser(Lookup context, String mimeType);

    public Collection<? extends Scheduler> getSchedulers(Lookup context);

    /**

     * Creates an environment for the specified Source.

     * The passed control object may be {@code null}, which means the source cannot

     * be controlled by environment and listening may not be necessary.

     *

     * @param src the Source instance

     * @param control the control object; if null, the source cannot be controlled.

     * @return the SourceEnvironment, must not be null.

     */

    @NonNull

    public SourceEnvironment createEnvironment(@NonNull Source src, @NullAllowed SourceControl control);

    /**

     * Runs a priority I/O operation. The environment may lock out or suspend 

     * some (background) activities during the priority I/O operation.

     * 

     * @param <T> type of result

     * @param r the code to execute

     * @return computed result

     * @throws Exception propagated from the executed code

     */

    public abstract <T> T runPriorityIO (final Callable<T> r) throws Exception;

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2014 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2014 Sun Microsystems, Inc.

*/

package org.netbeans.modules.parsing.implspi;

import java.io.DataOutputStream;

import java.io.IOException;

/**

 * Semi-private SPI for self-profiling of the parsing system.

 *

 * @author sdedic

 * @since 9.2

 */

public abstract class ProfilerSupport {

    /**

     * Starts the profiling. The support will collect data until {@link #cancel} or {@link #stopAndSnapshot}

     * is called.

     */

    public abstract void start();

    /**

     * Cancels the profiling and discards data already collected.

     */

    public abstract void cancel();

    /**

     * Stops the profiling and flushes the data.

     * 

     * @param dos output stream to store the collected data.

     */

    public abstract void stopAndSnapshot(DataOutputStream dos) throws IOException;

    public interface Factory {

        public ProfilerSupport  create(String id);

    }

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2014 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2014 Sun Microsystems, Inc.

 */

package org.netbeans.modules.parsing.implspi;

import org.netbeans.modules.parsing.api.Source;

import org.netbeans.modules.parsing.spi.Scheduler;

/**

 * Allows the environment implementation to reschedule tasks for a

 * source. The instance is passed to {@link SourceEnvironment#attachScheduler}.

 * @author sdedic

 * @since 9.2

 */

public interface SchedulerControl {

    /**

     * Provides access to the controlled Scheduler

     * @return the scheduler instance

     */

    public Scheduler getScheduler();

    /**

     * Notifies about Source change. Should be called when the scheduler

     * should reschedule source's tasks or when the Source itself changes, i.e.

     * file is moved/renamed etc.

     * 

     * @param newSource the current Source for the Scheduler

     */

    public void sourceChanged(Source newSource);

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2014 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2014 Sun Microsystems, Inc.

 */

package org.netbeans.modules.parsing.implspi;

import java.util.EnumSet;

import java.util.Set;

import org.netbeans.api.annotations.common.NonNull;

import org.netbeans.modules.parsing.api.Source;

import org.netbeans.modules.parsing.impl.SourceAccessor;

import org.netbeans.modules.parsing.impl.SourceFlags;

import org.netbeans.modules.parsing.impl.TaskProcessor;

import org.openide.util.Parameters;

import org.openide.util.RequestProcessor;

/**

 * Allows to control Source state within the Parsing subsystem based on

 * external events.

 * The {@link SourceEnvironment} gets this instance to forward interesting

 * events to the parser. It is possible to invalidate the source, region of source.

 * @author sdedic

 * @since 9.2

 */

public final class SourceControl {

    private static final RequestProcessor RP = new RequestProcessor (

        "parsing-event-collector",         //NOI18N

        1,

        false,

        false);

    private final RequestProcessor.Task resetTask;

    private final Source source;

    /**

     * Creates a new control object for the source.

     * 

     * @param source the source which is controlled

     */

    public SourceControl(@NonNull final Source source) {

        Parameters.notNull("source", source);   //NOI18N

        this.source = source;

        this.resetTask = RP.create(new Runnable() {

            @Override

            public void run() {

                if (SourceAccessor.getINSTANCE().getEnv(source).isReparseBlocked()) {

                    return;

                }

                TaskProcessor.resetStateImpl(source);

            }

        });

    }

    /**

     * Provides reference to the Source. The reference is provided for convenience

     * to help proper garbage collection of the Source object. If the client keeps

     * a Source instance, it should use WeakReference to store it.

     * @return Source instance or {@code null}

     */

    @NonNull

    public Source getSource() {

        return source;

    }

    /**

     * Informs that the source was changed in an unspecified way, and possibly

     * its mime was changed.

     * The source will be reparsed and if {@code mimeChanged} is true, the MIME

     * type will be re-read and the appropriate parser will be used for parsing.

     * <p/>

     * The {@code mimeChanged} flag is used for optimization; set it aggressively,

     * so proper parser is looked up.

     * 

     * @param mimeChanged true, if mime type might have changed.

     */

    public void sourceChanged(final boolean mimeChanged) {

        final SourceAccessor sa = SourceAccessor.getINSTANCE();

        final Set<SourceFlags> flags = EnumSet.of(

            SourceFlags.CHANGE_EXPECTED,

            SourceFlags.INVALID,

            SourceFlags.RESCHEDULE_FINISHED_TASKS);

        if (mimeChanged) {

            sa.mimeTypeMayChanged(source);

        }

        sa.setSourceModification(source, true, -1, -1);

        sa.setFlags(source, flags);

        TaskProcessor.resetState(source, true, true);

    }

    /**

     * Informs that part of the source was edited. The parser implementation

     * may reparse just a portion of the text or a whole (depends on the 

     * implementation). Setting {@code startOffset} or {@code endOffset}

     * to -1 will execute an equivalent of {@code sourceChanged(false)}.

     * 

     * @param startOffset start of the change

     * @param endOffset end of the change

     */

    public void regionChanged(int startOffset, int endOffset) {

        final SourceAccessor sa = SourceAccessor.getINSTANCE();

        final Set<SourceFlags> flags = EnumSet.of(

            SourceFlags.CHANGE_EXPECTED,

            SourceFlags.INVALID,

            SourceFlags.RESCHEDULE_FINISHED_TASKS);

        sa.setSourceModification(source, true, startOffset, endOffset);

        sa.setFlags(source, flags);

        TaskProcessor.resetState(source, true, true);

    }

    /**

     * Informs about a non-text change in the Source, such as caret movement

     * or focus. Does not invalidate the parsing result, but may re-execute certain

     * tasks.

     */

    public void stateChanged() {

        final SourceAccessor sa = SourceAccessor.getINSTANCE();

        final Set<SourceFlags> flags = EnumSet.of(SourceFlags.CHANGE_EXPECTED);

        sa.setSourceModification(source, false, -1, -1);

        sa.setFlags(source, flags);

        TaskProcessor.resetState(source, false, true);

    }

    /**

     * Marks the source for reparsing after the specified delay.

     *

     * @param delay time in milliseconds.

     */

    public void revalidate(int delay) {

        resetTask.schedule(delay);

    }

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2014 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2014 Sun Microsystems, Inc.

 */

package org.netbeans.modules.parsing.implspi;

import java.io.IOException;

import javax.swing.event.ChangeListener;

import javax.swing.text.Document;

import org.netbeans.api.annotations.common.CheckForNull;

import org.netbeans.api.annotations.common.NonNull;

import org.netbeans.modules.parsing.api.Source;

import org.netbeans.modules.parsing.impl.ParserEventForward;

import org.netbeans.modules.parsing.impl.SourceAccessor;

import org.netbeans.modules.parsing.impl.event.FileChangeSupport;

import org.netbeans.modules.parsing.impl.event.ParserChangeSupport;

import org.openide.filesystems.FileChangeListener;

import org.openide.filesystems.FileObject;

import org.openide.filesystems.FileUtil;

import org.openide.util.Parameters;

/**

 * Connects the Source instance to its environment.It is not implemented by

 * Parsing API as it may introduce extra dependencies on file or object access

 * libraries (e.g. Data Systems API). In exchange, the Provider gets a control

 * interface, which can be used to signal source change events originating from

 * the storage/file/DataObject.

 * <p/>

 * Instance of the SourceEnvironment is referenced from the Source object. It is 

 * advised not to store Source reference, but rather extract the Source instance

 * from the {@link Source.EnvControl} to allow Source instances to be GCed. 

 * 

 * @author sdedic

 * @since 9.2

 */

public abstract class SourceEnvironment {

    private final SourceControl sourceControl;

    private FileChangeListener fileChangeListener;

    private ChangeListener parserListener;

    /**

     * Initialized a new SourceEnvironment.

     * @param sourceControl handle to control a Source object

     */

    protected SourceEnvironment(@NonNull final SourceControl sourceControl) {

        Parameters.notNull("sourceControl", sourceControl); //NOI18N

        this.sourceControl = sourceControl;

    }

    /**

     * Reads the Document based on the Source's properties

     *

     * @param f the FIleObject

     * @param forceOpen true, if the document should be opened even though

     * it does not exist yet

     * @return the document, or {@code null} if the document was not opened.

     */

    @CheckForNull

    public abstract Document readDocument(@NonNull FileObject f, boolean forceOpen) throws IOException;

    /**

     * Attaches a Scheduler to the source in this environment. The implementation

     * may need to listen on certain environment objects in order to schedule

     * tasks at appropriate time.

     * <p/>

     * 

     * @param s the scheduler to attach or detach

     * @param attach if false, the scheduler is just detached from the source.

     */

    public abstract void attachScheduler(@NonNull SchedulerControl s, boolean attach);

    /**

     * Notifies that the source was actually used, and the parser wants to be

     * notified on changes through {@link SourceControl}.

     * Until this method is called, the environment implementation need not to

     * listen or forward source affecting events to the parser API.

     */

    public abstract void activate();

    /**

     * Returns true, if reparse should NOT occur immediately when source is invalidated.

     * This is used when e.g. completion is active; postpones reparsing. The SourceEnvironment

     * is responsible for calling {@link SourceControl#revalidate()} when the condition changes.

     * 

     * @return true, if a reparse should not be scheduled.

     */

    public abstract boolean isReparseBlocked();

    /**

     * Returns the {@link SourceControl}.

     * @return the {@link SourceControl}

     */

    protected final SourceControl getSourceControl() {

        return this.sourceControl;

    }

    /**

     * Starts listening on file changes.

     * Should be called from {@link SourceEnvironment#activate}

     */

    protected final void listenOnFileChanges() {

        final FileObject fo = sourceControl.getSource().getFileObject();

        if (fo != null) {

            fileChangeListener = new FileChangeSupport(sourceControl);

            fo.addFileChangeListener(FileUtil.weakFileChangeListener(this.fileChangeListener,fo));

        }

    }

    /**

     * Starts listening on {@link Source} parsers.

     * Should be called from {@link SourceEnvironment#activate}

     */

    protected final void listenOnParser() {

        final ParserEventForward peFwd = SourceAccessor.getINSTANCE().getParserEventForward(

            sourceControl.getSource());

        parserListener = new ParserChangeSupport(sourceControl);

        peFwd.addChangeListener(parserListener);

    }

    /**

     * Returns a {@link SourceEnvironment} for given {@link Source}.

     * @param source the {@link Source} to return {@link SourceEnvironment} for