Add new scopes and sub-scopes

api/src/main/java/org/eclipse/microprofile/metrics/MetricRegistry.java

@@ -29,12 +29,12 @@
 /**
  * The registry that stores metrics and their metadata.
  * The MetricRegistry provides methods to register, create and retrieve metrics and their respective metadata.
- * 
- * 
+ *
+ *
  * @see MetricFilter
  */
 public abstract class MetricRegistry {
-    
+
     /**
      * An enumeration representing the scopes of the MetricRegistry
      */
@@ -43,26 +43,32 @@ public enum Type {
          * The Application (default) scoped MetricRegistry.
          * Any metric registered/accessed via CDI will use this MetricRegistry.
          */
-        APPLICATION("application"), 
-        
+        APPLICATION("application"),
+
         /**
          * The Base scoped MetricRegistry.
          * This MetricRegistry will contain required metrics specified in the MicroProfile Metrics specification.
          */
         BASE("base"),
-
+
+        /**
+         * The integrations metric registry.
+         * Integrations need to use a sub-registry per integration.
+         */
+        INTEGRATION("integration"),
+
         /**
          * The Vendor scoped MetricRegistry.
          * This MetricRegistry will contain vendor provided metrics which may vary between different vendors.
          */
         VENDOR("vendor");
-    
+
         private String name;
-        
+
         private Type(String name) {
             this.name = name;
         }
-        
+
         /**
          * Returns the name of the MetricRegistry scope.
          * @return the scope
@@ -98,7 +104,7 @@ private static void append(StringBuilder builder, String part) {
             builder.append(part);
         }
     }
-    
+
     /**
      * Concatenates a class name and elements to form a dotted name, eliding any null values or
      * empty strings.
@@ -112,7 +118,7 @@ public static String name(Class<?> klass, String... names) {
     }
 
     /**
-     * Given a {@link Metric}, registers it under the given name. 
+     * Given a {@link Metric}, registers it under the given name.
      * A {@link Metadata} object will be registered with the name and type.
      *
      * @param name   the name of the metric
@@ -122,7 +128,7 @@ public static String name(Class<?> klass, String... names) {
      * @throws IllegalArgumentException if the name is already registered
      */
     public abstract <T extends Metric> T register(String name, T metric) throws IllegalArgumentException;
-    
+
     /**
      * Given a {@link Metric}, registers it under the given name along with the provided {@link Metadata}.
      *
@@ -137,23 +143,23 @@ public static String name(Class<?> klass, String... names) {
 
 
     /**
-     * Return the {@link Counter} registered under this name; or create and register 
+     * Return the {@link Counter} registered under this name; or create and register
      * a new {@link Counter} if none is registered.
      * If a {@link Counter} was created, a {@link Metadata} object will be registered with the name and type.
      *
      * @param name the name of the metric
      * @return a new or pre-existing {@link Counter}
      */
     public abstract Counter counter(String name);
-    
+
     /**
-     * Return the {@link Counter} registered under the {@link Metadata}'s name; or create and register 
+     * Return the {@link Counter} registered under the {@link Metadata}'s name; or create and register
      * a new {@link Counter} if none is registered.
      * If a {@link Counter} was created, the provided {@link Metadata} object will be registered.
      * <p>
      * Note: The {@link Metadata} will not be updated if the metric is already registered.
      * </p>
-     * 
+     *
      * @param metadata the name of the metric
      * @return a new or pre-existing {@link Counter}
      */
@@ -162,23 +168,23 @@ public static String name(Class<?> klass, String... names) {
 
 
     /**
-     * Return the {@link Histogram} registered under this name; or create and register 
+     * Return the {@link Histogram} registered under this name; or create and register
      * a new {@link Histogram} if none is registered.
      * If a {@link Histogram} was created, a {@link Metadata}  object will be registered with the name and type.
      *
      * @param name the name of the metric
      * @return a new or pre-existing {@link Histogram}
      */
     public abstract Histogram histogram(String name);
-    
+
     /**
-     * Return the {@link Histogram} registered under the {@link Metadata}'s name; or create and register 
+     * Return the {@link Histogram} registered under the {@link Metadata}'s name; or create and register
      * a new {@link Histogram} if none is registered.
      * If a {@link Histogram} was created, the provided {@link Metadata} object will be registered.
      * <p>
      * Note: The {@link Metadata} will not be updated if the metric is already registered.
      * </p>
-     * 
+     *
      * @param metadata the name of the metric
      * @return a new or pre-existing {@link Histogram}
      */
@@ -194,15 +200,15 @@ public static String name(Class<?> klass, String... names) {
      * @return a new or pre-existing {@link Meter}
      */
     public abstract Meter meter(String name);
-    
+
     /**
-     * Return the {@link Meter} registered under the {@link Metadata}'s name; or create and register 
+     * Return the {@link Meter} registered under the {@link Metadata}'s name; or create and register
      * a new {@link Meter} if none is registered.
      * If a {@link Meter} was created, the provided {@link Metadata} object will be registered.
      * <p>
      * Note: The {@link Metadata} will not be updated if the metric is already registered.
      * </p>
-     * 
+     *
      * @param metadata the name of the metric
      * @return a new or pre-existing {@link Meter}
      */
@@ -218,20 +224,20 @@ public static String name(Class<?> klass, String... names) {
      * @return a new or pre-existing {@link Timer}
      */
     public abstract Timer timer(String name);
-    
+
     /**
-     * Return the {@link Timer} registered under the {@link Metadata}'s name; or create and register 
+     * Return the {@link Timer} registered under the {@link Metadata}'s name; or create and register
      * a new {@link Timer} if none is registered.
      * If a {@link Timer} was created, the provided {@link Metadata} object will be registered.
      * <p>
      * Note: The {@link Metadata} will not be updated if the metric is already registered.
      * </p>
-     * 
+     *
      * @param metadata the name of the metric
      * @return a new or pre-existing {@link Timer}
      */
     public abstract Timer timer(Metadata metadata);
- 
+
 
 
     /**
@@ -347,5 +353,5 @@ public static String name(Class<?> klass, String... names) {
      * @return all the metadata in the registry
      */
     public abstract Map<String, Metadata> getMetadata();
-    
+
 }

api/src/main/java/org/eclipse/microprofile/metrics/annotation/RegistryType.java

@@ -41,9 +41,9 @@
  *      {@literal @}RegistryType(type=MetricRegistry.Type.BASE)
  *      MetricRegistry baseRegistry;
  * </code></pre>
- * 
+ *
  * @see org.eclipse.microprofile.metrics.MetricRegistry.Type
- * 
+ *
  * @author Raymond Lam
  *
  */
@@ -52,5 +52,8 @@
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER, ElementType.ANNOTATION_TYPE })
 public @interface RegistryType {
+    /** type of registry */
     MetricRegistry.Type type() default MetricRegistry.Type.APPLICATION;
+    /** Sub-registry in case type is application or integration */
+    String subtype();
 }

api/src/main/java/org/eclipse/microprofile/metrics/annotation/SubRegistry.java

@@ -0,0 +1,46 @@
+/*
+ * ********************************************************************
+ *  Copyright (c) 2017 Contributors to the Eclipse Foundation
+ *
+ *  See the NOTICES file(s) distributed with this work for additional
+ *  information regarding copyright ownership.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  You may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *  SPDX-License-Identifier: Apache-2.0
+ * ********************************************************************
+ *
+ */
+package org.eclipse.microprofile.metrics.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Defines a sub-registry applicable for registries of
+ * type {@link org.eclipse.microprofile.metrics.MetricRegistry.Type#APPLICATION}
+ * and {@link org.eclipse.microprofile.metrics.MetricRegistry.Type#INTEGRATION}
+ *
+ * If set then all metrics of this application or integration use the
+ * passed sub registry.
+ * @author hrupp
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface SubRegistry {
+  String name();
+}