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-2005, by Sasa Markovic.
9  *
10  * Developers:    Sasa Markovic (saxon@jrobin.org)
11  *
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;
29 import java.util.Set;
30
31 /**
32  * Class to represent fetch request. For the complete explanation of all
33  * fetch parameters consult RRDTool's
34  * <a href="../../../../man/rrdfetch.html" target="man">rrdfetch man page</a>.
35  * <p/>
36  * You cannot create <code>FetchRequest</code> directly (no public constructor
37  * is provided). Use {@link RrdDb#createFetchRequest(String, long, long, long)
38  * createFetchRequest()} method of your {@link RrdDb RrdDb} object.
39  *
40  * @author <a href="mailto:saxon@jrobin.org">Sasa Markovic</a>
41  */
42 public class FetchRequest {
43     private RrdDb parentDb;
44     private String consolFun;
45     private long fetchStart;
46     private long fetchEnd;
47     private long resolution;
48     private String[] filter;
49
50     FetchRequest(RrdDb parentDb, String consolFun, long fetchStart, long fetchEnd,
51                  long resolution) throws RrdException {
52         this.parentDb = parentDb;
53         this.consolFun = consolFun;
54         this.fetchStart = fetchStart;
55         this.fetchEnd = fetchEnd;
56         this.resolution = resolution;
57         validate();
58     }
59
60     /**
61      * Sets request filter in order to fetch data only for
62      * the specified array of datasources (datasource names).
63      * If not set (or set to null), fetched data will
64      * containt values of all datasources defined in the corresponding RRD.
65      * To fetch data only from selected
66      * datasources, specify an array of datasource names as method argument.
67      *
68      * @param filter Array of datsources (datsource names) to fetch data from.
69      */
70     public void setFilter(String[] filter) {
71         this.filter = filter;
72     }
73
74     /**
75      * Sets request filter in order to fetch data only for
76      * the specified set of datasources (datasource names).
77      * If the filter is not set (or set to null), fetched data will
78      * containt values of all datasources defined in the corresponding RRD.
79      * To fetch data only from selected
80      * datasources, specify a set of datasource names as method argument.
81      *
82      * @param filter Set of datsource names to fetch data for.
83      */
84     public void setFilter(Set<String> filter) {
85         this.filter = filter.toArray(new String[0]);
86     }
87
88     /**
89      * Sets request filter in order to fetch data only for
90      * a single datasource (datasource name).
91      * If not set (or set to null), fetched data will
92      * containt values of all datasources defined in the corresponding RRD.
93      * To fetch data for a single datasource only,
94      * specify an array of datasource names as method argument.
95      *
96      * @param filter Array of datsources (datsource names) to fetch data from.
97      */
98     public void setFilter(String filter) {
99         this.filter = (filter == null) ? null : (new String[] {filter});
100     }
101
102     /**
103      * Returns request filter. See {@link #setFilter(String[]) setFilter()} for
104      * complete explanation.
105      *
106      * @return Request filter (array of datasource names), null if not set.
107      */
108     public String[] getFilter() {
109         return filter;
110     }
111
112     /**
113      * Returns consolitation function to be used during the fetch process.
114      *
115      * @return Consolidation function.
116      */
117     public String getConsolFun() {
118         return consolFun;
119     }
120
121     /**
122      * Returns starting timestamp to be used for the fetch request.
123      *
124      * @return Starting timstamp in seconds.
125      */
126     public long getFetchStart() {
127         return fetchStart;
128     }
129
130     /**
131      * Returns ending timestamp to be used for the fetch request.
132      *
133      * @return Ending timestamp in seconds.
134      */
135     public long getFetchEnd() {
136         return fetchEnd;
137     }
138
139     /**
140      * Returns fetch resolution to be used for the fetch request.
141      *
142      * @return Fetch resolution in seconds.
143      */
144     public long getResolution() {
145         return resolution;
146     }
147
148     private void validate() throws RrdException {
149         if (!ArcDef.isValidConsolFun(consolFun)) {
150             throw new RrdException("Invalid consolidation function in fetch request: " + consolFun);
151         }
152         if (fetchStart < 0) {
153             throw new RrdException("Invalid start time in fetch request: " + fetchStart);
154         }
155         if (fetchEnd < 0) {
156             throw new RrdException("Invalid end time in fetch request: " + fetchEnd);
157         }
158         if (fetchStart > fetchEnd) {
159             throw new RrdException("Invalid start/end time in fetch request: " + fetchStart +
160                     " > " + fetchEnd);
161         }
162         if (resolution <= 0) {
163             throw new RrdException("Invalid resolution in fetch request: " + resolution);
164         }
165     }
166
167     /**
168      * Dumps the content of fetch request using the syntax of RRDTool's fetch command.
169      *
170      * @return Fetch request dump.
171      */
172     public String dump() {
173         return "fetch \"" + parentDb.getRrdBackend().getPath() +
174                 "\" " + consolFun + " --start " + fetchStart + " --end " + fetchEnd +
175                 (resolution > 1 ? " --resolution " + resolution : "");
176     }
177
178     String getRrdToolCommand() {
179         return dump();
180     }
181
182     /**
183      * Returns data from the underlying RRD and puts it in a single
184      * {@link FetchData FetchData} object.
185      *
186      * @return FetchData object filled with timestamps and datasource values.
187      * @throws RrdException Thrown in case of JRobin specific error.
188      * @throws IOException  Thrown in case of I/O error.
189      */
190     public FetchData fetchData() throws RrdException, IOException {
191         return parentDb.fetchData(this);
192     }
193
194     /**
195      * Returns the underlying RrdDb object.
196      *
197      * @return RrdDb object used to create this FetchRequest object.
198      */
199     public RrdDb getParentDb() {
200         return parentDb;
201     }
202
203 }
204