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 * @see NNTPClient
042 ***/
043
044 public final class NewGroupsOrNewsQuery
045 {
046 private String __date, __time;
047 private StringBuffer __distributions;
048 private StringBuffer __newsgroups;
049 private boolean __isGMT;
050
051
052 /***
053 * Creates a new query using the given time as a reference point.
054 * <p>
055 * @param date The date since which new groups or news have arrived.
056 * @param gmt True if the date should be considered as GMT, false if not.
057 ***/
058 public NewGroupsOrNewsQuery(Calendar date, boolean gmt)
059 {
060 int num;
061 String str;
062 StringBuilder buffer;
063
064 __distributions = null;
065 __newsgroups = null;
066 __isGMT = gmt;
067
068 buffer = new StringBuilder();
069
070 // Get year
071 num = date.get(Calendar.YEAR);
072 str = Integer.toString(num);
073 num = str.length();
074
075 if (num >= 2)
076 buffer.append(str.substring(num - 2));
077 else
078 buffer.append("00");
079
080 // Get month
081 num = date.get(Calendar.MONTH) + 1;
082 str = Integer.toString(num);
083 num = str.length();
084
085 if (num == 1)
086 {
087 buffer.append('0');
088 buffer.append(str);
089 }
090 else if (num == 2)
091 buffer.append(str);
092 else
093 buffer.append("01");
094
095 // Get day
096 num = date.get(Calendar.DAY_OF_MONTH);
097 str = Integer.toString(num);
098 num = str.length();
099
100 if (num == 1)
101 {
102 buffer.append('0');
103 buffer.append(str);
104 }
105 else if (num == 2)
106 buffer.append(str);
107 else
108 buffer.append("01");
109
110 __date = buffer.toString();
111
112 buffer.setLength(0);
113
114 // Get hour
115 num = date.get(Calendar.HOUR_OF_DAY);
116 str = Integer.toString(num);
117 num = str.length();
118
119 if (num == 1)
120 {
121 buffer.append('0');
122 buffer.append(str);
123 }
124 else if (num == 2)
125 buffer.append(str);
126 else
127 buffer.append("00");
128
129 // Get minutes
130 num = date.get(Calendar.MINUTE);
131 str = Integer.toString(num);
132 num = str.length();
133
134 if (num == 1)
135 {
136 buffer.append('0');
137 buffer.append(str);
138 }
139 else if (num == 2)
140 buffer.append(str);
141 else
142 buffer.append("00");
143
144
145 // Get seconds
146 num = date.get(Calendar.SECOND);
147 str = Integer.toString(num);
148 num = str.length();
149
150 if (num == 1)
151 {
152 buffer.append('0');
153 buffer.append(str);
154 }
155 else if (num == 2)
156 buffer.append(str);
157 else
158 buffer.append("00");
159
160 __time = buffer.toString();
161 }
162
163
164 /***
165 * Add a newsgroup to the list of newsgroups being queried. Newsgroups
166 * added this way are only meaningful to the NEWNEWS command. Newsgroup
167 * names may include the <code> * </code> wildcard, as in
168 * <code>comp.lang.* </code> or <code> comp.lang.java.* </code>. Adding
169 * at least one newsgroup is mandatory for the NEWNEWS command.
170 * <p>
171 * @param newsgroup The newsgroup to add to the list of groups to be
172 * checked for new news.
173 ***/
174 public void addNewsgroup(String newsgroup)
175 {
176 if (__newsgroups != null)
177 __newsgroups.append(',');
178 else
179 __newsgroups = new StringBuffer();
180 __newsgroups.append(newsgroup);
181 }
182
183
184 /***
185 * Add a newsgroup to the list of newsgroups being queried, but indicate
186 * that group should not be checked for new news. Newsgroups
187 * added this way are only meaningful to the NEWNEWS command.
188 * Newsgroup names may include the <code> * </code> wildcard, as in
189 * <code>comp.lang.* </code> or <code> comp.lang.java.* </code>.
190 * <p>
191 * The following would create a query that searched for new news in
192 * all comp.lang.java newsgroups except for comp.lang.java.advocacy.
193 * <pre>
194 * query.addNewsgroup("comp.lang.java.*");
195 * query.omitNewsgroup("comp.lang.java.advocacy");
196 * </pre>
197 * <p>
198 * @param newsgroup The newsgroup to add to the list of groups to be
199 * checked for new news, but which should be omitted from
200 * the search for new news..
201 ***/
202 public void omitNewsgroup(String newsgroup)
203 {
204 addNewsgroup("!" + newsgroup);
205 }
206
207
208 /***
209 * Add a distribution group to the query. The distribution part of a
210 * newsgroup is the segment of the name preceding the first dot (e.g.,
211 * comp, alt, rec). Only those newsgroups matching one of the
212 * distributions or, in the case of NEWNEWS, an article in a newsgroup
213 * matching one of the distributions, will be reported as a query result.
214 * Adding distributions is purely optional.
215 * <p>
216 * @param distribution A distribution to add to the query.
217 ***/
218 public void addDistribution(String distribution)
219 {
220 if (__distributions != null)
221 __distributions.append(',');
222 else
223 __distributions = new StringBuffer();
224 __distributions.append(distribution);
225 }
226
227 /***
228 * Return the NNTP query formatted date (year, month, day in the form
229 * YYMMDD.
230 * <p>
231 * @return The NNTP query formatted date.
232 ***/
233 public String getDate()
234 {
235 return __date;
236 }
237
238 /***
239 * Return the NNTP query formatted time (hour, minutes, seconds in the form
240 * HHMMSS.
241 * <p>
242 * @return The NNTP query formatted time.
243 ***/
244 public String getTime()
245 {
246 return __time;
247 }
248
249 /***
250 * Return whether or not the query date should be treated as GMT.
251 * <p>
252 * @return True if the query date is to be treated as GMT, false if not.
253 ***/
254 public boolean isGMT()
255 {
256 return __isGMT;
257 }
258
259 /***
260 * Return the comma separated list of distributions. This may be null
261 * if there are no distributions.
262 * <p>
263 * @return The list of distributions, which may be null if no distributions
264 * have been specified.
265 ***/
266 public String getDistributions()
267 {
268 return (__distributions == null ? null : __distributions.toString());
269 }
270
271 /***
272 * Return the comma separated list of newsgroups. This may be null
273 * if there are no newsgroups
274 * <p>
275 * @return The list of newsgroups, which may be null if no newsgroups
276 * have been specified.
277 ***/
278 public String getNewsgroups()
279 {
280 return (__newsgroups == null ? null : __newsgroups.toString());
281 }
282 }