8032025: Update repeating annotations demo

Reviewed-by: jfranck

src/share/sample/annotations/DependencyChecker/PluginChecker/src/checker/Device.java

+package checker;
+
+/*
+ * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   - Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *
+ *   - Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *
+ *   - Neither the name of Oracle nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This source code is provided to illustrate the usage of a given feature
+ * or technique and has been deliberately simplified. Additional steps
+ * required for a production-quality application, such as security checks,
+ * input validation and proper error handling, might not be present in
+ * this sample code.
+ */
+
+
+import javax.xml.bind.annotation.XmlElement;
+import javax.xml.bind.annotation.XmlRootElement;
+import java.util.Collections;
+import java.util.EnumMap;
+import java.util.Map;
+
+/**
+ * Represents the device configuration. The values are loaded from an XML file by JAXB.
+ */
+@XmlRootElement
+public class Device {
+
+    @XmlElement()
+    private Map<Module, Integer> supportedModules = new EnumMap<>(Module.class);
+
+    /**
+     * Returns map of supported modules. The map key is module. The map value is version.
+     *
+     * @return map of supported modules.
+     */
+    public Map<Module, Integer> getSupportedModules() {
+        return Collections.unmodifiableMap(supportedModules);
+    }
+}

src/share/sample/annotations/DependencyChecker/PluginChecker/src/checker/Kettle.xml

+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<!--
+  Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions
+  are met:
+
+    - Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+
+    - Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+
+    - Neither the name of Oracle nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+  IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+  PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+
+  This source code is provided to illustrate the usage of a given feature
+  or technique and has been deliberately simplified. Additional steps
+  required for a production-quality application, such as security checks,
+  input validation and proper error handling, might not be present in
+  this sample code.
+
+  -->
+
+<device>
+    <supportedModules>
+        <entry>
+            <key>DISPLAY</key>
+            <value>2</value>
+        </entry>
+        <entry>
+            <key>THERMOMETER</key>
+            <value>1</value>
+        </entry>
+        <entry>
+            <key>CLOCK</key>
+            <value>4</value>
+        </entry>
+    </supportedModules>
+</device>
\ No newline at end of file

src/share/sample/annotations/DependencyChecker/PluginChecker/src/checker/Module.java

+package checker;
+
+/*
+ * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   - Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *
+ *   - Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *
+ *   - Neither the name of Oracle nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This source code is provided to illustrate the usage of a given feature
+ * or technique and has been deliberately simplified. Additional steps
+ * required for a production-quality application, such as security checks,
+ * input validation and proper error handling, might not be present in
+ * this sample code.
+ */
+
+
+/**
+ * Represents available modules.
+ */
+public enum Module {
+
+    DISPLAY, CLOCK, THERMOMETER, HEATER, SPEAKER, GSM, LED;
+}

src/share/sample/annotations/DependencyChecker/PluginChecker/src/checker/PluginChecker.java

+/*
+ * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   - Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *
+ *   - Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *
+ *   - Neither the name of Oracle nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This source code is provided to illustrate the usage of a given feature
+ * or technique and has been deliberately simplified. Additional steps
+ * required for a production-quality application, such as security checks,
+ * input validation and proper error handling, might not be present in
+ * this sample code.
+ */
+package checker;
+
+import javax.annotation.processing.ProcessingEnvironment;
+import javax.annotation.processing.RoundEnvironment;
+import javax.annotation.processing.SupportedAnnotationTypes;
+import javax.annotation.processing.SupportedSourceVersion;
+import javax.lang.model.SourceVersion;
+import javax.lang.model.element.Element;
+import javax.lang.model.element.TypeElement;
+import javax.tools.Diagnostic;
+import javax.xml.bind.JAXBContext;
+import java.io.File;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
+
+import javax.xml.bind.JAXBException;
+
+/**
+ * Reads the device configuration from the XML file specified by -Adevice=device.xml.
+ * For each class in a project, checks required modules. If the device doesn't have
+ * the required module, then a compilation error will be shown.
+ */
+@SupportedAnnotationTypes("checker.RequireContainer")
+@SupportedSourceVersion(SourceVersion.RELEASE_8)
+public class PluginChecker extends javax.annotation.processing.AbstractProcessor {
+
+    /**
+     * Name of the option to get the path to the xml with device configuration.
+     */
+    public static final String DEVICE_OPTION = "device";
+    private Device device;
+
+    /**
+     * Only the device option is supported.
+     *
+     * {@inheritDoc}
+     */
+    @Override
+    public Set<String> getSupportedOptions() {
+        return new HashSet<>(Arrays.asList(DEVICE_OPTION));
+    }
+
+    /**
+     * Initializes the processor by loading the device configuration.
+     *
+     * {@inheritDoc}
+     */
+    @Override
+    public synchronized void init(ProcessingEnvironment processingEnv) {
+        super.init(processingEnv);
+        try {
+            String deviceOption = processingEnv.getOptions().get(DEVICE_OPTION);
+            device = (Device) JAXBContext.newInstance(Device.class)
+                    .createUnmarshaller().unmarshal(new File(deviceOption));
+        } catch (JAXBException e) {
+            throw new RuntimeException(
+                    "Please specify device by -Adevice=device.xml\n"
+                    + e.toString(), e);
+        }
+    }
+
+    /**
+     * Processes @Require annotations and checks that Device meets requirements.
+     *
+     * {@inheritDoc}
+     */
+    @Override
+    public boolean process(Set<? extends TypeElement> annotations,
+            RoundEnvironment roundEnv) {
+        for (Element el : roundEnv.getElementsAnnotatedWith(RequireContainer.class)) {
+            for (Require req : el.getAnnotationsByType(Require.class)) {
+                //for every Require annotation checks if device has module of required version.
+                Integer version = device.getSupportedModules().get(req.value());
+
+                if (version == null
+                        || version < req.minVersion()
+                        || version > req.maxVersion()) {
+                    //if module is optional then show only warning not error
+                    if (req.optional()) {
+                        processingEnv.getMessager()
+                                .printMessage(Diagnostic.Kind.WARNING,
+                                        "Plugin [" + el + "] requires " + req
+                                        + "\n but device " + (version == null
+                                        ? "doesn't have such module."
+                                        + " This module is optional."
+                                        + " So plugin will work but miss"
+                                        + " some functionality"
+                                        : "has " + version
+                                        + " version of that module"));
+                    } else {
+                        processingEnv.getMessager()
+                                .printMessage(Diagnostic.Kind.ERROR,
+                                        "Plugin [" + el + "] requires " + req
+                                        + "\n but device "
+                                        + (version == null
+                                        ? "doesn't have such module"
+                                        : "has " + version
+                                        + " version of that module"));
+                    }
+                }
+            }
+            return true;
+        }
+        return false;
+    }
+}

src/share/sample/annotations/DependencyChecker/PluginChecker/src/checker/Require.java

+/*
+ * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   - Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *
+ *   - Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *
+ *   - Neither the name of Oracle nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This source code is provided to illustrate the usage of a given feature
+ * or technique and has been deliberately simplified. Additional steps
+ * required for a production-quality application, such as security checks,
+ * input validation and proper error handling, might not be present in
+ * this sample code.
+ */
+package checker;
+
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * Indicates that a plug-in depends on a module.
+ */
+@Retention(RetentionPolicy.CLASS)
+@Repeatable(RequireContainer.class)
+public @interface Require {
+
+    /**
+     * Returns the required module.
+     *
+     * @return required module.
+     */
+    Module value();
+
+    /**
+     * Returns the minimum supported version of a module.
+     *
+     * @return minimum supported version of a module.
+     */
+    int minVersion() default 1;
+
+    /**
+     * Returns the maximum supported version of a module.
+     *
+     * @return maximum supported version of a module.
+     */
+    int maxVersion() default Integer.MAX_VALUE;
+
+    /**
+     * Returns true if a module is optional. A module is optional if a system
+     * works without that module but is missing some functionality. Returns false if a system
+     * won't work without the specified module.
+     *
+     * @return true if module is optional. False otherwise.
+     */
+    boolean optional() default false;
+}

src/share/sample/annotations/DependencyChecker/PluginChecker/src/checker/RequireContainer.java

+package checker;
+
+/*
+ * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   - Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *
+ *   - Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *
+ *   - Neither the name of Oracle nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This source code is provided to illustrate the usage of a given feature
+ * or technique and has been deliberately simplified. Additional steps
+ * required for a production-quality application, such as security checks,
+ * input validation and proper error handling, might not be present in
+ * this sample code.
+ */
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * A container for the repeatable @Require annotation.
+ */
+@Retention(RetentionPolicy.CLASS)
+public @interface RequireContainer {
+
+    Require[] value();
+}

src/share/sample/annotations/DependencyChecker/Plugins/src/plugins/BoilerPlugin.java

+/*
+ * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   - Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *
+ *   - Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *
+ *   - Neither the name of Oracle nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This source code is provided to illustrate the usage of a given feature
+ * or technique and has been deliberately simplified. Additional steps
+ * required for a production-quality application, such as security checks,
+ * input validation and proper error handling, might not be present in
+ * this sample code.
+ */
+package plugins;
+
+import checker.Module;
+import checker.Require;
+
+/**
+ * BoilerPlugin provides support for boiling water and keeping water warm.
+ */
+@Require(value = Module.CLOCK, maxVersion = 3)
+@Require(value = Module.THERMOMETER)
+@Require(value = Module.HEATER)
+@Require(value = Module.LED, optional = true) //will use if present
+public class BoilerPlugin {
+
+    /**
+     * Heats water up to 100 degrees Celsius.
+     */
+    public void boil() {
+        boil(100);
+    }
+
+    /**
+     * Heats water up to temperature.
+     *
+     * @param temperature - desired temperature of the water in the boiler
+     */
+    public void boil(int temperature) {
+        /*
+         * Turn on heater and wait while temperature reaches desired temperature
+         * in Celsius. Finally, turn off heater.
+         * If present, the LED light changes color according to the temperature.
+         */
+    }
+
+    /**
+     * Keeps desired temperature.
+     *
+     * @param temperature - desired temperature of the water in the boiler
+     * @param seconds - period of time for checking temperature in seconds
+     */
+    public void keepWarm(int temperature, int seconds) {
+        //Every n seconds check temperature and warm up, if necessary.
+    }
+
+}

src/share/sample/annotations/DependencyChecker/Plugins/src/plugins/ExtendedBoilerPlugin.java

+/*
+ * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   - Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *
+ *   - Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *
+ *   - Neither the name of Oracle nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This source code is provided to illustrate the usage of a given feature
+ * or technique and has been deliberately simplified. Additional steps
+ * required for a production-quality application, such as security checks,
+ * input validation and proper error handling, might not be present in
+ * this sample code.
+ */
+package plugins;
+
+import checker.Module;
+import checker.Require;
+import java.util.Calendar;
+
+/**
+ * Introduces new features for BoilerPlugin. Features are boiling water by an
+ * SMS and boiling water by date with notification by a phone call.
+ */
+@Require(value = Module.SPEAKER)
+@Require(value = Module.GSM, minVersion = 3)
+@Require(value = Module.DISPLAY)
+public class ExtendedBoilerPlugin extends BoilerPlugin {
+
+    /**
+     * Boils water at the appointed time and wakes you up by a ring and phone
+     * call. Shows "Good morning" and a quote of the day from the Internet on the
+     * display.
+     *
+     * @param calendar - date and time when water should be boiled
+     * @param phoneNumber - phone number to call
+     */
+    public void boilAndWakeUp(Calendar calendar, int phoneNumber) {
+        //implementation
+    }
+
+    /**
+     * Boils water at the appointed time by getting an SMS of fixed format.
+     * Sends an SMS on finish.
+     *
+     * @param sms - text of SMS
+     */
+    public void boilBySMS(String sms) {
+        //implementation
+    }
+}

src/share/sample/annotations/DependencyChecker/Plugins/src/plugins/TimerPlugin.java

+/*
+ * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   - Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *
+ *   - Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *
+ *   - Neither the name of Oracle nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This source code is provided to illustrate the usage of a given feature
+ * or technique and has been deliberately simplified. Additional steps
+ * required for a production-quality application, such as security checks,
+ * input validation and proper error handling, might not be present in
+ * this sample code.
+ */
+package plugins;
+
+import checker.Module;
+import checker.Require;
+
+/**
+ * Timer plug-in is used to support an alarm and a timer. It depends on Display and
+ * Clock modules.
+ */
+@Require(Module.DISPLAY)
+@Require(value = Module.CLOCK, maxVersion = 3)
+public class TimerPlugin {
+
+    /**
+     * Sets timer.
+     *
+     * @param time - the remaining time.
+     */
+    public void timer(long time) {
+        //start timer
+        //show the remaining time on display
+    }
+
+    /**
+     * Sets alarm.
+     *
+     * @param time - the alarm time.
+     */
+    public void alarm(long time) {
+        //start alarm
+        //show current time and alarm time on display
+    }
+}

src/share/sample/annotations/Validator/src/PositiveIntegerSupplier.java

+/*
+ * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   - Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *
+ *   - Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *
+ *   - Neither the name of Oracle nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This source code is provided to illustrate the usage of a given feature
+ * or technique and has been deliberately simplified. Additional steps
+ * required for a production-quality application, such as security checks,
+ * input validation and proper error handling, might not be present in
+ * this sample code.
+ */
+import java.util.function.Supplier;
+
+/**
+ * Supplies a positive number.
+ */
+@Validate(value = Validator.INTEGER_NUMBER,
+        description = "It's not an Integer ")
+@Validate(value = Validator.POSITIVE_NUMBER,
+        description = "It's not a positive Number")
+public class PositiveIntegerSupplier implements Supplier<String> {
+
+    /**
+     * Returns a string representation of a positive integer.
+     *
+     * @return string representation of a positive integer.
+     */
+    @Override
+    public String get() {
+        return "20005"; //random number
+    }
+}

src/share/sample/annotations/Validator/src/SupplierValidator.java

+/*
+ * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   - Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *
+ *   - Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *
+ *   - Neither the name of Oracle nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This source code is provided to illustrate the usage of a given feature
+ * or technique and has been deliberately simplified. Additional steps
+ * required for a production-quality application, such as security checks,
+ * input validation and proper error handling, might not be present in
+ * this sample code.
+ */
+import javax.xml.bind.ValidationException;
+import java.util.function.Supplier;
+
+/**
+ * Validates the supplier.
+ */
+public class SupplierValidator {
+
+    /**
+     * Validates the supplier.
+     *
+     * @param supplier - Supplier that needs to be validated.
+     * @return true if supplier has passed validation check. False otherwise.
+     */
+    public static boolean validate(Supplier<?> supplier) {
+        for (Validate annotation
+                : supplier.getClass().getAnnotationsByType(Validate.class)) {
+            try {
+                annotation.value().validate(supplier);
+            } catch (ValidationException e) {
+                System.out.println(annotation.description());
+                e.printStackTrace();
+                return false;
+            }
+        }
+        return true;
+    }
+}

src/share/sample/annotations/Validator/src/Validate.java

+/*
+ * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   - Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *
+ *   - Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *
+ *   - Neither the name of Oracle nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This source code is provided to illustrate the usage of a given feature
+ * or technique and has been deliberately simplified. Additional steps
+ * required for a production-quality application, such as security checks,
+ * input validation and proper error handling, might not be present in
+ * this sample code.
+ */
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * Indicates that the class should be validated by the specified validator.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Repeatable(ValidateContainer.class)
+public @interface Validate {
+
+    /**
+     * Returns the validator that should validate the annotated class.
+     *
+     * @return Validator that should validate annotated class.
+     */
+    Validator value();
+
+    /**
+     * Returns text to describe the failure of the validation check.
+     *
+     * @return text to describe the failure of the validation check.
+     */
+    String description() default "";
+}
+
+/**
+ * A container for the repeatable @Validate annotation.
+ *
+ * @author Andrey Nazarov
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@interface ValidateContainer {
+
+    Validate[] value();
+}

src/share/sample/annotations/Validator/src/Validator.java

+/*
+ * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   - Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *
+ *   - Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *
+ *   - Neither the name of Oracle nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This source code is provided to illustrate the usage of a given feature
+ * or technique and has been deliberately simplified. Additional steps
+ * required for a production-quality application, such as security checks,
+ * input validation and proper error handling, might not be present in
+ * this sample code.
+ */
+import javax.xml.bind.ValidationException;
+import java.util.function.Supplier;
+
+/**
+ * Enum of Validator implementations.
+ */
+public enum Validator {
+
+    /**
+     * This validator checks that the string represents an integer.
+     */
+    INTEGER_NUMBER {
+                /**
+                 * Checks that the string represents an integer.
+                 *
+                 * @param string - a string supplier
+                 * @throws ValidationException if the validation check fails
+                 */
+                @Override
+                void validate(Supplier<?> string) throws ValidationException {
+                    try {
+                        Integer.parseInt((String) string.get());
+                    } catch (NumberFormatException ex) {
+                        throw new ValidationException("Error while validating "
+                                + string.get());
+                    }
+                }
+            },
+    /**
+     * This validator checks that the string represents a positive number.
+     */
+    POSITIVE_NUMBER {
+                /**
+                 * Checks that the string represents a positive number.
+                 *
+                 * @param string - an string supplier
+                 * @throws ValidationException if the validation check fails
+                 */
+                @Override
+                void validate(Supplier<?> string) throws ValidationException {
+                    try {
+                        if (Double.compare(0.0, Double.parseDouble(
+                                        (String) string.get())) > 0) {
+                            throw new Exception();
+                        }
+                    } catch (Exception ex) {
+                        throw new ValidationException("Error while validating "
+                                + string.get());
+                    }
+                }
+            };
+
+    /**
+     * Checks that the supplier is valid.
+     *
+     * @param string - a string supplier
+     * @throws ValidationException if validation check fails
+     */
+    abstract void validate(Supplier<?> string) throws ValidationException;
+
+}

src/share/sample/annotations/index.html

+<!DOCTYPE html>
+<html>
+<head>
+    <title>Repeating Annotations Demo</title>
+</head>
+<body>
+<h2>Repeating Annotations Demo</h2>
+
+<p>
+    This demo shows how to use repeating annotations at runtime and at compile time.
+</p>
+
+<ul>
+    <li><h3>Dependency checker.</h3>
+
+        <p>
+            Shows how to define repeating annotations and process them at compile time.
+            The problem domain is some code that performs useful operations on hardware devices.
+            The code relies on "modules" to be present on the devices. Applicability of the code to a particular
+            device is checked while compiling the code for a particular device.
+            A set of modules provided by a device is listed in an xml file that turns red during the compilation
+            phase and is compared with the required module set specified by annotations.
+            For instance, there is kettle with hardware modules: thermometer, display, and clock.
+            There is also a boiler plug-in that requires clock, thermometer, heater, and optionally an LED light.
+
+            Build the PluginChecker annotation processor first.
+            Then, run javac with the annotation processor against plug-in sources using the following command: </p>
+
+        <code>javac -cp "PluginChecker.jar" -processor checker.PluginChecker -Adevice=Kettle.xml -proc:only &lt;source
+            files&gt;</code>
+
+        <p>
+            where <code>PluginChecker.jar</code> - path to jar file that contains PluginChecker annotation processor
+            class. </br>
+            <code>Kettle.xml</code> - path to device descriptor Kettle.xml                                         </br>
+            <code>&lt;source files&gt;</code> - source files in Plugins/src
+        </p>
+        For more information, see the source files.
+        </p>
+        <ul>
+            <li>Annotation processor sources: <a href="DependencyChecker/PluginChecker/src/">DependencyChecker/PluginChecker/src</a>
+            <li>Processing of repeating annotations can be found in <a href="DependencyChecker/PluginChecker/src/checker/PluginChecker.java">PluginChecker.java</a>
+            <li>Usage of repeating annotation is shown in modules sources.<a href="DependencyChecker/Plugins/src">DependencyChecker/Plugins/src</a>
+        </ul>
+
+    <li><h3>Validator.</h3>
+
+        <p>
+            Shows how to define repeating annotations and process them at runtime.
+            A problem domain is code that needs to validate provided Suppliers for conformance to some criteria.
+            The criteria are implemented by the Validator class which is applied by using annotations that are placed in
+            the code whenever validation is needed. For more information, see the
+            source files.
+        </p>
+
+        <p>
+        <ul>
+            <li>Usage of repeating annotation is described in <a href="Validator/src/PositiveIntegerSupplier.java">PositiveIntegerSupplier.java</a>
+            <li> Example of how to define a repeating annotation type can be found in
+                <a href="Validator/src/Validate.java">Validate.java</a>
+            <li> Usages of the new reflective methods can be found in <a href="Validator/src/SupplierValidator.java">SupplierValidator.java</a>
+        </ul>
+        </p>
+        Sources: <a href="Validator/src/">Validator/src/</a>
+</ul>
+</body>
+</html>
\ No newline at end of file