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