View Javadoc

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( &quot;mySaopService.sent&quot;, bytes );
33   * 
34   *     String reply = service.call( message );
35   * 
36   *     bytes = reply.getBytes().length;
37   *     Monitoring.add( &quot;mySaopService.received&quot;, 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( &quot;myBusinessMethod&quot; );
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 }