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 * @see NNTPClient
042 ***/
043
044public final class NewGroupsOrNewsQuery
045{
046    private String __date, __time;
047    private StringBuffer __distributions;
048    private StringBuffer __newsgroups;
049    private boolean __isGMT;
050
051
052    /***
053     * Creates a new query using the given time as a reference point.
054     * <p>
055     * @param date  The date since which new groups or news have arrived.
056     * @param gmt   True if the date should be considered as GMT, false if not.
057     ***/
058    public NewGroupsOrNewsQuery(Calendar date, boolean gmt)
059    {
060        int num;
061        String str;
062        StringBuilder buffer;
063
064        __distributions = null;
065        __newsgroups = null;
066        __isGMT = gmt;
067
068        buffer = new StringBuilder();
069
070        // Get year
071        num = date.get(Calendar.YEAR);
072        str = Integer.toString(num);
073        num = str.length();
074
075        if (num >= 2) {
076            buffer.append(str.substring(num - 2));
077        } else {
078            buffer.append("00");
079        }
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            buffer.append('0');
088            buffer.append(str);
089        } else if (num == 2) {
090            buffer.append(str);
091        } else {
092            buffer.append("01");
093        }
094
095        // Get day
096        num = date.get(Calendar.DAY_OF_MONTH);
097        str = Integer.toString(num);
098        num = str.length();
099
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}