<friend>org.netbeans.modules.csl.api</friend>

                <package>org.netbeans.spi.jumpto.file</package>

/*

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

 *

 * Copyright 2010 Sun Microsystems, Inc. All rights reserved.

 *

 * 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.  Sun designates this

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

 * by Sun 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 2010 Sun Microsystems, Inc.

 */

package org.netbeans.spi.jumpto.file;

import java.util.List;

import org.netbeans.api.project.FileOwnerQuery;

import org.netbeans.api.project.Project;

import org.netbeans.api.project.SourceGroup;

import org.netbeans.modules.jumpto.file.FileDescription;

import org.netbeans.modules.jumpto.file.FileProviderAccessor;

import org.netbeans.spi.jumpto.type.SearchType;

import org.openide.filesystems.FileObject;

import org.openide.filesystems.FileUtil;

import org.openide.util.Lookup;

import org.openide.util.Parameters;

/**

 * A FileProvider participates in the Goto File dialog by providing matched files

 * for given {@link SourceGroup}.

 * The FileProviders are registered in global {@link Lookup}

 *

 * @since 1.15

 * @author Tomas Zezula

 */

public interface FileProvider {

    /**

     * Compute a list of files that match the given search text for the given

     * search type. This might be a slow operation, and the infrastructure may end

     * up calling {@link #cancel} on the file provider during the operation, in which

     * case the method can return incomplete results.

     * <p>

     * Note that a useful performance optimization is for the FileProvider to cache

     * a few of its most recent search results, and if the next search (e.g. more user

     * keystrokes) is a simple narrowing of the search, just filter the previous search

     * result. The same {@link FileProvider} instance is used during the GoTo File session and

     * it's freed when the GoTo File dialog is closed.

     *

     * @param context search context containg search text, type, project and {@link SourceGroup} root

     * @param result  filled with files and optional message

     * @return returns true if the root was handled by this FileProvider. When false

     * next provider is used.

     */

    boolean computeFiles(Context context, Result result);

    /**

     * Cancel the current operation, if possible. This might be called if the user

     * has typed something (including the backspace key) which makes the current

     * search obsolete and a new one should be initiated.

     */

    void cancel();

    /**

     * Represents search context.

     * Contains search type (such as prefix, regexp), search text,

     * {@link SourceGroup} root and project where to search.

     *

     */

    public static final class Context {

        //<editor-fold defaultstate="collapsed" desc="Private data">

        private final String text;

        private final SearchType type;

        private final Project currentProject;

        private FileObject sourceGroupRoot;

        private Project project;

        //</editor-fold>

        /**

         * Returns project owning the {@link SourceGroup} root

         * @return project to search in.

         */

        public Project getProject() {

            if (project == null) {

                project = FileOwnerQuery.getOwner(this.sourceGroupRoot);

            }

            return project;

        }

        /**

         * Returns the {@link SourceGroup} root to search files in.

         * @return root to search in.

         */

        public FileObject getRoot() { return sourceGroupRoot;}

        /**

          * Return the text used for search.

          *

          * @return The text used for the search; e.g. when getSearchType() == SearchType.PREFIX,

          *   text is the prefix that all returned types should start with.

          */

        public String getText() { return text; }

        /**

         * Return the type of search.

         *

         * @return Type of search performed, such as prefix, regexp or camel case.

         */

        public SearchType getSearchType() { return type; }

        //<editor-fold defaultstate="collapsed" desc="Private methods">

        private Context(String text, SearchType type, Project currentProject) {

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

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

            this.text = text;

            this.type = type;

            this.currentProject = currentProject;

        }

        private Project getCurrentProject() {

            return currentProject;

        }

        static {

            FileProviderAccessor.setInstance(new FileProviderAccessor() {

                @Override

                public Context createContext(String text, SearchType searchType, Project currentProject) {

                    return new Context(text, searchType,currentProject);

                }

                @Override

                public Result createResult(List<? super FileDescription> result, String[] message, Context ctx) {

                    return new Result(result, message, ctx);

                }

                @Override

                public int getRetry(Result result) {

                    return result.retry;

                }

                @Override

                public void setRoot(Context ctx, FileObject root) {

                    ctx.sourceGroupRoot = root;

                    ctx.project = null;

                }

            });

        }

        //</editor-fold>

    }

    /**

     * Represents a collection of files that match

     * the given search criteria. Moreover, it can contain message

     * for the user, such as an incomplete search result.

     *

     */

    public static final class Result {

        //<editor-fold defaultstate="collapsed" desc="Private data">

        private final List<? super FileDescription> result;

        private final String[] message;

        private final Context ctx;

        private int retry;

        //</editor-fold>

        /**

         * Optional message. It can inform the user about result, e.g.

         * that result can be incomplete etc.

         *

         * @param  msg  message

         */

        public void setMessage(String msg) {

            message[0] = msg;

        }

        /**

         * Adds a file into the result

         *

         * @param file The file to be added to result

         */

        public void addFile (final FileObject file) {

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

            final String path = FileUtil.getRelativePath(ctx.getRoot(), file);

            if (path != null) {

                final Project prj = ctx.getProject();

                final Project curPrj = ctx.getCurrentProject();

                result.add(new FileDescription(file, path, prj, curPrj.getProjectDirectory() == prj.getProjectDirectory()));

            }

        }

        /**

         * Notify caller that a provider should be called again because

         * of incomplete or inaccurate results.

         *

         * Method can be used when long running task blocks the provider

         * to complete the data.

         *

         */

        public void pendingResult() {

            retry = 2000;

        }

        //<editor-fold defaultstate="collapsed" desc="Private constructor">

        private Result(final List<? super FileDescription> result, final String[] message, final Context ctx) {

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

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

            Parameters.notNull("ctx", ctx);

            this.result = result;

            this.message = message;

            this.ctx = ctx;

        }

        //</editor-fold>

    }

}

/*

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

 *

 * Copyright 2010 Sun Microsystems, Inc. All rights reserved.

 *

 * 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.  Sun designates this

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

 * by Sun 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 2010 Sun Microsystems, Inc.

 */

package org.netbeans.spi.jumpto.file;

/**

 * Factory to create {@link FileProvider}s

 * @since 1.15

 * @author Tomas Zezula

 */

public interface FileProviderFactory {

    /**

     * Describe this provider with an internal name, used by logging.

     * @return An internal String uniquely identifying {@link FileProvider}, such as

     * "java"

     */

    String name();

    /**

     * Describe this provider for the user, used by logging.

     * @return A display name describing the {@link FileProvider}

     */

    String getDisplayName();

    /**

     * Reurns a {@link FileProvider} used in one session of Go To File action.

     * The returned provider is freed when the Go To File dialog is closed.

     * The {@link FileProvider} may cache some data to improve performance.

     * @return a new {@link FileProvider}

     */

    FileProvider createFileProvider();

}