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