<change id="UriSupport">

            <api name="api.search"/>

            <summary>Support for URI-based searching</summary>

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

            <date day="27" month="4" year="2012"/>

            <author login="jhavlin"/>

            <compatibility addition="yes"/>

            <description>

                <p>

                    Previous versions of this API supported searching based on

                    traversing of <code>FileObject</code>s only. In some cases

                    (e.g. remote filesystems), working with

                    <code>FileObjects</code> is too expensive and slow.

                    This API change make it possible to work with

                    <code>URI</code> objects as an alternative to

                    <code>FileObjects</code>.

                </p>

            </description>

            <class package="org.netbeans.api.search" name="SearchRoot"/>

            <class package="org.netbeans.api.search.provider" name="FileNameMatcher"/>

            <class package="org.netbeans.api.search.provider" name="SearchFilter"/>

            <class package="org.netbeans.api.search.provider" name="SearchInfo"/>

            <class package="org.netbeans.api.search.provider" name="SearchListener"/>

            <class package="org.netbeans.spi.search" name="SearchFilterDefinition"/>

            <class package="org.netbeans.spi.search" name="SearchInfoDefinition"/>

        </change>

import java.io.File;

import java.net.URI;

import java.util.logging.Level;

import java.util.logging.Logger;

import org.openide.filesystems.FileUtil;

    private URI rootUri;

    private static final Logger LOG = Logger.getLogger(

            SearchRoot.class.getName());

     * Create a new search root, defined by a folder and a set of filters.

     *

     * @param rootUri Root URI, cannot be null.

     * @param filters List of default filters, can be null.

     *

     * @since org.netbeans.api.search/1.4

     */

    public SearchRoot(@NonNull URI rootUri,

            @NullAllowed List<SearchFilter> filters) {

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

        this.rootUri = rootUri;

        this.filters = filters == null ? EMPTY_FILTER_LIST : filters;

    }

    /**

        if (rootFile == null) {

            try {

                FileObject fo = FileUtil.toFileObject(new File(rootUri));

                if (fo == null) {

                    rootFile = createFakeFile(rootUri, null);

                } else {

                    rootFile = fo;

                }

            } catch (Exception e) {

                rootFile = createFakeFile(rootUri, e);

            }

        }

    /**

     * Get URI of the search root.

     *

     * @since org.netbeans.api.search/1.4

     */

    public @NonNull URI getUri() {

        if (rootUri == null) {

            rootUri = rootFile.toURI();

        }

        return rootUri;

    }

    private FileObject createFakeFile(URI uri, Throwable t) {

        LOG.log(Level.INFO, "Invalid URI: " + uri, t);                  //NOI18N

        return FileUtil.createMemoryFileSystem().getRoot();

    }

import java.net.URI;

     * @param uri URI whose name or path should be matched.

     * @return True if the URI matches required criteria, false otherwise.

     *

     * @since org.netbeans.api.search/1.4

     */

    public abstract boolean pathMatches(URI uri);

    /**

        @Override

        public boolean pathMatches(URI uri) {

            return true;

        }

        public boolean pathMatches(File file) {

            String fileName = file.getName();

            return pathMatches(fileName);

        }

        @Override

        @Override

        public boolean pathMatches(URI uri) {

            String fileName = uri.getPath();

            return pathMatches(fileName);

        }

        @Override

        public boolean pathMatches(URI uri) {

            return pattern.matcher(uri.getPath()).find();

        }

        @Override

        public boolean pathMatches(URI uri) {

            String path = uri.getPath();

            int lastSeparator = path.lastIndexOf("\\");

            if (lastSeparator == -1) {

                lastSeparator = path.lastIndexOf("/");

            }

            if (lastSeparator == -1) {

                return false;

            } else {

                String name = path.substring(lastSeparator + 1, path.length());

                return pattern.matcher(name).matches();

            }

        }

import java.net.URI;

     * Answers a question whether a given URI should be searched. The URI must

     * stand for a plain file (not folder).

     *

     * @return

     * <code>true</code> if the given file should be searched;

     * <code>false</code> if not

     * @exception java.lang.IllegalArgumentException if the passed

     * <code>URI</code> is a folder

     *

     * @since org.netbeans.api.search/1.4

     */

    public abstract boolean searchFile(@NonNull URI fileUri);

    /**

    /**

     * Answers a questions whether a given URI should be traversed (its

     * contents searched). The passed URI must stand for a folder.

     *

     * @return One of constants of {@link FolderResult}. If

     * <code>TRAVERSE_ALL_SUBFOLDERS</code> is returned, this filter will not be

     * applied on the folder's children (both direct and indirect, both files

     * and folders)

     * @exception java.lang.IllegalArgumentException if the passed

     * <code>URI</code> is not a folder

     *

     * @since org.netbeans.api.search/1.4

     */

    public abstract @NonNull FolderResult traverseFolder(

            @NonNull URI folderUri) throws IllegalArgumentException;

import java.net.URI;

     * Create {@link Iterator} that iterates over all URIs in the search scope

     * that comply with search options and search filters.

     *

     * @param options Custom options. This object encapsulates custom search

     * filters, file name pattern and general search settings.

     * @param listener Listener that is notified when some important event

     * occurs during searching. Listener passed to {@link SearchComposition}

     * should be used here.

     * @param terminated Object that can be asked by the iterator whether the

     * search has been terminated.

     *

     * @return Iterator over all URIs that comply with specified options (in

     * the scope of this search info).

     *

     * @since org.netbeans.api.search/1.4

     */

    protected abstract @NonNull Iterator<URI> createUrisToSearchIterator(

            @NonNull SearchScopeOptions options,

            @NonNull SearchListener listener,

            @NonNull AtomicBoolean terminated);

    /**

    /**

     * Get {@link Iterable} that iterates over all URIs in the search scope

     * that comply with search options and search filters.

     *

     * @param options Custom options. This object encapsulates custom search

     * filters, file name pattern and general search settings.

     * @param listener Listener that is notified when some important event

     * occurs during searching. Listener passed to {@link SearchComposition}

     * should be used here.

     * @param terminated Object that can be asked by the iterator whether

     * the search has been terminated.

     *

     * <div class="nonnormative">

     * <p>

     *  This method can be used in for-each loops:

     * </p>

     * <pre>

     * {@code

     * for (URI uri: searchInfo.getUrisToSearch(opts,listnr,term) {

     *   ResultType result = somehowCheckFileContentMatches(fo);

     *   if (result != null) {

     *     searchResultsDisplayer.addMatchingObject(result);

     *   }

     * }}

     * </pre>

     * </div>

     *

     * @since org.netbeans.api.search/1.4

     */

    public final @NonNull Iterable<URI> getUrisToSearch(

            @NonNull final SearchScopeOptions options,

            @NonNull final SearchListener listener,

            @NonNull final AtomicBoolean terminated) {

        return new Iterable<URI>() {

            @Override

            public Iterator<URI> iterator() {

                return createUrisToSearchIterator(options, listener,

                        terminated);

            }

        };

    }

import java.net.URI;

     * Called when a file is skipped - filtered out by a filter.

     *

     * @param uri the skipped URI.

     * @param filter filter that filtered out the file (can be null).

     * @param message message describing reasons for skipping (can be null).

     *

     * @since org.netbeans.api.search/1.4

     */

    public void fileSkipped(@NonNull URI uri,

            @NullAllowed SearchFilterDefinition filter,

            @NullAllowed String message) {

    }

    /**

/*

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

 *

 * Copyright 2012 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 2012 Sun Microsystems, Inc.

 */

package org.netbeans.api.search.provider.impl;

import java.util.Iterator;

import java.util.NoSuchElementException;

import java.util.concurrent.atomic.AtomicBoolean;

import org.netbeans.api.search.SearchScopeOptions;

import org.netbeans.api.search.provider.SearchListener;

/**

 *

 * @author jhavlin

 */

public abstract class AbstractCompoundIterator<E, T> implements Iterator<T> {

    /**

     *

     */

    private final E[] elements;

    /**

     *

     */

    private int elementIndex;

    /**

     *

     */

    private Iterator<T> elementIterator = null;

    /**

     *

     */

    private T nextObject;

    /**

     *

     */

    private boolean upToDate;

    private SearchScopeOptions options;

    private SearchListener listener;

    private AtomicBoolean terminated;

    /**

     * Creates a new instance of

     * <code>CompoundSearchIterator</code>.

     *

     * @param elements elements of the compound iterator

     * @exception java.lang.IllegalArgumentException if the argument is

     * <code>null</code>

     */

    public AbstractCompoundIterator(E[] elements,

            SearchScopeOptions options, SearchListener listener,

            AtomicBoolean terminated) {

        if (elements == null) {

            throw new IllegalArgumentException("Elements are null");    //NOI18N

        } else if (options == null) {

            throw new IllegalArgumentException("Options are null");     //NOI18N

        }

        this.options = options;

        if (elements.length == 0) {

            this.elements = null;

            elementIndex = 0;

            upToDate = true;                //hasNext() returns always false

        } else {

            this.elements = elements;

            upToDate = false;

        }

        this.listener = listener;

        this.terminated = terminated;

    }

    /**

     */

    @Override

    public boolean hasNext() {

        if (!upToDate) {

            update();

        }

        return (elements != null) && (elementIndex < elements.length);

    }

    /**

     */

    @Override

    public T next() {

        if (!hasNext()) {

            throw new NoSuchElementException();

        }

        upToDate = false;

        return nextObject;

    }

    /**

     */

    private void update() {

        assert upToDate == false;

        if (elementIterator == null) {

            elementIterator = getIteratorFor(elements[elementIndex = 0], options,

                    listener, terminated);

        }

        while (!elementIterator.hasNext()) {

            elements[elementIndex] = null;

            if (++elementIndex == elements.length) {

                break;

            }

            elementIterator = getIteratorFor(elements[elementIndex], options,

                    listener, terminated);

        }

        if (elementIndex < elements.length) {

            nextObject = elementIterator.next();

        } else {

            elementIterator = null;

            nextObject = null;

        }

        upToDate = true;

    }

    @Override

    public void remove() {

        throw new UnsupportedOperationException();

    }

    protected abstract Iterator<T> getIteratorFor(E element,

            SearchScopeOptions options, SearchListener listener,

            AtomicBoolean terminated);

}

import java.net.URI;

import java.net.URI;

    public boolean searchFile(URI fileUri) {

        return definition.searchFile(fileUri);

    }

    @Override

    public FolderResult traverseFolder(URI folderUri)

            throws IllegalArgumentException {

        return definitionToClientFolderResult(

                definition.traverseFolder(folderUri));

    }

    @Override

        return definitionToClientFolderResult(

                definition.traverseFolder(folder));

    }

import java.net.URI;

    protected Iterator<URI> createUrisToSearchIterator(

            SearchScopeOptions options, SearchListener listener,

            AtomicBoolean terminated) {

        return delegate.urisToSearch(options, listener, terminated);

    }

    @Override

import java.net.URI;

    @Override

    public Iterator<URI> createUrisToSearchIterator(

            SearchScopeOptions options, SearchListener listener,

            AtomicBoolean terminated) {

        return Collections.<URI>emptyList().iterator();

    }

import java.net.URI;

        fileSkipped(fileObject.toURI(), filter, message);

    }

    @Override

    public void fileSkipped(URI uri, SearchFilterDefinition filter,

            String message) {

import java.io.File;

import java.net.URI;

import java.util.logging.Level;

import java.util.logging.Logger;

import org.openide.filesystems.FileUtil;

    private static final Logger LOG =

            Logger.getLogger(SearchFilterDefinition.class.getName());

    /**

     * Answers a question whether a file with given URI should be searched. The

     * file must be URI of a plain file (not folder).

     *

     * The default implementation creates a {@link FileObject} instance for each

     * URI and passes it to {@link #searchFile(FileObject)}. Override to improve

     * performance.

     *

     * @return

     * <code>true</code> if the given file should be searched;

     * <code>false</code> if not

     * @exception java.lang.IllegalArgumentException if the passed

     * <code>FileObject</code> is a folder

     *

     * @since org.netbeans.api.search/1.4

     */

    public boolean searchFile(@NonNull URI uri) {

        File f = null;

        try {

            f = new File(uri);

        } catch (IllegalArgumentException iae) {

            LOG.log(Level.INFO, null, iae);

            return false;

        }

        FileObject fo = FileUtil.toFileObject(f);

        if (fo == null) {

            return false;

        } else {

            return searchFile(fo);

        }

    }

    /**

     * Answers a questions whether a folder with given URI should be traversed

     * (its contents searched). The passed argument must be URI of a folder.

     *

     * The default implementation creates a {@link FileObject} instance for each

     * URI and passes it to {@link #traverseFolder(FileObject)}. Override to

     * improve performance.

     *

     * @return One of constants of {@link FolderResult}. If

     * <code>TRAVERSE_ALL_SUBFOLDERS</code> is returned, this filter will not be

     * applied on the folder's children (both direct and indirect, both files

     * and folders)

     * @exception java.lang.IllegalArgumentException if the passed

     * <code>FileObject</code> is not a folder

     *

     * @since org.netbeans.api.search/1.4

     */

    public @NonNull FolderResult traverseFolder(

            @NonNull URI uri) throws IllegalArgumentException {

        File f = null;

        try {

            f = new File(uri);

        } catch (IllegalArgumentException iae) {

            LOG.log(Level.INFO, null, iae);

            return FolderResult.DO_NOT_TRAVERSE;

        }

        FileObject fo = FileUtil.toFileObject(f);

        if (fo == null) {

            return FolderResult.DO_NOT_TRAVERSE;

        } else {

            return traverseFolder(fo);

        }

    }

import java.net.URI;

    /**

     * Specifies which

     * <code>URIs</code>s should be searched. The returned

     * <code>Iterator</code> needn't implement method

     * {@link java.util.Iterator#remove remove()} (i.e. it may throw

     * <code>UnsupportedOperationException</code> instead of actual

     * implementation).

     *

     * The default implementation uses internaly FileObject iterator returned by

     * {@link #filesToSearch(SearchScopeOptions, SearchListener, AtomicBoolean)}

     *

     * @param options File name pattern, traversing options and custom filters.

     * @param listener Listener that should be notified about important events

     * and progress.

     * @param terminated Object that can be asked whether the search has been

     * terminated by the user.

     * @return iterator which iterates over

     * <code>FileObject</code>s to be searched

     *

     * @since org.netbeans.api.search/1.4

     */

    public @NonNull

    Iterator<URI> urisToSearch(

            @NonNull SearchScopeOptions options,

            @NonNull SearchListener listener,

            @NonNull AtomicBoolean terminated) {

        final Iterator<FileObject> inner = filesToSearch(options,

                listener, terminated);

        return new Iterator<URI>() {

            @Override

            public boolean hasNext() {

                return inner.hasNext();

            }

            @Override

            public URI next() {

                FileObject next = inner.next();

                return next == null ? null : next.toURI();

            }

            @Override

            public void remove() {

                throw new UnsupportedOperationException();

            }

        };

    }

import java.net.URI;

import java.net.URI;

    @Override

    public boolean searchFile(URI uri) {

        return SharabilityQuery.getSharability(uri)

                != Sharability.NOT_SHARABLE;

    }

    @Override

    public FolderResult traverseFolder(URI uri)

            throws IllegalArgumentException {

        switch (SharabilityQuery.getSharability(uri)) {

            case SHARABLE:

                return FolderResult.TRAVERSE_ALL_SUBFOLDERS;

            case MIXED:

                return FolderResult.TRAVERSE;

            case UNKNOWN:

                return FolderResult.TRAVERSE;

            case NOT_SHARABLE:

                return FolderResult.DO_NOT_TRAVERSE;

            default:

                return FolderResult.TRAVERSE;

        }

    }

import java.net.URI;

import java.net.URI;

                @Override

                protected Iterator<URI> createUrisToSearchIterator(

                        SearchScopeOptions options, SearchListener listener,

                        AtomicBoolean terminated) {

                    throw new UnsupportedOperationException(

                            "Not supported yet.");                      //NOI18N

                }