001 /*
002 * Copyright 2001-2005 The Apache Software Foundation
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.apache.commons.net.nntp;
017
018 import java.util.Calendar;
019
020 /***
021 * The NewGroupsOrNewsQuery class. This is used to issue NNTP NEWGROUPS and
022 * NEWNEWS queries, implemented by
023 * {@link org.apache.commons.net.nntp.NNTPClient#listNewNewsgroups listNewNewsGroups }
024 * and
025 * {@link org.apache.commons.net.nntp.NNTPClient#listNewNews listNewNews }
026 * respectively. It prevents you from having to format
027 * date, time, distribution, and newgroup arguments.
028 * <p>
029 * You might use the class as follows:
030 * <pre>
031 * query = new NewsGroupsOrNewsQuery(new GregorianCalendar(97, 11, 15), false);
032 * query.addDistribution("comp");
033 * NewsgroupInfo[] newsgroups = client.listNewgroups(query);
034 * </pre>
035 * This will retrieve the list of newsgroups starting with the comp.
036 * distribution prefix created since midnight 11/15/97.
037 * <p>
038 * <p>
039 * @author Daniel F. Savarese
040 * @see NNTPClient
041 ***/
042
043 public final class NewGroupsOrNewsQuery
044 {
045 private String __date, __time;
046 private StringBuffer __distributions;
047 private StringBuffer __newsgroups;
048 private boolean __isGMT;
049
050
051 /***
052 * Creates a new query using the given time as a reference point.
053 * <p>
054 * @param date The date since which new groups or news have arrived.
055 * @param gmt True if the date should be considered as GMT, false if not.
056 ***/
057 public NewGroupsOrNewsQuery(Calendar date, boolean gmt)
058 {
059 int num;
060 String str;
061 StringBuffer buffer;
062
063 __distributions = null;
064 __newsgroups = null;
065 __isGMT = gmt;
066
067 buffer = new StringBuffer();
068
069 // Get year
070 num = date.get(Calendar.YEAR);
071 str = Integer.toString(num);
072 num = str.length();
073
074 if (num >= 2)
075 buffer.append(str.substring(num - 2));
076 else
077 buffer.append("00");
078
079 // Get month
080 num = date.get(Calendar.MONTH) + 1;
081 str = Integer.toString(num);
082 num = str.length();
083
084 if (num == 1)
085 {
086 buffer.append('0');
087 buffer.append(str);
088 }
089 else if (num == 2)
090 buffer.append(str);
091 else
092 buffer.append("01");
093
094 // Get day
095 num = date.get(Calendar.DAY_OF_MONTH);
096 str = Integer.toString(num);
097 num = str.length();
098
099 if (num == 1)
100 {
101 buffer.append('0');
102 buffer.append(str);
103 }
104 else if (num == 2)
105 buffer.append(str);
106 else
107 buffer.append("01");
108
109 __date = buffer.toString();
110
111 buffer.setLength(0);
112
113 // Get hour
114 num = date.get(Calendar.HOUR_OF_DAY);
115 str = Integer.toString(num);
116 num = str.length();
117
118 if (num == 1)
119 {
120 buffer.append('0');
121 buffer.append(str);
122 }
123 else if (num == 2)
124 buffer.append(str);
125 else
126 buffer.append("00");
127
128 // Get minutes
129 num = date.get(Calendar.MINUTE);
130 str = Integer.toString(num);
131 num = str.length();
132
133 if (num == 1)
134 {
135 buffer.append('0');
136 buffer.append(str);
137 }
138 else if (num == 2)
139 buffer.append(str);
140 else
141 buffer.append("00");
142
143
144 // Get seconds
145 num = date.get(Calendar.SECOND);
146 str = Integer.toString(num);
147 num = str.length();
148
149 if (num == 1)
150 {
151 buffer.append('0');
152 buffer.append(str);
153 }
154 else if (num == 2)
155 buffer.append(str);
156 else
157 buffer.append("00");
158
159 __time = buffer.toString();
160 }
161
162
163 /***
164 * Add a newsgroup to the list of newsgroups being queried. Newsgroups
165 * added this way are only meaningful to the NEWNEWS command. Newsgroup
166 * names may include the <code> * </code> wildcard, as in
167 * <code>comp.lang.* </code> or <code> comp.lang.java.* </code>. Adding
168 * at least one newsgroup is mandatory for the NEWNEWS command.
169 * <p>
170 * @param newsgroup The newsgroup to add to the list of groups to be
171 * checked for new news.
172 ***/
173 public void addNewsgroup(String newsgroup)
174 {
175 if (__newsgroups != null)
176 __newsgroups.append(',');
177 else
178 __newsgroups = new StringBuffer();
179 __newsgroups.append(newsgroup);
180 }
181
182
183 /***
184 * Add a newsgroup to the list of newsgroups being queried, but indicate
185 * that group should not be checked for new news. Newsgroups
186 * added this way are only meaningful to the NEWNEWS command.
187 * Newsgroup names may include the <code> * </code> wildcard, as in
188 * <code>comp.lang.* </code> or <code> comp.lang.java.* </code>.
189 * <p>
190 * The following would create a query that searched for new news in
191 * all comp.lang.java newsgroups except for comp.lang.java.advocacy.
192 * <pre>
193 * query.addNewsgroup("comp.lang.java.*");
194 * query.omitNewsgroup("comp.lang.java.advocacy");
195 * </pre>
196 * <p>
197 * @param newsgroup The newsgroup to add to the list of groups to be
198 * checked for new news, but which should be omitted from
199 * the search for new news..
200 ***/
201 public void omitNewsgroup(String newsgroup)
202 {
203 addNewsgroup("!" + newsgroup);
204 }
205
206
207 /***
208 * Add a distribution group to the query. The distribution part of a
209 * newsgroup is the segment of the name preceding the first dot (e.g.,
210 * comp, alt, rec). Only those newsgroups matching one of the
211 * distributions or, in the case of NEWNEWS, an article in a newsgroup
212 * matching one of the distributions, will be reported as a query result.
213 * Adding distributions is purely optional.
214 * <p>
215 * @param distribution A distribution to add to the query.
216 ***/
217 public void addDistribution(String distribution)
218 {
219 if (__distributions != null)
220 __distributions.append(',');
221 else
222 __distributions = new StringBuffer();
223 __distributions.append(distribution);
224 }
225
226 /***
227 * Return the NNTP query formatted date (year, month, day in the form
228 * YYMMDD.
229 * <p>
230 * @return The NNTP query formatted date.
231 ***/
232 public String getDate()
233 {
234 return __date;
235 }
236
237 /***
238 * Return the NNTP query formatted time (hour, minutes, seconds in the form
239 * HHMMSS.
240 * <p>
241 * @return The NNTP query formatted time.
242 ***/
243 public String getTime()
244 {
245 return __time;
246 }
247
248 /***
249 * Return whether or not the query date should be treated as GMT.
250 * <p>
251 * @return True if the query date is to be treated as GMT, false if not.
252 ***/
253 public boolean isGMT()
254 {
255 return __isGMT;
256 }
257
258 /***
259 * Return the comma separated list of distributions. This may be null
260 * if there are no distributions.
261 * <p>
262 * @return The list of distributions, which may be null if no distributions
263 * have been specified.
264 ***/
265 public String getDistributions()
266 {
267 return (__distributions == null ? null : __distributions.toString());
268 }
269
270 /***
271 * Return the comma separated list of newsgroups. This may be null
272 * if there are no newsgroups
273 * <p>
274 * @return The list of newsgroups, which may be null if no newsgroups
275 * have been specified.
276 ***/
277 public String getNewsgroups()
278 {
279 return (__newsgroups == null ? null : __newsgroups.toString());
280 }
281 }