View Javadoc
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   *
40   * @see NNTPClient
41   ***/
42  
43  public final class NewGroupsOrNewsQuery
44  {
45      private final String __date, __time;
46      private StringBuffer __distributions;
47      private StringBuffer __newsgroups;
48      private final boolean __isGMT;
49  
50  
51      /***
52       * Creates a new query using the given time as a reference point.
53       * <p>
54       * @param date  The date since which new groups or news have arrived.
55       * @param gmt   True if the date should be considered as GMT, false if not.
56       ***/
57      public NewGroupsOrNewsQuery(Calendar date, boolean gmt)
58      {
59          int num;
60          String str;
61          StringBuilder buffer;
62  
63          __distributions = null;
64          __newsgroups = null;
65          __isGMT = gmt;
66  
67          buffer = new StringBuilder();
68  
69          // Get year
70          num = date.get(Calendar.YEAR);
71          str = Integer.toString(num);
72          num = str.length();
73  
74          if (num >= 2) {
75              buffer.append(str.substring(num - 2));
76          } else {
77              buffer.append("00");
78          }
79  
80          // Get month
81          num = date.get(Calendar.MONTH) + 1;
82          str = Integer.toString(num);
83          num = str.length();
84  
85          if (num == 1) {
86              buffer.append('0');
87              buffer.append(str);
88          } else if (num == 2) {
89              buffer.append(str);
90          } else {
91              buffer.append("01");
92          }
93  
94          // Get day
95          num = date.get(Calendar.DAY_OF_MONTH);
96          str = Integer.toString(num);
97          num = str.length();
98  
99          if (num == 1) {
100             buffer.append('0');
101             buffer.append(str);
102         } else if (num == 2) {
103             buffer.append(str);
104         } else {
105             buffer.append("01");
106         }
107 
108         __date = buffer.toString();
109 
110         buffer.setLength(0);
111 
112         // Get hour
113         num = date.get(Calendar.HOUR_OF_DAY);
114         str = Integer.toString(num);
115         num = str.length();
116 
117         if (num == 1) {
118             buffer.append('0');
119             buffer.append(str);
120         } else if (num == 2) {
121             buffer.append(str);
122         } else {
123             buffer.append("00");
124         }
125 
126         // Get minutes
127         num = date.get(Calendar.MINUTE);
128         str = Integer.toString(num);
129         num = str.length();
130 
131         if (num == 1) {
132             buffer.append('0');
133             buffer.append(str);
134         } else if (num == 2) {
135             buffer.append(str);
136         } else {
137             buffer.append("00");
138         }
139 
140 
141         // Get seconds
142         num = date.get(Calendar.SECOND);
143         str = Integer.toString(num);
144         num = str.length();
145 
146         if (num == 1) {
147             buffer.append('0');
148             buffer.append(str);
149         } else if (num == 2) {
150             buffer.append(str);
151         } else {
152             buffer.append("00");
153         }
154 
155         __time = buffer.toString();
156     }
157 
158 
159     /***
160      * Add a newsgroup to the list of newsgroups being queried.  Newsgroups
161      * added this way are only meaningful to the NEWNEWS command.  Newsgroup
162      * names may include the <code> * </code> wildcard, as in
163      * <code>comp.lang.* </code> or <code> comp.lang.java.* </code>.  Adding
164      * at least one newsgroup is mandatory for the NEWNEWS command.
165      * <p>
166      * @param newsgroup  The newsgroup to add to the list of groups to be
167      *                   checked for new news.
168      ***/
169     public void addNewsgroup(String newsgroup)
170     {
171         if (__newsgroups != null) {
172             __newsgroups.append(',');
173         } else {
174             __newsgroups = new StringBuffer();
175         }
176         __newsgroups.append(newsgroup);
177     }
178 
179 
180     /***
181      * Add a newsgroup to the list of newsgroups being queried, but indicate
182      * that group should not be checked for new news.  Newsgroups
183      * added this way are only meaningful to the NEWNEWS command.
184      * Newsgroup names may include the <code> * </code> wildcard, as in
185      * <code>comp.lang.* </code> or <code> comp.lang.java.* </code>.
186      * <p>
187      * The following would create a query that searched for new news in
188      * all comp.lang.java newsgroups except for comp.lang.java.advocacy.
189      * <pre>
190      * query.addNewsgroup("comp.lang.java.*");
191      * query.omitNewsgroup("comp.lang.java.advocacy");
192      * </pre>
193      * <p>
194      * @param newsgroup  The newsgroup to add to the list of groups to be
195      *                   checked for new news, but which should be omitted from
196      *                   the search for new news..
197      ***/
198     public void omitNewsgroup(String newsgroup)
199     {
200         addNewsgroup("!" + newsgroup);
201     }
202 
203 
204     /***
205      * Add a distribution group to the query.  The distribution part of a
206      * newsgroup is the segment of the name preceding the first dot (e.g.,
207      * comp, alt, rec).  Only those newsgroups matching one of the
208      * distributions or, in the case of NEWNEWS, an article in a newsgroup
209      * matching one of the distributions, will be reported as a query result.
210      * Adding distributions is purely optional.
211      * <p>
212      * @param distribution A distribution to add to the query.
213      ***/
214     public void addDistribution(String distribution)
215     {
216         if (__distributions != null) {
217             __distributions.append(',');
218         } else {
219             __distributions = new StringBuffer();
220         }
221         __distributions.append(distribution);
222     }
223 
224     /***
225      * Return the NNTP query formatted date (year, month, day in the form
226      * YYMMDD.
227      * <p>
228      * @return The NNTP query formatted date.
229      ***/
230     public String getDate()
231     {
232         return __date;
233     }
234 
235     /***
236      * Return the NNTP query formatted time (hour, minutes, seconds in the form
237      * HHMMSS.
238      * <p>
239      * @return The NNTP query formatted time.
240      ***/
241     public String getTime()
242     {
243         return __time;
244     }
245 
246     /***
247      * Return whether or not the query date should be treated as GMT.
248      * <p>
249      * @return True if the query date is to be treated as GMT, false if not.
250      ***/
251     public boolean isGMT()
252     {
253         return __isGMT;
254     }
255 
256     /***
257      * Return the comma separated list of distributions.  This may be null
258      * if there are no distributions.
259      * <p>
260      * @return The list of distributions, which may be null if no distributions
261      *         have been specified.
262      ***/
263     public String getDistributions()
264     {
265         return (__distributions == null ? null : __distributions.toString());
266     }
267 
268     /***
269      * Return the comma separated list of newsgroups.  This may be null
270      * if there are no newsgroups
271      * <p>
272      * @return The list of newsgroups, which may be null if no newsgroups
273      *         have been specified.
274      ***/
275     public String getNewsgroups()
276     {
277         return (__newsgroups == null ? null : __newsgroups.toString());
278     }
279 }