<change id="named.service.definition">

        <api name="lookup"/>

        <summary>Easy and robust way to register named services</summary>

        <version major="8" minor="14"/>

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

        <author login="jtulach"/>

        <compatibility

            addition="yes"

            binary="compatible" deletion="no" deprecation="no"

            modification="no" semantic="compatible" source="compatible"

        />

        <description>

            <p>

                Meta annotation <code>@NamedServiceDefinition</code> 

                for those who define their own annotations that register

                something into <code>Lookups.forPath</code>.

            </p>

        </description>

        <class package="org.openide.util.lookup" name="NamedServiceDefinition"/>

        <issue number="179289"/>

    </change>

org.netbeans.modules.openide.util.NamedServiceProcessor

/*

 * 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.modules.openide.util;

import java.io.BufferedReader;

import java.io.IOException;

import java.io.InputStream;

import java.io.InputStreamReader;

import java.lang.annotation.Annotation;

import java.net.URL;

import java.util.ArrayList;

import java.util.Enumeration;

import java.util.HashSet;

import java.util.List;

import java.util.Set;

import java.util.regex.Matcher;

import java.util.regex.Pattern;

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.type.TypeMirror;

import javax.tools.Diagnostic;

import org.openide.util.lookup.NamedServiceDefinition;

import org.openide.util.lookup.implspi.AbstractServiceProviderProcessor;

@SupportedSourceVersion(SourceVersion.RELEASE_6)

public final class NamedServiceProcessor extends AbstractServiceProviderProcessor {

    private static final String PATH = "META-INF/namedservices.index"; // NOI18N

    @Override

    public Set<String> getSupportedAnnotationTypes() {

        Set<String> all = new HashSet<String>();

        all.add(NamedServiceDefinition.class.getName());

        searchAnnotations(all, true);

        return all;

    }

    @Override

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

        for (Element e : roundEnv.getElementsAnnotatedWith(NamedServiceDefinition.class)) {

            NamedServiceDefinition nsd = e.getAnnotation(NamedServiceDefinition.class);

            register(e, PATH);

        }

        Set<String> index = new HashSet<String>();

        searchAnnotations(index, false);

        for (String className : index) {

            Class<? extends Annotation> c;

            try {

                c = Class.forName(className).asSubclass(Annotation.class);

            } catch (ClassNotFoundException ex) {

                throw new IllegalStateException(ex);

            }

            for (Element e : roundEnv.getElementsAnnotatedWith(c)) {

                Annotation a = e.getAnnotation(c);

                NamedServiceDefinition nsd = c.getAnnotation(NamedServiceDefinition.class);

                int cnt = 0;

                for (Class<?> type : nsd.serviceType()) {

                    TypeMirror typeMirror = asType(type);

                    if (processingEnv.getTypeUtils().isSubtype(e.asType(), typeMirror)) {

                        cnt++;

                        for (String p : findPath(nsd.path(), a)) {

                            register(

                                e, c, typeMirror, p,

                                findPosition(nsd.position(), a)

                            );

                        }

                    }

                    if (cnt == 0) {

                        processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "Not right subclass!", e);

                    }

                }

            }

        }

        return true;

    }

    private TypeMirror asType(Class<?> type) {

        return processingEnv.getElementUtils().getTypeElement(type.getName()).asType();

    }

    private static Pattern reference;

    private List<String> findPath(String path, Annotation a) {

        if (reference == null) {

            reference = Pattern.compile("@([^/]+)\\(\\)"); // NOI18N

        }

        List<String> arr = new ArrayList<String>();

        arr.add(path);

        RESTART: for (;;) {

            for (int i = 0; i < arr.size(); i++) {

                Matcher m = reference.matcher(arr.get(i));

                if (m.find()) {

                    String methodName = m.group(1);

                    System.err.println("search for " + m.group(1) + " in " + path);

                    Object obj;

                    try {

                        obj = a.getClass().getMethod(methodName).invoke(a);

                    } catch (Exception ex) {

                        throw new IllegalStateException(methodName, ex);

                    }

                    if (obj instanceof String) {

                        arr.set(i, substitute(path, m, (String)obj));

                    } else if (obj instanceof String[]) {

                        String[] subs = (String[])obj;

                        arr.set(i, substitute(path, m, subs[0]));

                        for (int j = 1; j < subs.length; j++) {

                            arr.add(substitute(path, m, subs[j]));

                        }

                    } else {

                        throw new IllegalStateException("Wrong return value " + obj); // NOI18N

                    }

                    continue RESTART;

                }

            }

            break RESTART;

        }

        return arr;

    }

    private Integer findPosition(String posDefinition, Annotation a) {

        if (posDefinition.length() == 1 && posDefinition.charAt(0) == 0) {

            try {

                return (Integer)a.getClass().getMethod("position").invoke(a);

            } catch (NoSuchMethodException ex) {

                return Integer.MAX_VALUE;

            } catch (Exception ex) {

                throw new IllegalStateException(ex);

            }

        }

        try {

            return (Integer)a.getClass().getMethod(posDefinition).invoke(a);

        } catch (Exception ex) {

            throw new IllegalStateException(ex);

        }

    }

    private static void searchAnnotations(Set<String> found, boolean canonicalName) {

        try {

            Enumeration<URL> en = NamedServiceProcessor.class.getClassLoader().getResources(PATH);

            while (en.hasMoreElements()) {

                URL url = en.nextElement();

                InputStream is = url.openStream();

                BufferedReader reader = new BufferedReader(new InputStreamReader(is, "UTF-8")); // NOI18N

                // XXX consider using ServiceLoaderLine instead

                while (true) {

                    String line = reader.readLine();

                    if (line == null) {

                        break;

                    }

                    line = line.trim();

                    if (line.startsWith("#")) { // NOI18N

                        continue;

                    }

                    if (canonicalName) {

                        line = line.replace('$', '.');

                    }

                    found.add(line);

                }

            }

        } catch (IOException ex) {

            throw new IllegalStateException(ex);

        }

    }

    private static String substitute(String path, Matcher m, String obj) {

        return path.substring(0, m.start(0)) + obj + path.substring(m.end(0));

    }

}

/*

 * 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.openide.util.lookup;

import java.lang.annotation.ElementType;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

/** Annotation to simplify creation and add robustness to usage of

 * various named service registration annotations. For example

 * the {@code @}<a href="@org-openide-util@/org/openide/util/URLStreamHandlerRegistration.html">

 * URLStreamHandlerRegistration</a> annotation uses the {@link NamedServiceDefinition}

 * as: <pre>

 * {@code @NamedServiceDefinition(path="URLStreamHandler/@protocol()", serviceType=URLStreamHandler.class)}

 * </pre>

 * The above instructs the annotation processor that handles {@link NamedServiceDefinition}s

 * to verify the annotated type is subclass of <code>URLStreamHandler</code> and

 * if so, register it into <code>URLStreamHandler/@protocol</code> where the

 * value of <code>@protocol()</code> is replaced by the value of annotation's

 * <a href="@org-openide-util@/org/openide/util/URLStreamHandlerRegistration.html#protocol()">

 * protocol attribute</a>. The registration can later be found by using

 * {@link Lookups#forPath(java.lang.String) Lookups.forPath("URLStreamHandler/ftp")}

 * (in case the protocol was ftp).

 *

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

 * @since 8.14

 */

@Retention(RetentionPolicy.RUNTIME)

@Target(ElementType.ANNOTATION_TYPE)

public @interface NamedServiceDefinition {

    /** Type, or array of types that the registered type

     * has to implement.

     */

    public Class<?>[] serviceType();

    /** Path to register the annotation to, so it can later be found by

     * using {@link Lookups#forPath(java.lang.String) Lookups.forPath(theSamePath)}.

     * The path may reference attributes of the annotated annotation by prefixing

     * them with {@code @}. To reuse attribute named <code>location</code> one

     * can for example use <code>"how/to/get/to/@location/please"</code>

     * These attributes must be of type <code>String</code>

     * or array of <code>String</code>s.

     */

    public String path();

    /** Name of attribute that specifies position. By default the system tries

     * to find <code>int position()</code> attribute in the defined annotation

     * and use it to specify the order of registrations. In case a different

     * attribute should be used to specify position, can be provide its

     * name by specifying non-default here. Should the position be ignored,

     * specify empty string.

     * 

     * @param name of attribute in the annotated annotation to use for defining

     *   position of the registration. The attribute should return int value.

     */

    public String position() default "\u0000";

}

        if (getClass().getName().equals("org.netbeans.modules.openide.util.NamedServiceProcessor")) { // NOI18N

            // OK subclass

            return;

        }

        String impl = processingEnv.getElementUtils().getBinaryName(clazz).toString();

        String xface = processingEnv.getElementUtils().getBinaryName((TypeElement) processingEnv.getTypeUtils().asElement(type)).toString();

        if (!processingEnv.getTypeUtils().isAssignable(clazz.asType(), type)) {

            AnnotationMirror ann = findAnnotationMirror(clazz, annotation);

            processingEnv.getMessager().printMessage(Kind.ERROR, impl + " is not assignable to " + xface,

                    clazz, ann, findAnnotationValue(ann, "service"));

            return;

        }

        String rsrc = (path.length() > 0 ? "META-INF/namedservices/" + path + "/" : "META-INF/services/") + xface;

        registerImpl(clazz, impl, rsrc, position, supersedes);

    }

    protected final void register(Element el, String path) {

        TypeElement clazz = (TypeElement)el;

/*

 * 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.openide.util.lookup;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.net.URL;

import java.net.URLClassLoader;

import java.util.concurrent.Callable;

import org.netbeans.junit.NbTestCase;

import org.openide.util.Lookup;

import org.openide.util.test.AnnotationProcessorTestUtils;

/**

 *

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

 */

public class NamedServiceDefinitionTest extends NbTestCase {

    public NamedServiceDefinitionTest(String n) {

        super(n);

    }

    @Override

    protected void setUp() throws Exception {

        clearWorkDir();

    }

    public void testNamedDefinition() throws Exception {

        System.setProperty("executed", "false");

        String content = "import org.openide.util.lookup.NamedServiceDefinitionTest.RunTestReg;\n"

            + "@RunTestReg(position=10,when=\"now\")\n"

            + "public class Test implements Runnable {\n"

            + "  public void run() { System.setProperty(\"executed\", \"true\"); }\n"

            + "}\n";

        AnnotationProcessorTestUtils.makeSource(getWorkDir(), "x.Test", content);

        assertTrue("Compiles OK",

            AnnotationProcessorTestUtils.runJavac(getWorkDir(), null, getWorkDir(), null, System.err)

            );

        URLClassLoader l = new URLClassLoader(new URL[] { getWorkDir().toURI().toURL() }, NamedServiceDefinitionTest.class.getClassLoader());

        Lookup lkp = Lookups.metaInfServices(l, "META-INF/namedservices/runtest/now/below/");

        for (Runnable r : lkp.lookupAll(Runnable.class)) {

            r.run();

        }

        assertEquals("Our runnable was executed", "true", System.getProperty("executed"));

    }

    public void testNamedDefinitionWithArray() throws Exception {

        System.setProperty("executed", "false");

        String content = "import org.openide.util.lookup.NamedServiceDefinitionTest.RunTestArray;\n"

            + "@RunTestArray(position=10,array={\"now\", \"then\" })\n"

            + "public class Test implements Runnable {\n"

            + "  public void run() { System.setProperty(\"executed\", \"true\"); }\n"

            + "}\n";

        AnnotationProcessorTestUtils.makeSource(getWorkDir(), "x.Test", content);

        assertTrue("Compiles OK",

            AnnotationProcessorTestUtils.runJavac(getWorkDir(), null, getWorkDir(), null, System.err)

            );

        URLClassLoader l = new URLClassLoader(new URL[] { getWorkDir().toURI().toURL() }, NamedServiceDefinitionTest.class.getClassLoader());

        Lookup lkp = Lookups.metaInfServices(l, "META-INF/namedservices/runtest/now/");

        for (Runnable r : lkp.lookupAll(Runnable.class)) {

            r.run();

        }

        assertEquals("Our runnable was executed", "true", System.getProperty("executed"));

        System.setProperty("executed", "false");

        Lookup lkp2 = Lookups.metaInfServices(l, "META-INF/namedservices/runtest/then/");

        for (Runnable r : lkp2.lookupAll(Runnable.class)) {

            r.run();

        }

        assertEquals("Our runnable was executed again", "true", System.getProperty("executed"));

    }

    @NamedServiceDefinition(

        path="runtest/@when()/below",

        serviceType={ Runnable.class, Callable.class }

    )

    @Retention(RetentionPolicy.SOURCE)

    public static @interface RunTestReg {

        public int position();

        public String when();

    }

    @NamedServiceDefinition(

        path="runtest/@array()",

        serviceType={ Runnable.class, Callable.class }

    )

    @Retention(RetentionPolicy.SOURCE)

    public static @interface RunTestArray {

        public int position();

        public String[] array();

    }

}

import org.openide.util.lookup.NamedServiceDefinition;

@NamedServiceDefinition(path="URLStreamHandler/@protocol()", serviceType=URLStreamHandler.class)