<change id="ConstrainedBinaryIndexer">

      <api name="ParsingAPI"/>

      <summary>Added <code>ConstrainedBinaryIndexer</code> to prevent indexer creation when constrained are not fulfilled.</summary>

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

      <date day="10" month="11" year="2011"/>

      <author login="tzezula"/>

      <compatibility source="compatible" binary="compatible" semantic="compatible" deletion="no" addition="yes" modification="no"/>

      <description>

          <p>

              Added <code>ConstrainedBinaryIndexer</code> to prevent indexer creation and calling when declared

              constrained are not fulfilled. The <code>ConstrainedBinaryIndexer</code> allows an indexer to specify

              constrains which need to be fulfilled, the check is done by infrastructure before the indexer is loaded.

          </p>

      </description>

      <class package="org.netbeans.modules.parsing.spi.indexing" name="ConstrainedBinaryIndexer"/>

      <issue number="200050"/>

  </change>

/*

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

 *

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

 */

package org.netbeans.modules.parsing.impl.indexing;

import java.util.Collections;

import java.util.Set;

import javax.annotation.processing.Processor;

import javax.annotation.processing.RoundEnvironment;

import javax.annotation.processing.SupportedSourceVersion;

import javax.lang.model.SourceVersion;

import javax.lang.model.element.Element;

import javax.lang.model.element.TypeElement;

import javax.lang.model.util.Elements;

import javax.lang.model.util.Types;

import org.netbeans.modules.parsing.spi.indexing.BinaryIndexerFactory;

import org.netbeans.modules.parsing.spi.indexing.ConstrainedBinaryIndexer;

import org.openide.filesystems.annotations.LayerBuilder.File;

import org.openide.filesystems.annotations.LayerGeneratingProcessor;

import org.openide.filesystems.annotations.LayerGenerationException;

import org.openide.util.lookup.ServiceProvider;

/**

 * {@link LayerGeneratingProcessor} to generate {@link BinaryIndexer} registrations.

 * @author Jaroslav Tulach <jtulach@netbeans.org>

 * @author Tomas Zezula

 */

@ServiceProvider(service=Processor.class)

@SupportedSourceVersion(SourceVersion.RELEASE_6)

public final class IndexerRegistrationProcessor extends LayerGeneratingProcessor {

    @Override

    public Set<String> getSupportedAnnotationTypes() {

        return Collections.singleton(ConstrainedBinaryIndexer.Registration.class.getCanonicalName());

    }

    @Override

    protected boolean handleProcess(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) throws LayerGenerationException {

        for (Element e : roundEnv.getElementsAnnotatedWith(ConstrainedBinaryIndexer.Registration.class)) {

            assert e.getKind().isClass();

            final ConstrainedBinaryIndexer.Registration reg = e.getAnnotation(ConstrainedBinaryIndexer.Registration.class);

            final Elements elements = processingEnv.getElementUtils();

            final Types types = processingEnv.getTypeUtils();

            final TypeElement binIndexerType = elements.getTypeElement(ConstrainedBinaryIndexer.class.getName());

            if (types.isSubtype(((TypeElement)e).asType(), binIndexerType.asType())) {

                final String indexerName = reg.indexerName();

                if (indexerName == null) {

                    throw new LayerGenerationException("Indexer name has to be given.", e); //NOI18N

                }

                final File f = layer(e).instanceFile("Editors", null, null);    //NOI18N

                f.stringvalue("instanceClass", BinaryIndexerFactory.class.getName());   //NOI18N

                f.methodvalue("instanceCreate", ConstrainedBinaryIndexer.class.getName(), "create");    //NOI18N

                f.instanceAttribute("delegate", ConstrainedBinaryIndexer.class);

                if (reg.requiredResource().length > 0) {

                    f.stringvalue("requiredResource", list(reg.requiredResource(), e)); //NOI18N

                }

                if (reg.mimeType().length > 0) {

                    f.stringvalue("mimeType", list(reg.mimeType(), e)); //NOI18N

                }

                f.stringvalue("name", indexerName);         //NOI18N

                f.intvalue("version", reg.indexVersion());  //NOI18N

                f.write();

            } else {

                throw new LayerGenerationException("Annoated element is not a  subclass of BinaryIndexer.",e); //NOI18N

            }

        }

        return true;

    }

    private static String list(String[] arr, Element e) throws LayerGenerationException {

        if (arr.length == 1) {

            return arr[0];

        }

        StringBuilder sb = new StringBuilder();

        for (String s : arr) {

            if (s.indexOf(',') >= 0) {  //NOI18N

                throw new LayerGenerationException("',' is not allowed in the text", e);    //NOI18N

            }

            sb.append(s).append(",");   //NOI18N

        }

        return sb.substring(0, sb.length() - 1);

    }

}

/*

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

 *

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

 */

package org.netbeans.modules.parsing.impl.indexing;

import java.net.URL;

import java.util.*;

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

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

import org.netbeans.modules.parsing.spi.indexing.BinaryIndexer;

import org.netbeans.modules.parsing.spi.indexing.BinaryIndexerFactory;

import org.netbeans.modules.parsing.spi.indexing.ConstrainedBinaryIndexer;

import org.netbeans.modules.parsing.spi.indexing.Context;

import org.openide.filesystems.FileObject;

import org.openide.util.Parameters;

/**

 *

 * @author Jaroslav Tulach <jtulach@netbeans.org>

 * @author Tomas Zezula

 */

public final class ProxyBinaryIndexerFactory extends BinaryIndexerFactory {

    private static final String ATTR_DELEGATE = "delegate";     //NOI18N

    private static final String ATTR_INDEXER_NAME = "name";     //NOI18N

    private static final String ATTR_INDEXER_VERSION = "version";   //NOI18N

    private static final String ATTR_REQUIRED_RES = "requiredResource"; //NOI18N

    private static final String ATTR_REQUIRED_MIME = "mimeType";    //NOI18N

    private static final String PROP_CHECKED = "ProxyBinaryIndexerFactory_checked";  //NOI18N

    private static final String PROP_MATCHED_FILES = "ProxyBinaryIndexerFactory_matchedFiles";  //NOI18N

    private final Map<String,Object> params;

    private final String indexerName;

    private final int indexerVersion;

    @org.netbeans.api.annotations.common.SuppressWarnings(

            value="DMI_COLLECTION_OF_URLS"

            /*,justification="URLs have never host part"*/)    //NOI18N

    private final Set<URL> activeRoots;

    public ProxyBinaryIndexerFactory(

            @NonNull final Map<String,Object> params) {

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

        this.params = params;

        indexerName = (String)params.get(ATTR_INDEXER_NAME);

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

        Integer iv = (Integer)params.get(ATTR_INDEXER_VERSION);

        Parameters.notNull("version", iv);                  //NOI18N

        indexerVersion = iv;

        activeRoots = new HashSet<URL>();

    }

    @Override

    public String getIndexerName() {

        return indexerName;

    }

    @Override

    public int getIndexVersion() {

        return indexerVersion;

    }

    @Override

    public BinaryIndexer createIndexer() {

        return new Indexer();

    }

    @Override

    public void rootsRemoved(Iterable<? extends URL> removedRoots) {

        final Set<URL> filtered = new HashSet<URL>();

        for (URL removedRoot : removedRoots) {

            if (activeRoots.remove(removedRoot)) {

                filtered.add(removedRoot);

            }

        }

        SPIAccessor.getInstance().rootsRemoved(

                getDelegate(),

                Collections.unmodifiableSet(filtered));

    }

    @Override

    public boolean scanStarted (final Context context) {

        if (supports(context) != null) {

            return SPIAccessor.getInstance().scanStarted(getDelegate(),context);

        }

        return true;

    }

    @Override

    public void scanFinished (final Context context) {

        if (supports(context) != null) {

            SPIAccessor.getInstance().scanFinished(getDelegate(),context);

        }

    }

    @CheckForNull

    private Map<String,? extends Iterable<? extends FileObject>> supports(@NonNull final Context ctx) {

        final FileObject root = ctx.getRoot();

        if (root == null) {

            return null;

        }

        if (Boolean.TRUE == SPIAccessor.getInstance().getProperty(ctx, PROP_CHECKED)) {

            return (Map<String,? extends Iterable<? extends FileObject>>) SPIAccessor.getInstance().getProperty(ctx, PROP_MATCHED_FILES);

        }

        final Map<String,Queue<FileObject>> matchedFiles = new HashMap<String, Queue<FileObject>>();

        String s = (String) params.get(ATTR_REQUIRED_RES);

        final String[] requiredResources = s == null ? null : s.split(","); //NOI18N

        s = (String) params.get(ATTR_REQUIRED_MIME);

        final String[] mimeTypes = s == null ? null : s.split(",");         //NOI18N

        try {

            if (requiredResources != null) {

                boolean found = false;

                for (String r : requiredResources) {

                    if (root.getFileObject(r) != null) {

                        found = true;

                        break;

                    }

                }

                if (!found) {

                    return null;

                }

            }

            if (mimeTypes != null) {

                final Enumeration<? extends FileObject> fos = root.getChildren(true);

                final Set<String> mimeTypesSet = new HashSet<String>(Arrays.asList(mimeTypes));

                while (fos.hasMoreElements()) {

                    final FileObject f = fos.nextElement();

                    final String mt = f.getMIMEType(mimeTypes);

                    if (mimeTypesSet.contains(mt)) {

                        Queue<FileObject> q = matchedFiles.get(mt);

                        if (q == null) {

                            q = new ArrayDeque<FileObject>();

                            matchedFiles.put(mt, q);

                        }

                        q.offer(f);

                    }

                }

                if (matchedFiles.isEmpty()) {

                    return null;

                }

            }

            final Map<String, ? extends Iterable<? extends FileObject>> res = Collections.unmodifiableMap(matchedFiles);

            SPIAccessor.getInstance().putProperty(ctx, PROP_MATCHED_FILES, res);

            return res;

        } finally {

            SPIAccessor.getInstance().putProperty(ctx, PROP_CHECKED, Boolean.TRUE);

        }

    }

    @NonNull

    private ConstrainedBinaryIndexer getDelegate() {

        final Object delegate = params.get(ATTR_DELEGATE);

        if (!(delegate instanceof ConstrainedBinaryIndexer)) {

            throw new IllegalArgumentException();

        }

        return (ConstrainedBinaryIndexer) delegate;

    }

    private final class Indexer extends BinaryIndexer {

        @Override

        protected void index(@NonNull final Context context) {

            final Map<String,? extends Iterable<? extends FileObject>> matchedFiles = supports(context);

            if (matchedFiles != null) {

                activeRoots.add(context.getRootURI());

                SPIAccessor.getInstance().index(

                    getDelegate(),

                    matchedFiles,

                    context);

            }

        }

    }

}

import java.util.Map;

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

    public abstract void index (@NonNull ConstrainedBinaryIndexer indexer, @NonNull Map<String,? extends Iterable<? extends FileObject>> files, @NonNull Context context);

    public abstract boolean scanStarted(@NonNull ConstrainedBinaryIndexer indexer, @NonNull Context context);

    public abstract void scanFinished(@NonNull ConstrainedBinaryIndexer indexer, @NonNull Context context);

    public abstract void rootsRemoved(@NonNull ConstrainedBinaryIndexer indexer, @NonNull Iterable<? extends URL> removed);

    public abstract void putProperty(@NonNull Context context, @NonNull String propName, @NullAllowed Object value);

    public abstract Object getProperty(@NonNull Context context, @NonNull String propName);

/*

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

 *

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

 */

package org.netbeans.modules.parsing.spi.indexing;

import java.lang.annotation.ElementType;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

import java.net.URL;

import java.util.Map;

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

import org.netbeans.modules.parsing.impl.indexing.ProxyBinaryIndexerFactory;

import org.openide.filesystems.FileObject;

/**

 * An binary indexer with declared constrains on the binary.

 * The subclasses of this indexer are registered by {@link ConstrainedBinaryIndexer.Registration}.

 * @author Tomas Zezula

 * @author Jaroslav Tulach <jtulach@netbeans.org>

 * @since 1.48

 */

public abstract class ConstrainedBinaryIndexer {

    /**

     * Indexes given binary root.

     * @param files the files passed the mime type constrain check, categorized

     * by the mime types.

     * @param context of indexer, contains information about index storage, indexed root.

     */

    protected abstract void index(

        @NonNull Map<String, ? extends Iterable<? extends FileObject>> files,

        @NonNull Context context);

    /**

     * Notifies the indexer that a binary root is going to be scanned.

     *

     * @param context The indexed binary root.

     *

     * @return <code>false</code> means that the whole root should be rescanned

     *   (eg. no up to date check is done, etc)

     */

    protected boolean scanStarted (@NonNull final Context context) {

        return true;

    }

    /**

     * Notifies the indexer that scanning of a binary root just finished.

     *

     * @param context The indexed binary root.

     *

     */

    protected void scanFinished (@NonNull final Context context) {

    }

    /**

     * Called by indexing infrastructure to notify indexer that roots were deregistered,

     * for example the project owning these roots was closed. The indexer may free memory caches

     * for given roots or do any other clean up.

     *

     * @param removedRoots the iterable of removed roots

     */

    protected void rootsRemoved (@NonNull final Iterable<? extends URL> removedRoots) {

    }

    /**

     * The annotation to register {@link ConstrainedBinaryIndexer} with constrains on

     * the scanned binary. The registered indexer is loaded and executed only of

     * the constrains are fulfilled.

     *

     */

    @Target(ElementType.TYPE)

    @Retention(RetentionPolicy.SOURCE)

    public @interface Registration {

        /**

         * Return the name of this indexer. This name should be unique because

         * GSF will use this name to produce a separate data directory for each

         * indexer where it has its own storage.

         *

         * @return The indexer name. This does not need to be localized since it

         * is never shown to the user, but should contain filesystem safe

         * characters.

         *

         * @see BinaryIndexerFactory

         */

        String indexerName();

        /**

         * Return the version stamp of the schema that is currently being stored

         * by this indexer. Along with the index name this string will be used

         * to create a unique data directory for the database.

         *

         * Whenever you incompatibly change what is stored by the indexer,

         * update the version stamp.

         *

         * @return The version stamp of the current index.

         *

         * @see BinaryIndexerFactory

         */

        int indexVersion();

        /**

         * At least one of these resources has to be present to trigger this

         * indexer. Use

         * <code>{}</code> if the resource check should be skipped.

         *

         * @return one or more paths inside the binary files that will be

         * checked for existence

         */

        String[] requiredResource() default {};

        /**

         * One or more mime types that have to be present inside of the binary

         * to enable this indexer. Use

         * <code>{}</code> if the resource check should be skipped.

         *

         * @return one or more mimetypes this indexer processing

         */

        String[] mimeType() default {};

    }

    private static BinaryIndexerFactory create(final Map<String,Object> params) {

        return new ProxyBinaryIndexerFactory(params);

    }

}

import java.util.HashMap;

import java.util.Map;

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

import org.openide.util.Parameters;

    private final Map<String,Object> props;

        this.props = new HashMap<String, Object>();

    void putProperty(

            @NonNull String propName,

            @NullAllowed final Object value) {

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

        props.put(propName, value);

    }

    Object getProperty(@NonNull String propName) {

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

        return props.get(propName);

    }

import java.util.Map;

import org.openide.util.Parameters;

        @Override

        public void index(

                @NonNull final ConstrainedBinaryIndexer indexer,

                @NonNull final Map<String,? extends Iterable<? extends FileObject>> files,

                @NonNull final Context context) {

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

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

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

            indexer.index(files, context);

        }

        @Override

        public boolean scanStarted(

                @NonNull final ConstrainedBinaryIndexer indexer,

                @NonNull final Context context) {

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

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

            return indexer.scanStarted(context);

        }

        @Override

        public void scanFinished(

                @NonNull final ConstrainedBinaryIndexer indexer,

                @NonNull final Context context) {

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

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

            indexer.scanFinished(context);

        }

        @Override

        public void rootsRemoved(

                @NonNull ConstrainedBinaryIndexer indexer,

                @NonNull Iterable<? extends URL> removed) {

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

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

            indexer.rootsRemoved(removed);

        }

        @Override

        public void putProperty(

                @NonNull final Context context,

                @NonNull final String propName,

                @NullAllowed final Object value) {

            context.putProperty(propName, value);

        }

        @Override

        public Object getProperty(

                @NonNull final Context context,

                @NonNull final String propName) {

            return context.getProperty(propName);

        }

    static final String XSD_MIME = "text/xml";  //NOI18N