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   * <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 }