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 }