001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing, software
013     * distributed under the License is distributed on an "AS IS" BASIS,
014     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015     * See the License for the specific language governing permissions and
016     * limitations under the License.
017     */
018    
019    package org.apache.hadoop.metrics2;
020    
021    import org.apache.hadoop.classification.InterfaceAudience;
022    import org.apache.hadoop.classification.InterfaceStability;
023    
024    /**
025     * The metrics system interface
026     */
027    @InterfaceAudience.Public
028    @InterfaceStability.Evolving
029    public abstract class MetricsSystem implements MetricsSystemMXBean {
030    
031      @InterfaceAudience.Private
032      public abstract MetricsSystem init(String prefix);
033    
034      /**
035       * Register a metrics source
036       * @param <T>   the actual type of the source object
037       * @param source object to register
038       * @param name  of the source. Must be unique or null (then extracted from
039       *              the annotations of the source object.)
040       * @param desc  the description of the source (or null. See above.)
041       * @return the source object
042       * @exception MetricsException
043       */
044      public abstract <T> T register(String name, String desc, T source);
045    
046      /**
047       * Register a metrics source (deriving name and description from the object)
048       * @param <T>   the actual type of the source object
049       * @param source  object to register
050       * @return  the source object
051       * @exception MetricsException
052       */
053      public <T> T register(T source) {
054        return register(null, null, source);
055      }
056    
057      /**
058       * @param name  of the metrics source
059       * @return the metrics source (potentially wrapped) object
060       */
061      @InterfaceAudience.Private
062      public abstract MetricsSource getSource(String name);
063    
064      /**
065       * Register a metrics sink
066       * @param <T>   the type of the sink
067       * @param sink  to register
068       * @param name  of the sink. Must be unique.
069       * @param desc  the description of the sink
070       * @return the sink
071       * @exception MetricsException
072       */
073      public abstract <T extends MetricsSink>
074      T register(String name, String desc, T sink);
075    
076      /**
077       * Register a callback interface for JMX events
078       * @param callback  the callback object implementing the MBean interface.
079       */
080      public abstract void register(Callback callback);
081    
082      /**
083       * Requests an immediate publish of all metrics from sources to sinks.
084       * 
085       * This is a "soft" request: the expectation is that a best effort will be
086       * done to synchronously snapshot the metrics from all the sources and put
087       * them in all the sinks (including flushing the sinks) before returning to
088       * the caller. If this can't be accomplished in reasonable time it's OK to
089       * return to the caller before everything is done. 
090       */
091      public abstract void publishMetricsNow();
092    
093      /**
094       * Shutdown the metrics system completely (usually during server shutdown.)
095       * The MetricsSystemMXBean will be unregistered.
096       * @return true if shutdown completed
097       */
098      public abstract boolean shutdown();
099    
100      /**
101       * The metrics system callback interface (needed for proxies.)
102       */
103      public interface Callback {
104        /**
105         * Called before start()
106         */
107        void preStart();
108    
109        /**
110         * Called after start()
111         */
112        void postStart();
113    
114        /**
115         * Called before stop()
116         */
117        void preStop();
118    
119        /**
120         * Called after stop()
121         */
122        void postStop();
123      }
124    
125      /**
126       * Convenient abstract class for implementing callback interface
127       */
128      public static abstract class AbstractCallback implements Callback {
129        @Override public void preStart() {}
130        @Override public void postStart() {}
131        @Override public void preStop() {}
132        @Override public void postStop() {}
133      }
134    }