001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.net.nntp;
019
020import java.util.Calendar;
021
022/***
023 * The NewGroupsOrNewsQuery class.  This is used to issue NNTP NEWGROUPS and
024 * NEWNEWS queries, implemented by
025 * {@link org.apache.commons.net.nntp.NNTPClient#listNewNewsgroups listNewNewsGroups }
026 *  and
027 * {@link org.apache.commons.net.nntp.NNTPClient#listNewNews listNewNews }
028 *  respectively.  It prevents you from having to format
029 * date, time, distribution, and newgroup arguments.
030 * <p>
031 * You might use the class as follows:
032 * <pre>
033 * query = new NewsGroupsOrNewsQuery(new GregorianCalendar(97, 11, 15), false);
034 * query.addDistribution("comp");
035 * NewsgroupInfo[] newsgroups = client.listNewgroups(query);
036 * </pre>
037 * This will retrieve the list of newsgroups starting with the comp.
038 * distribution prefix created since midnight 11/15/97.
039 * <p>
040 * <p>
041 * @author Daniel F. Savarese
042 * @see NNTPClient
043 ***/
044
045public final class NewGroupsOrNewsQuery
046{
047    private String __date, __time;
048    private StringBuffer __distributions;
049    private StringBuffer __newsgroups;
050    private boolean __isGMT;
051
052
053    /***
054     * Creates a new query using the given time as a reference point.
055     * <p>
056     * @param date  The date since which new groups or news have arrived.
057     * @param gmt   True if the date should be considered as GMT, false if not.
058     ***/
059    public NewGroupsOrNewsQuery(Calendar date, boolean gmt)
060    {
061        int num;
062        String str;
063        StringBuffer buffer;
064
065        __distributions = null;
066        __newsgroups = null;
067        __isGMT = gmt;
068
069        buffer = new StringBuffer();
070
071        // Get year
072        num = date.get(Calendar.YEAR);
073        str = Integer.toString(num);
074        num = str.length();
075
076        if (num >= 2)
077            buffer.append(str.substring(num - 2));
078        else
079            buffer.append("00");
080
081        // Get month
082        num = date.get(Calendar.MONTH) + 1;
083        str = Integer.toString(num);
084        num = str.length();
085
086        if (num == 1)
087        {
088            buffer.append('0');
089            buffer.append(str);
090        }
091        else if (num == 2)
092            buffer.append(str);
093        else
094            buffer.append("01");
095
096        // Get day
097        num = date.get(Calendar.DAY_OF_MONTH);
098        str = Integer.toString(num);
099        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}