1 /*
2 ~ Copyright 2006-2007 Nicolas De Loof.
3 ~
4 ~ Licensed under the Apache License, Version 2.0 (the "License");
5 ~ you may not use this file except in compliance with the License.
6 ~ You may obtain a copy of the License at
7 ~
8 ~ http://www.apache.org/licenses/LICENSE-2.0
9 ~
10 ~ Unless required by applicable law or agreed to in writing, software
11 ~ distributed under the License is distributed on an "AS IS" BASIS,
12 ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 ~ See the License for the specific language governing permissions and
14 ~ limitations under the License.
15 */
16 package org.jmonit;
17
18 import org.jmonit.features.DefaultPluginManager;
19 import org.jmonit.repositories.DefaultRepository;
20
21 /**
22 * <b>Monitoring</b> is a convenience entry point in the jMonit API. It handles
23 * a default Repository and defines static methods for accessing monitors.
24 * <p>
25 * The {@link #add(String, long)} method is designed to easily add any numeric
26 * value to the specified monitor.
27 *
28 * <pre>
29 * public String callMySaopService( Sring message )
30 * {
31 * long bytes = message.getBytes().length;
32 * Monitoring.add( "mySaopService.sent", bytes );
33 *
34 * String reply = service.call( message );
35 *
36 * bytes = reply.getBytes().length;
37 * Monitoring.add( "mySaopService.received", bytes );
38 *
39 * return reply;
40 * }
41 * </pre>
42 *
43 * <p>
44 * The <code>start(..)</code> methods can be used to quickly create a Probe
45 * and monitor time consumed in a block of code. Never forget to stop the
46 * returned Probe ! A try / finally block is the safer way to ensure this with
47 * fiew impact on performances :
48 *
49 * <pre>
50 * public void myBusinessMethod()
51 * {
52 * Probe probe = Monitoring.start( "myBusinessMethod" );
53 * try
54 * {
55 * // Some bunsiness code you want to monitor here...
56 * }
57 * finally
58 * {
59 * probe.stop();
60 * }
61 * }
62 * </pre>
63 *
64 * @author <a href="mailto:nicolas.deloof@gmail.com">Nicolas De Loof</a>
65 */
66 public final class Monitoring
67 {
68 /** Repository containing all the monitoring monitors */
69 private static Repository repository;
70
71 static
72 {
73 repository = new DefaultRepository();
74 repository.setFeatureManager( new DefaultPluginManager() );
75 }
76
77 /**
78 * Add data to a monitor.
79 *
80 * @param name The monitor name
81 * @param value The value to be added (positive or negative)
82 */
83 public static void add( String name, long value )
84 {
85 getMonitor( name ).add( value );
86 }
87
88 /**
89 * Get an existing monitor or creates it.
90 *
91 * @return the monitor
92 * @param name The monitor name
93 */
94 public static Monitor getMonitor( String name )
95 {
96 return getRepository().getMonitor( name );
97 }
98
99 /**
100 * @return the repository
101 */
102 public static Repository getRepository()
103 {
104 return repository;
105 }
106
107 /**
108 * Replace the repository by a custom one.
109 *
110 * @param repository the repository to set
111 */
112 public static void setRepository( Repository repository )
113 {
114 Monitoring.repository = repository;
115 }
116
117 /**
118 * Start a new Stopwatch for the monitor 'name'.
119 *
120 * @param name The monitor name
121 * @return a Monitoring instance
122 */
123 public static Stopwatch start( String name )
124 {
125 Monitor monitor = getMonitor( name );
126 return Stopwatch.start( monitor );
127 }
128
129 /**
130 * Start a new Stopwatch for the monitor 'name', and apply the tags to the
131 * monitor.
132 *
133 * @param name The monitor name
134 * @param tags The tags to apply on the monitor
135 * @return a Monitoring instance
136 */
137 public static Stopwatch start( String name, String... tags )
138 {
139 Monitor monitor = getMonitor( name );
140 for ( String tag : tags )
141 {
142 monitor.tag( tag );
143 }
144 return Stopwatch.start( monitor );
145 }
146
147 /**
148 * Apply the specified tag to the specified monitor
149 *
150 * @param name monitor name
151 * @param tag tag
152 * @return the tagged monitor
153 */
154 public static Monitor tag( String name, String tag )
155 {
156 return getMonitor( name ).tag( tag );
157 }
158
159 /**
160 * Constructor
161 */
162 private Monitoring()
163 {
164 super();
165 }
166 }