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
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 buffer.append('0');
088 buffer.append(str);
089 } else if (num == 2) {
090 buffer.append(str);
091 } else {
092 buffer.append("01");
093 }
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 buffer.append('0');
102 buffer.append(str);
103 } else if (num == 2) {
104 buffer.append(str);
105 } else {
106 buffer.append("01");
107 }
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 buffer.append('0');
120 buffer.append(str);
121 } else if (num == 2) {
122 buffer.append(str);
123 } else {
124 buffer.append("00");
125 }
126
127 // Get minutes
128 num = date.get(Calendar.MINUTE);
129 str = Integer.toString(num);
130 num = str.length();
131
132 if (num == 1) {
133 buffer.append('0');
134 buffer.append(str);
135 } else if (num == 2) {
136 buffer.append(str);
137 } else {
138 buffer.append("00");
139 }
140
141
142 // Get seconds
143 num = date.get(Calendar.SECOND);
144 str = Integer.toString(num);
145 num = str.length();
146
147 if (num == 1) {
148 buffer.append('0');
149 buffer.append(str);
150 } else if (num == 2) {
151 buffer.append(str);
152 } else {
153 buffer.append("00");
154 }
155
156 __time = buffer.toString();
157 }
158
159
160 /***
161 * Add a newsgroup to the list of newsgroups being queried. Newsgroups
162 * added this way are only meaningful to the NEWNEWS command. Newsgroup
163 * names may include the <code> * </code> wildcard, as in
164 * <code>comp.lang.* </code> or <code> comp.lang.java.* </code>. Adding
165 * at least one newsgroup is mandatory for the NEWNEWS command.
166 * <p>
167 * @param newsgroup The newsgroup to add to the list of groups to be
168 * checked for new news.
169 ***/
170 public void addNewsgroup(String newsgroup)
171 {
172 if (__newsgroups != null) {
173 __newsgroups.append(',');
174 } else {
175 __newsgroups = new StringBuffer();
176 }
177 __newsgroups.append(newsgroup);
178 }
179
180
181 /***
182 * Add a newsgroup to the list of newsgroups being queried, but indicate
183 * that group should not be checked for new news. Newsgroups
184 * added this way are only meaningful to the NEWNEWS command.
185 * Newsgroup names may include the <code> * </code> wildcard, as in
186 * <code>comp.lang.* </code> or <code> comp.lang.java.* </code>.
187 * <p>
188 * The following would create a query that searched for new news in
189 * all comp.lang.java newsgroups except for comp.lang.java.advocacy.
190 * <pre>
191 * query.addNewsgroup("comp.lang.java.*");
192 * query.omitNewsgroup("comp.lang.java.advocacy");
193 * </pre>
194 * <p>
195 * @param newsgroup The newsgroup to add to the list of groups to be
196 * checked for new news, but which should be omitted from
197 * the search for new news..
198 ***/
199 public void omitNewsgroup(String newsgroup)
200 {
201 addNewsgroup("!" + newsgroup);
202 }
203
204
205 /***
206 * Add a distribution group to the query. The distribution part of a
207 * newsgroup is the segment of the name preceding the first dot (e.g.,
208 * comp, alt, rec). Only those newsgroups matching one of the
209 * distributions or, in the case of NEWNEWS, an article in a newsgroup
210 * matching one of the distributions, will be reported as a query result.
211 * Adding distributions is purely optional.
212 * <p>
213 * @param distribution A distribution to add to the query.
214 ***/
215 public void addDistribution(String distribution)
216 {
217 if (__distributions != null) {
218 __distributions.append(',');
219 } else {
220 __distributions = new StringBuffer();
221 }
222 __distributions.append(distribution);
223 }
224
225 /***
226 * Return the NNTP query formatted date (year, month, day in the form
227 * YYMMDD.
228 * <p>
229 * @return The NNTP query formatted date.
230 ***/
231 public String getDate()
232 {
233 return __date;
234 }
235
236 /***
237 * Return the NNTP query formatted time (hour, minutes, seconds in the form
238 * HHMMSS.
239 * <p>
240 * @return The NNTP query formatted time.
241 ***/
242 public String getTime()
243 {
244 return __time;
245 }
246
247 /***
248 * Return whether or not the query date should be treated as GMT.
249 * <p>
250 * @return True if the query date is to be treated as GMT, false if not.
251 ***/
252 public boolean isGMT()
253 {
254 return __isGMT;
255 }
256
257 /***
258 * Return the comma separated list of distributions. This may be null
259 * if there are no distributions.
260 * <p>
261 * @return The list of distributions, which may be null if no distributions
262 * have been specified.
263 ***/
264 public String getDistributions()
265 {
266 return (__distributions == null ? null : __distributions.toString());
267 }
268
269 /***
270 * Return the comma separated list of newsgroups. This may be null
271 * if there are no newsgroups
272 * <p>
273 * @return The list of newsgroups, which may be null if no newsgroups
274 * have been specified.
275 ***/
276 public String getNewsgroups()
277 {
278 return (__newsgroups == null ? null : __newsgroups.toString());
279 }
280 }