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 * @author Daniel F. Savarese
42 * @see NNTPClient
43 ***/
44
45 public final class NewGroupsOrNewsQuery
46 {
47 private String __date, __time;
48 private StringBuffer __distributions;
49 private StringBuffer __newsgroups;
50 private boolean __isGMT;
51
52
53 /***
54 * Creates a new query using the given time as a reference point.
55 * <p>
56 * @param date The date since which new groups or news have arrived.
57 * @param gmt True if the date should be considered as GMT, false if not.
58 ***/
59 public NewGroupsOrNewsQuery(Calendar date, boolean gmt)
60 {
61 int num;
62 String str;
63 StringBuffer buffer;
64
65 __distributions = null;
66 __newsgroups = null;
67 __isGMT = gmt;
68
69 buffer = new StringBuffer();
70
71 // Get year
72 num = date.get(Calendar.YEAR);
73 str = Integer.toString(num);
74 num = str.length();
75
76 if (num >= 2)
77 buffer.append(str.substring(num - 2));
78 else
79 buffer.append("00");
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 {
88 buffer.append('0');
89 buffer.append(str);
90 }
91 else if (num == 2)
92 buffer.append(str);
93 else
94 buffer.append("01");
95
96 // Get day
97 num = date.get(Calendar.DAY_OF_MONTH);
98 str = Integer.toString(num);
99 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 }