1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.net.nntp;
19
20 import java.util.Calendar;
21
22 /***
23 * The NewGroupsOrNewsQuery class. This is used to issue NNTP NEWGROUPS and
24 * NEWNEWS queries, implemented by
25 * {@link org.apache.commons.net.nntp.NNTPClient#listNewNewsgroups listNewNewsGroups }
26 * and
27 * {@link org.apache.commons.net.nntp.NNTPClient#listNewNews listNewNews }
28 * respectively. It prevents you from having to format
29 * date, time, distribution, and newgroup arguments.
30 * <p>
31 * You might use the class as follows:
32 * <pre>
33 * query = new NewsGroupsOrNewsQuery(new GregorianCalendar(97, 11, 15), false);
34 * query.addDistribution("comp");
35 * NewsgroupInfo[] newsgroups = client.listNewgroups(query);
36 * </pre>
37 * This will retrieve the list of newsgroups starting with the comp.
38 * distribution prefix created since midnight 11/15/97.
39 * <p>
40 * <p>
41 * @see NNTPClient
42 ***/
43
44 public final class NewGroupsOrNewsQuery
45 {
46 private final String __date, __time;
47 private StringBuffer __distributions;
48 private StringBuffer __newsgroups;
49 private final boolean __isGMT;
50
51
52 /***
53 * Creates a new query using the given time as a reference point.
54 * <p>
55 * @param date The date since which new groups or news have arrived.
56 * @param gmt True if the date should be considered as GMT, false if not.
57 ***/
58 public NewGroupsOrNewsQuery(Calendar date, boolean gmt)
59 {
60 int num;
61 String str;
62 StringBuilder buffer;
63
64 __distributions = null;
65 __newsgroups = null;
66 __isGMT = gmt;
67
68 buffer = new StringBuilder();
69
70 // Get year
71 num = date.get(Calendar.YEAR);
72 str = Integer.toString(num);
73 num = str.length();
74
75 if (num >= 2) {
76 buffer.append(str.substring(num - 2));
77 } else {
78 buffer.append("00");
79 }
80
81 // Get month
82 num = date.get(Calendar.MONTH) + 1;
83 str = Integer.toString(num);
84 num = str.length();
85
86 if (num == 1) {
87 buffer.append('0');
88 buffer.append(str);
89 } else if (num == 2) {
90 buffer.append(str);
91 } else {
92 buffer.append("01");
93 }
94
95 // Get day
96 num = date.get(Calendar.DAY_OF_MONTH);
97 str = Integer.toString(num);
98 num = str.length();
99
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 }