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 * Unregister a metrics source
048 * @param name of the source. This is the name you use to call register()
049 */
050 public abstract void unregisterSource(String name);
051
052 /**
053 * Register a metrics source (deriving name and description from the object)
054 * @param <T> the actual type of the source object
055 * @param source object to register
056 * @return the source object
057 * @exception MetricsException
058 */
059 public <T> T register(T source) {
060 return register(null, null, source);
061 }
062
063 /**
064 * @param name of the metrics source
065 * @return the metrics source (potentially wrapped) object
066 */
067 @InterfaceAudience.Private
068 public abstract MetricsSource getSource(String name);
069
070 /**
071 * Register a metrics sink
072 * @param <T> the type of the sink
073 * @param sink to register
074 * @param name of the sink. Must be unique.
075 * @param desc the description of the sink
076 * @return the sink
077 * @exception MetricsException
078 */
079 public abstract <T extends MetricsSink>
080 T register(String name, String desc, T sink);
081
082 /**
083 * Register a callback interface for JMX events
084 * @param callback the callback object implementing the MBean interface.
085 */
086 public abstract void register(Callback callback);
087
088 /**
089 * Requests an immediate publish of all metrics from sources to sinks.
090 *
091 * This is a "soft" request: the expectation is that a best effort will be
092 * done to synchronously snapshot the metrics from all the sources and put
093 * them in all the sinks (including flushing the sinks) before returning to
094 * the caller. If this can't be accomplished in reasonable time it's OK to
095 * return to the caller before everything is done.
096 */
097 public abstract void publishMetricsNow();
098
099 /**
100 * Shutdown the metrics system completely (usually during server shutdown.)
101 * The MetricsSystemMXBean will be unregistered.
102 * @return true if shutdown completed
103 */
104 public abstract boolean shutdown();
105
106 /**
107 * The metrics system callback interface (needed for proxies.)
108 */
109 public interface Callback {
110 /**
111 * Called before start()
112 */
113 void preStart();
114
115 /**
116 * Called after start()
117 */
118 void postStart();
119
120 /**
121 * Called before stop()
122 */
123 void preStop();
124
125 /**
126 * Called after stop()
127 */
128 void postStop();
129 }
130
131 /**
132 * Convenient abstract class for implementing callback interface
133 */
134 public static abstract class AbstractCallback implements Callback {
135 @Override public void preStart() {}
136 @Override public void postStart() {}
137 @Override public void preStop() {}
138 @Override public void postStop() {}
139 }
140 }