RrdExportDef


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    * Developers:    Sasa Markovic (saxon@jrobin.org)
9    *                Arne Vandamme (cobralord@jrobin.org)
10   *
11   * (C) Copyright 2003, by Sasa Markovic.
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  package org.jrobin.graph;
26  
27  import java.io.*;
28  import java.util.ArrayList  ;
29  import java.util.Date  ;
30  import java.util.GregorianCalendar  ;
31  
32  import org.jrobin.core.Util;
33  import org.jrobin.core.RrdException;
34  import org.jrobin.core.XmlWriter;
35  
36  /**
37   * <p>Class used to collect information for a JRobin export.</p>
38   *
39   * <p>JRobin export works the same way as Rrdtool XPORT does, to learn
40   * more about the XPORT functionality, see RRDTool's
41   * <a HREF="../../../../man/rrdxport.html" target="man">rrdxport man page</a>.</p>
42   *
43   * @author Arne Vandamme (cobralord@jrobin.org)
44   */
45  public class RrdExportDef implements Serializable
46  {
47      // ================================================================
48      // -- Members
49      // ================================================================
50      public final static int STRICT_IMPLICIT_OFF = 0;
51      public final static int STRICT_IMPLICIT_ON  = 1;
52      public final static int STRICT_EXPLICIT_OFF = 2;
53      public final static int STRICT_EXPLICIT_ON  = 3;
54  
55      private long endTime                        = Util.getTime();                   // default time span of the last 24 hours
56      private long startTime                      = Util.getTime() - 86400L;
57      private long resolution                     = 1;                                // resolution to fetch from the RRD databases
58  
59      private int strict                          = STRICT_IMPLICIT_OFF;
60  
61      // -- Non-settable members
62      private int numSdefs                        = 0;
63      private int numDefs                         = 0;                                // number of Def datasources added
64  
65      protected FetchSourceList fetchSources      = new FetchSourceList( 10 );        // holds the list of FetchSources
66      protected ArrayList   pdefList                = new ArrayList  ( 10 );              // holds the list of Plottable datasources
67      protected ArrayList   cdefList                = new ArrayList  ( 10 );              // holds the list of Cdef datasources
68      protected ArrayList   exportList              = new ArrayList  ( 10 );              // holds the list of datasources to export
69      protected ArrayList   edefList                = new ArrayList  ( 3 );               // holds the list of export data objects
70  
71      // ================================================================
72      // -- Constructors
73      // ================================================================
74      public RrdExportDef() {
75      }
76  
77      /**
78       * Constructs a new JRobin graph object, with a specified time span to be presented on the graph.
79       * Using timestamps defined as number of seconds since the epoch.
80       *
81       * @param startTime Starting timestamp in seconds.
82       * @param endTime Ending timestamp in seconds.
83       * @throws org.jrobin.core.RrdException Thrown if invalid parameters are supplied.
84       */
85      public RrdExportDef( long startTime, long endTime ) throws RrdException
86      {
87          setTimePeriod( startTime, endTime );
88      }
89  
90      /**
91       * Constructs a new JRobin graph object, with a specified time span to be presented on the graph.
92       * Time spam defined using <code>java.util.Date</code> objects.
93       *
94       * @param start Starting time.
95       * @param end Ending time.
96       * @throws RrdException Thrown in case of invalid parameters.
97       */
98      public RrdExportDef( Date   start, Date   end) throws RrdException
99      {
100         setTimePeriod( start, end );
101     }
102 
103     /**
104      * Constructs a new JRobin graph object, with a specified time span to be presented on the graph.
105      * Time spam defined using <code>java.util.GregorianCalendar</code> objects.
106      *
107      * @param start Starting time.
108      * @param end Ending time.
109      * @throws RrdException Thrown in case of invalid parameters.
110      */
111     public RrdExportDef( GregorianCalendar   start, GregorianCalendar   end ) throws RrdException
112     {
113         setTimePeriod( start, end );
114     }
115 
116     // ================================================================
117     // -- Public methods
118     // ================================================================
119     /**
120      * Sets time span to be presented on the graph using timestamps in number of seconds.
121      * An end time of 0 means JRobin will try to use the last available update time.
122      *
123      * @param startTime Starting timestamp in seconds.
124      * @param endTime Ending timestamp in secons.
125      * @throws RrdException Thrown if invalid parameters are supplied.
126      */
127     public void setTimePeriod( long startTime, long endTime ) throws RrdException
128     {
129         if ( startTime < 0 || ( endTime != 0 && endTime <= startTime ) )
130             throw new RrdException( "Invalid start/end time: " + startTime + "/" + endTime );
131 
132         this.startTime  = startTime;
133         this.endTime    = endTime;
134     }
135 
136     /**
137      * Sets time span to be presented on the graph using <code>java.util.Date</code> objects.
138      *
139      * @param start Starting time.
140      * @param end Ending time.
141      * @throws RrdException Thrown in case of invalid parameters.
142      */
143     public void setTimePeriod( Date   start, Date   end ) throws RrdException
144     {
145         setTimePeriod( start.getTime() / 1000L, end.getTime() / 1000L );
146     }
147 
148     /**
149      * Sets time span to be presented on the graph using <code>java.util.GregorianCalendar</code> objects.
150      *
151      * @param start Starting time.
152      * @param end Ending time
153      * @throws RrdException Thrown if invalid parameters are supplied.
154      */
155     public void setTimePeriod( GregorianCalendar   start, GregorianCalendar   end ) throws RrdException
156     {
157         setTimePeriod( start.getTime(), end.getTime() );
158     }
159 
160     /**
161      * Sets the resolution with which data will be fetched from the RRD sources.
162      * JRobin will try to match the requested resolution as closely as possible.
163      *
164      * @param resolution Resolution (data step) in seconds.
165      */
166     public void setResolution( long resolution )
167     {
168         this.resolution = resolution;
169     }
170 
171     /**
172      * <p>Adds simple graph source to graph definition. Graph source <code>name</code>
173      * can be used:</p>
174      * <ul>
175      * <li>To specify sources for line, area and stack plots.</li>
176      * <li>To define complex graph sources
177      * (see {@link #datasource(java.lang.String, java.lang.String) complex graph
178      * source definition}).</li>
179      * </ul>
180      *
181      * @param name Graph source name.
182      * @param file Path to RRD file.
183      * @param dsName Data source name defined in the RRD file.
184      * @param consolFunc Consolidation function that will be used to extract data from the RRD
185      * file ("AVERAGE", "MIN", "MAX" or "LAST").
186      */
187     public void datasource( String   name, String   file, String   dsName, String   consolFunc ) throws RrdException
188     {
189         fetchSources.add( name, file, dsName, consolFunc );
190 
191         numDefs++;
192     }
193 
194     /**
195      * <p>Adds simple graph source to graph definition. Graph source <code>name</code>
196      * can be used:</p>
197      * <ul>
198      * <li>To specify sources for line, area and stack plots.</li>
199      * <li>To define complex graph sources
200      * (see {@link #datasource(java.lang.String, java.lang.String) complex graph
201      * source definition}).</li>
202      * </ul>
203      *
204      * @param name Graph source name.
205      * @param file Path to RRD file.
206      * @param dsName Data source name defined in the RRD file.
207      * @param consolFunc Consolidation function that will be used to extract data from the RRD
208      * file ("AVERAGE", "MIN", "MAX" or "LAST").
209      * @param backend Name of the RrdBackendFactory that should be used for this RrdDb.
210      */
211     public void datasource( String   name, String   file, String   dsName, String   consolFunc, String   backend ) throws RrdException
212     {
213         fetchSources.add( name, file, dsName, consolFunc, backend );
214 
215         numDefs++;
216     }
217 
218     /**
219      * <p>Clears the list of RRD datasources for this GraphDef and sets it to the FetchSourceList
220      * passed as aparameter.  This does not alter any Cdef, Sdef or Pdef definitions.  The datasources
221      * should be passed on as a FetchSourceList {@link FetchSourceList}.</p>
222      * @param datasourceList FetchSourceList of the datasources to use.
223      */
224     public void setDatasources( FetchSourceList datasourceList )
225     {
226         fetchSources    = datasourceList;
227 
228         numDefs         = fetchSources.defCount();
229     }
230 
231     /**
232      * <p>Adds complex graph source with the given name to the graph definition.
233      * Complex graph sources are evaluated using the supplied <code>rpn</code> expression.
234      *
235      * <p>Complex graph source <code>name</code> can be used:</p>
236      * <ul>
237      * <li>To specify sources for line, area and stack plots.</li>
238      * <li>To define other complex graph sources.</li>
239      * </ul>
240      *
241      * <p>JRobin supports the following RPN functions, operators and constants: +, -, *, /,
242      * %, SIN, COS, LOG, EXP, FLOOR, CEIL, ROUND, POW, ABS, SQRT, RANDOM, LT, LE, GT, GE, EQ,
243      * IF, MIN, MAX, LIMIT, DUP, EXC, POP, UN, UNKN, NOW, TIME, PI and E. JRobin does not
244      * force you to specify at least one simple graph source name as RRDTool.</p>
245      *
246      * <p>For more details on RPN see RRDTool's
247      * <a HREF="http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/manual/rrdgraph.html" target="man">rrdgraph man page</a>.</p>
248      *
249      * @param name Graph source name.
250      * @param rpn RPN expression containig comma delmited simple and complex graph
251      * source names, RPN constants, functions and operators.
252      */
253     public void datasource( String   name, String   rpn )
254     {
255         cdefList.add( new Cdef(name, rpn) );
256     }
257 
258     /**
259      * <p>Adds static graph source with the given name to the graph definition.
260      * Static graph sources are the result of a consolidation function applied
261      * to *any* other graph source that has been defined previously.</p>
262      *
263      * @param name Graph source name.
264      * @param defName Name of the datasource to calculate the value from.
265      * @param consolFunc Consolidation function to use for value calculation
266      */
267     public void datasource( String   name, String   defName, String   consolFunc ) throws RrdException
268     {
269         cdefList.add( new Sdef(name, defName, consolFunc) );
270         numSdefs++;
271     }
272 
273     /**
274      * <p>Adds a custom graph source with the given name to the graph definition.
275      * The datapoints should be made available by a class extending Plottable.</p>
276      *
277      * @param name Graph source name.
278      * @param plottable Class that extends Plottable class and is suited for graphing.
279      */
280     public void datasource( String   name, Plottable plottable )
281     {
282         pdefList.add( new Pdef(name, plottable) );
283     }
284 
285     /**
286      * <p>Adds a custom graph source with the given name to the graph definition.
287      * The datapoints should be made available by a class extending Plottable.</p>
288      *
289      * @param name Graph source name.
290      * @param plottable Class that extends Plottable class and is suited for graphing.
291      * @param index Integer referring to the datasource in the Plottable class.
292      */
293     public void datasource( String   name, Plottable plottable, int index )
294     {
295         pdefList.add( new Pdef(name, plottable, index) );
296     }
297 
298     /**
299      * <p>Adds a custom graph source with the given name to the graph definition.
300      * The datapoints should be made available by a class extending Plottable.</p>
301      *
302      * @param name Graph source name.
303      * @param plottable Class that extends Plottable class and is suited for graphing.
304      * @param sourceName String name referring to the datasource in the Plottable class.
305      */
306     public void datasource( String   name, Plottable plottable, String   sourceName )
307     {
308         pdefList.add( new Pdef(name, plottable, sourceName) );
309     }
310 
311     /**
312      * Adds a set of ExportData to the datasource list.
313      *
314      * @param edata ExportData to add.
315      */
316     public void addExportData( ExportData edata )
317     {
318         edefList.add( edata );
319     }
320 
321     /**
322      * Sets a specific datasource to be exported (if export is strict).
323      * The expor legend for this datasource will be empty. 
324      *
325      * @param name Name of the datasource
326      */
327     public void export( String   name )
328     {
329         export( name, "" );
330     }
331 
332     /**
333      * Sets a specific datasource to be exported (if export is strict).
334      * And maps an export legend to this datasource.
335      *
336      * @param name Name of the datasource
337      * @param legend Legend text
338      */
339     public void export( String   name, String   legend )
340     {
341         if ( strict == STRICT_IMPLICIT_OFF )
342             strict = STRICT_IMPLICIT_ON;
343 
344         exportList.add( new String  [] { name, legend } );
345     }
346 
347     /**
348      * <p>Sets the strict flag for the export functionality.  By default, the
349      * export is in implicit not-strict, this means that by default, all
350      * datasources specified in the RrdExportDef will be exported into
351      * the ExportData.</p>
352      *
353      * <p>If the strict flag is not specified explicitly by calling this method,
354      * the export will convert to implicitly strict as soon as a particular
355      * export() mapping is defined.  Explicit settings will override implicit.</p>
356      *
357      * <p>When explicit is off, the legend for datasources will by default be
358      * the same as the datasource name, the legend can be overridden by setting
359      * mappings using export() method.</p>
360      *
361      * <p>Strict export is the same behaviour as RRDtool's XPORT.</p>
362      *
363      * @param strict True if strict export should on, false if not.
364      */
365     public void setStrictExport( boolean strict )
366     {
367         this.strict = ( strict ? STRICT_EXPLICIT_ON : STRICT_EXPLICIT_OFF );
368     }
369 
370     /**
371      * Exports RrdExportDef (export definition) object in XML format to output stream.
372      * Generated code can be parsed with {@link RrdExportDefTemplate} class.
373      *
374      * @param stream Output stream to send XML code to.
375      */
376     public void exportXmlTemplate( OutputStream stream )
377     {
378         XmlWriter xml = new XmlWriter( stream );
379 
380         xml.startTag("rrd_export_def");
381 
382         // SPAN
383         xml.startTag("span");
384         xml.writeTag("start", getStartTime() );
385         xml.writeTag("end", getEndTime() );
386         xml.closeTag(); // span
387 
388         // OPTIONS
389         xml.startTag( "options" );
390         if ( resolution > 1 )
391             xml.writeTag( "resolution", resolution );
392         xml.writeTag( "strict_export", ( strict == STRICT_IMPLICIT_ON || strict == STRICT_EXPLICIT_ON ? "true" : "false" ) );
393         xml.closeTag();
394 
395         // DATASOURCES
396         xml.startTag("datasources");
397         // defs
398         for ( int i = 0; i < fetchSources.size(); i++ )
399             fetchSources.get( i ).exportXml(xml);
400         // cdefs and sdefs
401         for (int i = 0; i < cdefList.size(); i++ )
402         {
403             Cdef cdef = (Cdef) cdefList.get(i);
404             cdef.exportXml(xml);
405         }
406         xml.closeTag(); // datasources
407 
408         // EXPORTS
409         xml.startTag("exports");
410         String  [][] list = getExportDatasources();
411         for ( int i = 0; i < list.length; i++ )
412         {
413             xml.startTag( "export" );
414             xml.writeTag( "datasource", list[i][0] );
415             xml.writeTag( "legend", list[i][1] );
416             xml.closeTag();
417         }
418         xml.closeTag(); // exports
419 
420         xml.closeTag(); // rrd_export_def
421         xml.flush();
422 
423         xml.flush();
424     }
425 
426     /**
427      * Exports RrdExportDef (export definition) object in XML format to string.
428      * Generated code can be parsed with {@link RrdExportDefTemplate} class, see
429      * {@link RrdExportDef#exportXmlTemplate()}.
430      *
431      * @return String representing graph definition in XML format.
432      */
433     public String   getXmlTemplate()
434     {
435         return exportXmlTemplate();
436     }
437 
438     /**
439      * Exports RrdExportDef (export definition) object in XML format to string.
440      * Generated code can be parsed with {@link RrdExportDefTemplate} class.
441      *
442      * @return String representing graph definition in XML format.
443      */
444     public String   exportXmlTemplate()
445     {
446         ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
447         exportXmlTemplate(outputStream);
448         return outputStream.toString();
449     }
450 
451     /**
452      * Exports RrdExportDef (export definition) object in XML format to file.
453      * Generated code can be parsed with {@link RrdExportDefTemplate} class.
454      *
455      * @param filePath destination file
456      */
457     public void exportXmlTemplate(String   filePath) throws IOException
458     {
459         FileOutputStream outputStream = new FileOutputStream(filePath, false);
460         exportXmlTemplate(outputStream);
461         outputStream.close();
462     }
463 
464     // ================================================================
465     // -- Protected (package) methods
466     // ================================================================
467     protected long getStartTime() {
468         return startTime;
469     }
470 
471     protected long getEndTime() {
472         return endTime;
473     }
474 
475     protected long getResolution() {
476         return resolution;
477     }
478 
479     protected int getNumDefs()
480     {
481         return numDefs;
482     }
483 
484     protected Cdef[] getCdefs()
485     {
486         return (Cdef[]) cdefList.toArray( new Cdef[] {} );
487     }
488 
489     protected Pdef[] getPdefs()
490     {
491         return (Pdef[]) pdefList.toArray( new Pdef[] {} );
492     }
493 
494     protected ExportData[] getExportData()
495     {
496         return (ExportData[]) edefList.toArray( new ExportData[] {} );
497     }
498 
499     protected int getNumSdefs()
500     {
501         return numSdefs;
502     }
503 
504     protected FetchSourceList getFetchSources()
505     {
506         return fetchSources;
507     }
508 
509     protected boolean isStrict() {
510         return ( strict == STRICT_IMPLICIT_ON || strict == STRICT_EXPLICIT_ON );
511     }
512 
513     protected String  [][] getExportDatasources() {
514         return (String  [][]) exportList.toArray( new String  [0][2] );
515     }
516 }
517
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags