KickJava   Java API By Example, From Geeks To Geeks.

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


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.IOException JavaDoc;
29 import java.util.StringTokenizer JavaDoc;
30
31 /**
32  * <p>Class to represent data source values for the given timestamp. Objects of this
33  * class are never created directly (no public constructor is provided). To learn more how
34  * to update RRDs, see RRDTool's
35  * <a HREF="../../../../man/rrdupdate.html" target="man">rrdupdate man page</a>.
36  *
37  * <p>To update a RRD with JRobin use the following procedure:</p>
38  *
39  * <ol>
40  * <li>Obtain empty Sample object by calling method {@link org.jrobin.core.RrdDb#createSample(long)
41  * createSample()} on respective {@link org.jrobin.core.RrdDb RrdDb} object.
42  * <li>Adjust Sample timestamp if necessary (see {@link #setTime(long) setTime()} method).
43  * <li>Supply data source values (see {@link #setValue(java.lang.String, double) setValue()}).
44  * <li>Call Sample's {@link #update() update()} method.
45  * </ol>
46  *
47  * <p>Newly created Sample object contains all data source values set to 'unknown'.
48  * You should specifify only 'known' data source values. However, if you want to specify
49  * 'unknown' values too, use <code>Double.NaN</code>.</p>
50  *
51  * @author <a HREF="mailto:saxon@jrobin.org">Sasa Markovic</a>
52  */
53 public class Sample {
54     private RrdDb parentDb;
55     private long time;
56     private String JavaDoc[] dsNames;
57     private double[] values;
58
59     Sample(RrdDb parentDb, long time) throws IOException JavaDoc {
60         this.parentDb = parentDb;
61         this.time = time;
62         this.dsNames = parentDb.getDsNames();
63         values = new double[dsNames.length];
64         clearCurrentValues();
65     }
66
67     private void clearCurrentValues() {
68         for(int i = 0; i < values.length; i++) {
69             values[i] = Double.NaN;
70         }
71     }
72
73     /**
74      * Sets single data source value in the sample.
75      * @param dsName Data source name.
76      * @param value Data source value.
77      * @throws RrdException Thrown if invalid data source name is supplied.
78      */
79     public void setValue(String JavaDoc dsName, double value) throws RrdException {
80         for(int i = 0; i < values.length; i++) {
81             if(dsNames[i].equals(dsName)) {
82                 values[i] = value;
83                 return;
84             }
85         }
86         throw new RrdException("Datasource " + dsName + " not found");
87     }
88
89     /**
90      * Sets single datasource value using data source index. Data sources are indexed by
91      * the order specified during RRD creation (zero-based).
92      * @param i Data source index
93      * @param value Data source values
94      * @throws RrdException Thrown if data source index is invalid.
95      */
96     public void setValue(int i, double value) throws RrdException {
97         if(i < values.length) {
98             values[i] = value;
99             return;
100         }
101         throw new RrdException("Sample datasource index " + i + " out of bounds");
102     }
103
104     /**
105      * Sets some (possibly all) data source values in bulk. Data source values are
106      * assigned in the order of their definition inside the RRD.
107      *
108      * @param values Data source values.
109      * @throws RrdException Thrown if the number of supplied values is zero or greater
110      * than the number of data sources defined in the RRD.
111      */
112     public void setValues(double[] values) throws RrdException {
113         if(values.length <= this.values.length) {
114             for(int i = 0; i < values.length; i++) {
115                 this.values[i] = values[i];
116             }
117         }
118         else {
119             throw new RrdException("Invalid number of values specified (found " +
120                 values.length + ", only " + dsNames.length + " allowed)");
121         }
122     }
123
124     /**
125      * Returns all current data source values in the sample.
126      * @return Data source values.
127      */
128     public double[] getValues() {
129         return values;
130     }
131
132     /**
133      * Returns sample timestamp (in seconds, without milliseconds).
134      * @return Sample timestamp.
135      */
136     public long getTime() {
137         return time;
138     }
139
140     /**
141      * Sets sample timestamp. Timestamp should be defined in seconds (without milliseconds).
142      * @param time New sample timestamp.
143      */
144     public void setTime(long time) {
145         this.time = time;
146     }
147
148     /**
149      * Returns an array of all data source names. If you try to set value for the data source
150      * name not in this array, an exception is thrown.
151      * @return Acceptable data source names.
152      */
153     public String JavaDoc[] getDsNames() {
154         return dsNames;
155     }
156
157     /**
158      * <p>Sets sample timestamp and data source values in a fashion similar to RRDTool.
159      * Argument string should be composed in the following way:
160      * <code>timestamp:value1:value2:...:valueN</code>.</p>
161      *
162      * <p>You don't have to supply all datasource values. Unspecified values will be treated
163      * as unknowns. To specify unknown value in the argument string, use letter 'U'
164      *
165      * @param timeAndValues String made by concatenating sample timestamp with corresponding
166      * data source values delmited with colons. For example:<p>
167      * <pre>
168      * 1005234132:12.2:35.6:U:24.5
169      * NOW:12.2:35.6:U:24.5
170      * </pre>
171      * 'N' stands for the current timestamp (can be replaced with 'NOW')<p>
172      * Method will throw an exception if timestamp is invalid (cannot be parsed as Long, and is not 'N'
173      * or 'NOW'). Datasource value which cannot be parsed as 'double' will be silently set to NaN.<p>
174      * @throws RrdException Thrown if too many datasource values are supplied
175      */
176     public void set(String JavaDoc timeAndValues) throws RrdException {
177         StringTokenizer JavaDoc tokenizer = new StringTokenizer JavaDoc(timeAndValues, ":", false);
178         int n = tokenizer.countTokens();
179         if(n > values.length + 1) {
180             throw new RrdException("Invalid number of values specified (found " +
181                 values.length + ", " + dsNames.length + " allowed)");
182         }
183         String JavaDoc timeToken = tokenizer.nextToken();
184         try {
185             time = Long.parseLong(timeToken);
186         }
187         catch(NumberFormatException JavaDoc nfe) {
188             if(timeToken.equalsIgnoreCase("N") || timeToken.equalsIgnoreCase("NOW")) {
189                 time = Util.getTime();
190             }
191             else {
192                 throw new RrdException("Invalid sample timestamp: " + timeToken);
193             }
194         }
195         for(int i = 0; tokenizer.hasMoreTokens(); i++) {
196             try {
197                 values[i] = Double.parseDouble(tokenizer.nextToken());
198             }
199             catch (NumberFormatException JavaDoc nfe) {
200                 // NOP, value is already set to NaN
201 }
202         }
203     }
204
205     /**
206      * Stores sample in the corresponding RRD. If the update operation succeedes,
207      * all datasource values in the sample will be set to Double.NaN (unknown) values.
208      *
209      * @throws IOException Thrown in case of I/O error.
210      * @throws RrdException Thrown in case of JRobin related error.
211      */
212     public void update() throws IOException JavaDoc, RrdException {
213         parentDb.store(this);
214         clearCurrentValues();
215     }
216
217     /**
218      * <p>Creates sample with the timestamp and data source values supplied
219      * in the argument string and stores sample in the corresponding RRD.
220      * This method is just a shortcut for:</p>
221      * <pre>
222      * set(timeAndValues);
223      * update();
224      * </pre>
225      * @param timeAndValues String made by concatenating sample timestamp with corresponding
226      * data source values delmited with colons. For example:<br>
227      * <code>1005234132:12.2:35.6:U:24.5</code><br>
228      * <code>NOW:12.2:35.6:U:24.5</code>
229      *
230      * @throws IOException Thrown in case of I/O error.
231      * @throws RrdException Thrown in case of JRobin related error.
232      */
233     public void setAndUpdate(String JavaDoc timeAndValues) throws IOException JavaDoc, RrdException {
234         set(timeAndValues);
235         update();
236     }
237
238     /**
239      * Dumps sample content using the syntax of RRDTool's update command.
240      * @return Sample dump.
241      */
242     public String JavaDoc dump() {
243         StringBuffer JavaDoc buffer = new StringBuffer JavaDoc("update \"");
244         buffer.append(parentDb.getRrdBackend().getPath() + "\" " + time);
245         for(int i = 0; i < values.length; i++) {
246             buffer.append(":");
247             buffer.append(Util.formatDouble(values[i], "U", false));
248         }
249         return buffer.toString();
250     }
251
252     String JavaDoc getRrdToolCommand() {
253         return dump();
254     }
255 }
256
Popular Tags