001 /* ============================================================
002 * JRobin : Pure java implementation of RRDTool's functionality
003 * ============================================================
004 *
005 * Project Info: http://www.jrobin.org
006 * Project Lead: Sasa Markovic (saxon@jrobin.org);
007 *
008 * (C) Copyright 2003-2005, by Sasa Markovic.
009 *
010 * Developers: Sasa Markovic (saxon@jrobin.org)
011 *
012 *
013 * This library is free software; you can redistribute it and/or modify it under the terms
014 * of the GNU Lesser General Public License as published by the Free Software Foundation;
015 * either version 2.1 of the License, or (at your option) any later version.
016 *
017 * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
018 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
019 * See the GNU Lesser General Public License for more details.
020 *
021 * You should have received a copy of the GNU Lesser General Public License along with this
022 * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
023 * Boston, MA 02111-1307, USA.
024 */
025
026 package org.jrobin.core;
027
028 import java.io.IOException;
029 import java.util.Set;
030
031 /**
032 * Class to represent fetch request. For the complete explanation of all
033 * fetch parameters consult RRDTool's
034 * <a href="../../../../man/rrdfetch.html" target="man">rrdfetch man page</a>.
035 * <p/>
036 * You cannot create <code>FetchRequest</code> directly (no public constructor
037 * is provided). Use {@link RrdDb#createFetchRequest(String, long, long, long)
038 * createFetchRequest()} method of your {@link RrdDb RrdDb} object.
039 *
040 * @author <a href="mailto:saxon@jrobin.org">Sasa Markovic</a>
041 */
042 public class FetchRequest {
043 private RrdDb parentDb;
044 private String consolFun;
045 private long fetchStart;
046 private long fetchEnd;
047 private long resolution;
048 private String[] filter;
049
050 FetchRequest(RrdDb parentDb, String consolFun, long fetchStart, long fetchEnd,
051 long resolution) throws RrdException {
052 this.parentDb = parentDb;
053 this.consolFun = consolFun;
054 this.fetchStart = fetchStart;
055 this.fetchEnd = fetchEnd;
056 this.resolution = resolution;
057 validate();
058 }
059
060 /**
061 * Sets request filter in order to fetch data only for
062 * the specified array of datasources (datasource names).
063 * If not set (or set to null), fetched data will
064 * containt values of all datasources defined in the corresponding RRD.
065 * To fetch data only from selected
066 * datasources, specify an array of datasource names as method argument.
067 *
068 * @param filter Array of datsources (datsource names) to fetch data from.
069 */
070 public void setFilter(String[] filter) {
071 this.filter = filter;
072 }
073
074 /**
075 * Sets request filter in order to fetch data only for
076 * the specified set of datasources (datasource names).
077 * If the filter is not set (or set to null), fetched data will
078 * containt values of all datasources defined in the corresponding RRD.
079 * To fetch data only from selected
080 * datasources, specify a set of datasource names as method argument.
081 *
082 * @param filter Set of datsource names to fetch data for.
083 */
084 public void setFilter(Set<String> filter) {
085 this.filter = filter.toArray(new String[0]);
086 }
087
088 /**
089 * Sets request filter in order to fetch data only for
090 * a single datasource (datasource name).
091 * If not set (or set to null), fetched data will
092 * containt values of all datasources defined in the corresponding RRD.
093 * To fetch data for a single datasource only,
094 * specify an array of datasource names as method argument.
095 *
096 * @param filter Array of datsources (datsource names) to fetch data from.
097 */
098 public void setFilter(String filter) {
099 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 }