KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jrobin > core > RrdToolkit


1 /* ============================================================
2  * JRobin : Pure java implementation of RRDTool's functionality
3  * ============================================================
4  *
5  * Project Info: http://www.jrobin.org
6  * Project Lead: Sasa Markovic (saxon@jrobin.org);
7  *
8  * (C) Copyright 2003, by Sasa Markovic.
9  *
10  * Developers: Sasa Markovic (saxon@jrobin.org)
11  * Arne Vandamme (cobralord@jrobin.org)
12  *
13  * This library is free software; you can redistribute it and/or modify it under the terms
14  * of the GNU Lesser General Public License as published by the Free Software Foundation;
15  * either version 2.1 of the License, or (at your option) any later version.
16  *
17  * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
18  * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
19  * See the GNU Lesser General Public License for more details.
20  *
21  * You should have received a copy of the GNU Lesser General Public License along with this
22  * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
23  * Boston, MA 02111-1307, USA.
24  */

25
26 package org.jrobin.core;
27
28 import java.io.*;
29
30 /**
31  * <p>Class used to perform various complex operations on RRD files. Use an instance of the
32  * RrdToolkit class to:</p>
33  * <ul>
34  * <li>add datasource to a RRD file.
35  * <li>add archive to a RRD file.
36  * <li>remove datasource from a RRD file.
37  * <li>remove archive from a RRD file.
38  * </ul>
39  * <p>All these operations can be performed on the copy of the original RRD file, or on the
40  * original file itself (with possible backup file creation)</p>
41  */

42 public class RrdToolkit {
43     private static RrdToolkit ourInstance;
44
45     /**
46      * Returns an instance of RrdToolkit.
47      * @return Toolkint instance to work with
48      */

49     public synchronized static RrdToolkit getInstance() {
50         if (ourInstance == null) {
51             ourInstance = new RrdToolkit();
52         }
53         return ourInstance;
54     }
55
56     private RrdToolkit() {
57     }
58
59     /**
60      * Creates a new RRD file with one more datasource in it. RRD file is created based on the
61      * existing one (the original RRD file is not modified at all). All data from
62      * the original RRD file is copied to the new one.
63      * @param sourcePath path to a RRD file to import data from (will not be modified)
64      * @param destPath path to a new RRD file (will be created)
65      * @param newDatasource Datasource definition to be added to the new RRD file
66      * @throws IOException Thrown in case of I/O error
67      * @throws RrdException Thrown in case of JRobin specific error
68      */

69     public void addDatasource(String JavaDoc sourcePath, String JavaDoc destPath, DsDef newDatasource)
70         throws IOException, RrdException {
71         if (Util.sameFilePath(sourcePath, destPath)) {
72             throw new RrdException("Source and destination paths are the same");
73         }
74         RrdDb rrdSource = new RrdDb(sourcePath);
75         RrdDef rrdDef = rrdSource.getRrdDef();
76         rrdDef.setPath(destPath);
77         rrdDef.addDatasource(newDatasource);
78         RrdDb rrdDest = new RrdDb(rrdDef);
79         rrdSource.copyStateTo(rrdDest);
80         rrdSource.close();
81         rrdDest.close();
82     }
83
84     /**
85      * <p>Adds one more datasource to a RRD file.</p>
86      * <p>WARNING: This method is potentialy dangerous! It will modify your RRD file.
87      * It is highly recommended to preserve the original RRD file (<i>saveBackup</i>
88      * should be set to <code>true</code>). The backup file will be created in the same
89      * directory as the original one with <code>.bak</code> extension added to the
90      * original name.</p>
91      * <p>Before applying this method, be sure that the specified RRD file is not in use
92      * (not open)</p>
93      * @param sourcePath path to a RRD file to add datasource to.
94      * @param newDatasource Datasource definition to be added to the RRD file
95      * @param saveBackup true, if backup of the original file should be created;
96      * false, otherwise
97      * @throws IOException Thrown in case of I/O error
98      * @throws RrdException Thrown in case of JRobin specific error
99      */

100     public void addDatasource(String JavaDoc sourcePath, DsDef newDatasource, boolean saveBackup)
101         throws IOException, RrdException {
102         String JavaDoc destPath = Util.getTmpFilename();
103         addDatasource(sourcePath, destPath, newDatasource);
104         copyFile(destPath, sourcePath, saveBackup);
105     }
106
107     /**
108      * Creates a new RRD file with one datasource removed. RRD file is created based on the
109      * existing one (the original RRD file is not modified at all). All remaining data from
110      * the original RRD file is copied to the new one.
111      * @param sourcePath path to a RRD file to import data from (will not be modified)
112      * @param destPath path to a new RRD file (will be created)
113      * @param dsName Name of the Datasource to be removed from the new RRD file
114      * @throws IOException Thrown in case of I/O error
115      * @throws RrdException Thrown in case of JRobin specific error
116      */

117     public void removeDatasource(String JavaDoc sourcePath, String JavaDoc destPath, String JavaDoc dsName)
118         throws IOException, RrdException {
119         if (Util.sameFilePath(sourcePath, destPath)) {
120             throw new RrdException("Source and destination paths are the same");
121         }
122         RrdDb rrdSource = new RrdDb(sourcePath);
123         RrdDef rrdDef = rrdSource.getRrdDef();
124         rrdDef.setPath(destPath);
125         rrdDef.removeDatasource(dsName);
126         RrdDb rrdDest = new RrdDb(rrdDef);
127         rrdSource.copyStateTo(rrdDest);
128         rrdSource.close();
129         rrdDest.close();
130     }
131
132     /**
133      * <p>Removes single datasource from a RRD file.</p>
134      * <p>WARNING: This method is potentialy dangerous! It will modify your RRD file.
135      * It is highly recommended to preserve the original RRD file (<i>saveBackup</i>
136      * should be set to <code>true</code>). The backup file will be created in the same
137      * directory as the original one with <code>.bak</code> extension added to the
138      * original name.</p>
139      * <p>Before applying this method, be sure that the specified RRD file is not in use
140      * (not open)</p>
141      * @param sourcePath path to a RRD file to remove datasource from.
142      * @param dsName Name of the Datasource to be removed from the RRD file
143      * @param saveBackup true, if backup of the original file should be created;
144      * false, otherwise
145      * @throws IOException Thrown in case of I/O error
146      * @throws RrdException Thrown in case of JRobin specific error
147      */

148     public void removeDatasource(String JavaDoc sourcePath, String JavaDoc dsName, boolean saveBackup)
149         throws IOException, RrdException {
150         String JavaDoc destPath = Util.getTmpFilename();
151         removeDatasource(sourcePath, destPath, dsName);
152         copyFile(destPath, sourcePath, saveBackup);
153     }
154
155     /**
156      * Creates a new RRD file with one more archive in it. RRD file is created based on the
157      * existing one (the original RRD file is not modified at all). All data from
158      * the original RRD file is copied to the new one.
159      * @param sourcePath path to a RRD file to import data from (will not be modified)
160      * @param destPath path to a new RRD file (will be created)
161      * @param newArchive Archive definition to be added to the new RRD file
162      * @throws IOException Thrown in case of I/O error
163      * @throws RrdException Thrown in case of JRobin specific error
164      */

165     public void addArchive(String JavaDoc sourcePath, String JavaDoc destPath, ArcDef newArchive)
166         throws IOException, RrdException {
167         if (Util.sameFilePath(sourcePath, destPath)) {
168             throw new RrdException("Source and destination paths are the same");
169         }
170         RrdDb rrdSource = new RrdDb(sourcePath);
171         RrdDef rrdDef = rrdSource.getRrdDef();
172         rrdDef.setPath(destPath);
173         rrdDef.addArchive(newArchive);
174         RrdDb rrdDest = new RrdDb(rrdDef);
175         rrdSource.copyStateTo(rrdDest);
176         rrdSource.close();
177         rrdDest.close();
178     }
179
180     /**
181      * <p>Adds one more archive to a RRD file.</p>
182      * <p>WARNING: This method is potentialy dangerous! It will modify your RRD file.
183      * It is highly recommended to preserve the original RRD file (<i>saveBackup</i>
184      * should be set to <code>true</code>). The backup file will be created in the same
185      * directory as the original one with <code>.bak</code> extension added to the
186      * original name.</p>
187      * <p>Before applying this method, be sure that the specified RRD file is not in use
188      * (not open)</p>
189      * @param sourcePath path to a RRD file to add datasource to.
190      * @param newArchive Archive definition to be added to the RRD file
191      * @param saveBackup true, if backup of the original file should be created;
192      * false, otherwise
193      * @throws IOException Thrown in case of I/O error
194      * @throws RrdException Thrown in case of JRobin specific error
195      */

196     public void addArchive(String JavaDoc sourcePath, ArcDef newArchive, boolean saveBackup)
197         throws IOException, RrdException {
198         String JavaDoc destPath = Util.getTmpFilename();
199         addArchive(sourcePath, destPath, newArchive);
200         copyFile(destPath, sourcePath, saveBackup);
201     }
202
203     /**
204      * Creates a new RRD file with one archive removed. RRD file is created based on the
205      * existing one (the original RRD file is not modified at all). All relevant data from
206      * the original RRD file is copied to the new one.
207      * @param sourcePath path to a RRD file to import data from (will not be modified)
208      * @param destPath path to a new RRD file (will be created)
209      * @param consolFun Consolidation function of Archive which should be removed
210      * @param steps Number of steps for Archive which should be removed
211      * @throws IOException Thrown in case of I/O error
212      * @throws RrdException Thrown in case of JRobin specific error
213      */

214     public void removeArchive(String JavaDoc sourcePath, String JavaDoc destPath, String JavaDoc consolFun, int steps)
215         throws IOException, RrdException {
216         if (Util.sameFilePath(sourcePath, destPath)) {
217             throw new RrdException("Source and destination paths are the same");
218         }
219         RrdDb rrdSource = new RrdDb(sourcePath);
220         RrdDef rrdDef = rrdSource.getRrdDef();
221         rrdDef.setPath(destPath);
222         rrdDef.removeArchive(consolFun, steps);
223         RrdDb rrdDest = new RrdDb(rrdDef);
224         rrdSource.copyStateTo(rrdDest);
225         rrdSource.close();
226         rrdDest.close();
227     }
228
229     /**
230      * <p>Removes one archive from a RRD file.</p>
231      * <p>WARNING: This method is potentialy dangerous! It will modify your RRD file.
232      * It is highly recommended to preserve the original RRD file (<i>saveBackup</i>
233      * should be set to <code>true</code>). The backup file will be created in the same
234      * directory as the original one with <code>.bak</code> extension added to the
235      * original name.</p>
236      * <p>Before applying this method, be sure that the specified RRD file is not in use
237      * (not open)</p>
238      * @param sourcePath path to a RRD file to add datasource to.
239      * @param consolFun Consolidation function of Archive which should be removed
240      * @param steps Number of steps for Archive which should be removed
241      * @param saveBackup true, if backup of the original file should be created;
242      * false, otherwise
243      * @throws IOException Thrown in case of I/O error
244      * @throws RrdException Thrown in case of JRobin specific error
245      */

246     public void removeArchive(String JavaDoc sourcePath, String JavaDoc consolFun, int steps,
247                               boolean saveBackup) throws IOException, RrdException {
248         String JavaDoc destPath = Util.getTmpFilename();
249         removeArchive(sourcePath, destPath, consolFun, steps);
250         copyFile(destPath, sourcePath, saveBackup);
251     }
252
253     private static void copyFile(String JavaDoc sourcePath, String JavaDoc destPath, boolean saveBackup)
254         throws IOException {
255         File source = new File(sourcePath);
256         File dest = new File(destPath);
257         if (saveBackup) {
258             String JavaDoc backupPath = getBackupPath(destPath);
259             File backup = new File(backupPath);
260             deleteFile(backup);
261             if (!dest.renameTo(backup)) {
262                 throw new IOException("Could not create backup file " + backupPath);
263             }
264         }
265         deleteFile(dest);
266         if (!source.renameTo(dest)) {
267             throw new IOException("Could not create file " + destPath + " from " + sourcePath);
268         }
269     }
270
271     private static String JavaDoc getBackupPath(String JavaDoc destPath) {
272         String JavaDoc backupPath = destPath;
273         do {
274             backupPath += ".bak";
275         } while(new File(backupPath).exists());
276         return backupPath;
277     }
278
279     /**
280      * Sets datasource heartbeat to a new value.
281      * @param sourcePath Path to exisiting RRD file (will be updated)
282      * @param datasourceName Name of the datasource in the specified RRD file
283      * @param newHeartbeat New datasource heartbeat
284      * @throws RrdException Thrown in case of JRobin specific error
285      * @throws IOException Thrown in case of I/O error
286      */

287     public void setDsHeartbeat(String JavaDoc sourcePath, String JavaDoc datasourceName,
288                                long newHeartbeat) throws RrdException, IOException {
289         RrdDb rrd = new RrdDb(sourcePath);
290         Datasource ds = rrd.getDatasource(datasourceName);
291         ds.setHeartbeat(newHeartbeat);
292         rrd.close();
293     }
294
295     /**
296      * Sets datasource min value to a new value
297      * @param sourcePath Path to exisiting RRD file (will be updated)
298      * @param datasourceName Name of the datasource in the specified RRD file
299      * @param newMinValue New min value for the datasource
300      * @param filterArchivedValues set to <code>true</code> if archived values less than
301      * <code>newMinValue</code> should be set to NaN; set to false, otherwise.
302      * @throws RrdException Thrown in case of JRobin specific error
303      * @throws IOException Thrown in case of I/O error
304      */

305     public void setDsMinValue(String JavaDoc sourcePath, String JavaDoc datasourceName,
306                               double newMinValue, boolean filterArchivedValues) throws RrdException, IOException {
307         RrdDb rrd = new RrdDb(sourcePath);
308         Datasource ds = rrd.getDatasource(datasourceName);
309         ds.setMinValue(newMinValue, filterArchivedValues);
310         rrd.close();
311     }
312
313     /**
314      * Sets datasource max value to a new value.
315      * @param sourcePath Path to exisiting RRD file (will be updated)
316      * @param datasourceName Name of the datasource in the specified RRD file
317      * @param newMaxValue New max value for the datasource
318      * @param filterArchivedValues set to <code>true</code> if archived values greater than
319      * <code>newMaxValue</code> should be set to NaN; set to false, otherwise.
320      * @throws RrdException Thrown in case of JRobin specific error
321      * @throws IOException Thrown in case of I/O error
322      */

323     public void setDsMaxValue(String JavaDoc sourcePath, String JavaDoc datasourceName,
324                               double newMaxValue, boolean filterArchivedValues) throws RrdException, IOException {
325         RrdDb rrd = new RrdDb(sourcePath);
326         Datasource ds = rrd.getDatasource(datasourceName);
327         ds.setMaxValue(newMaxValue, filterArchivedValues);
328         rrd.close();
329     }
330
331     /**
332      * Updates valid value range for the given datasource.
333      * @param sourcePath Path to exisiting RRD file (will be updated)
334      * @param datasourceName Name of the datasource in the specified RRD file
335      * @param newMinValue New min value for the datasource
336      * @param newMaxValue New max value for the datasource
337      * @param filterArchivedValues set to <code>true</code> if archived values outside
338      * of the specified min/max range should be replaced with NaNs.
339      * @throws RrdException Thrown in case of JRobin specific error
340      * @throws IOException Thrown in case of I/O error
341      */

342     public void setDsMinMaxValue(String JavaDoc sourcePath, String JavaDoc datasourceName,
343                                  double newMinValue, double newMaxValue, boolean filterArchivedValues)
344         throws RrdException, IOException {
345         RrdDb rrd = new RrdDb(sourcePath);
346         Datasource ds = rrd.getDatasource(datasourceName);
347         ds.setMinMaxValue(newMinValue, newMaxValue, filterArchivedValues);
348         rrd.close();
349     }
350
351     /**
352      * Sets single archive's X-files factor to a new value.
353      * @param sourcePath Path to existing RRD file (will be updated)
354      * @param consolFun Consolidation function of the target archive
355      * @param steps Number of sptes of the target archive
356      * @param newXff New X-files factor for the target archive
357      * @throws RrdException Thrown in case of JRobin specific error
358      * @throws IOException Thrown in case of I/O error
359      */

360     public void setArcXff(String JavaDoc sourcePath, String JavaDoc consolFun, int steps,
361                           double newXff) throws RrdException, IOException {
362         RrdDb rrd = new RrdDb(sourcePath);
363         Archive arc = rrd.getArchive(consolFun, steps);
364         arc.setXff(newXff);
365         rrd.close();
366     }
367
368     /**
369      * Creates new RRD file based on the existing one, but with a different
370      * size (number of rows) for a single archive. The archive to be resized
371      * is identified by its consolidation function and the number of steps.
372      * @param sourcePath Path to the source RRD file (will not be modified)
373      * @param destPath Path to the new RRD file (will be created)
374      * @param consolFun Consolidation function of the archive to be resized
375      * @param numSteps Number of steps of the archive to be resized
376      * @param newRows New archive size (number of archive rows)
377      * @throws IOException Thrown in case of I/O error
378      * @throws RrdException Thrown in case of JRobin specific error
379      */

380     public void resizeArchive(String JavaDoc sourcePath, String JavaDoc destPath, String JavaDoc consolFun,
381                               int numSteps, int newRows)
382         throws IOException, RrdException {
383         if (Util.sameFilePath(sourcePath, destPath)) {
384             throw new RrdException("Source and destination paths are the same");
385         }
386         if (newRows < 2) {
387             throw new RrdException("New arcihve size must be at least 2");
388         }
389         RrdDb rrdSource = new RrdDb(sourcePath);
390         RrdDef rrdDef = rrdSource.getRrdDef();
391         ArcDef arcDef = rrdDef.findArchive(consolFun, numSteps);
392         if (arcDef.getRows() != newRows) {
393             arcDef.setRows(newRows);
394             rrdDef.setPath(destPath);
395             RrdDb rrdDest = new RrdDb(rrdDef);
396             rrdSource.copyStateTo(rrdDest);
397             rrdDest.close();
398         }
399         rrdSource.close();
400     }
401
402     /**
403      * Modifies existing RRD file, by resizing its chosen archive. The archive to be resized
404      * is identified by its consolidation function and the number of steps.
405      * @param sourcePath Path to the RRD file (will be modified)
406      * @param consolFun Consolidation function of the archive to be resized
407      * @param numSteps Number of steps of the archive to be resized
408      * @param newRows New archive size (number of archive rows)
409      * @param saveBackup true, if backup of the original file should be created;
410      * false, otherwise
411      * @throws IOException Thrown in case of I/O error
412      * @throws RrdException Thrown in case of JRobin specific error
413      */

414     public void resizeArchive(String JavaDoc sourcePath, String JavaDoc consolFun,
415                               int numSteps, int newRows, boolean saveBackup)
416         throws IOException, RrdException {
417         String JavaDoc destPath = Util.getTmpFilename();
418         resizeArchive(sourcePath, destPath, consolFun, numSteps, newRows);
419         copyFile(destPath, sourcePath, saveBackup);
420     }
421
422     private static void deleteFile(File file) throws IOException {
423         if (file.exists() && !file.delete()) {
424             throw new IOException("Could not delete file: " + file.getCanonicalPath());
425         }
426     }
427 }
428
429
Popular Tags