001    /*
002     * Copyright 2001-2005 The Apache Software Foundation
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     *     http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    package org.apache.commons.net.nntp;
017    
018    import java.util.Calendar;
019    
020    /***
021     * The NewGroupsOrNewsQuery class.  This is used to issue NNTP NEWGROUPS and
022     * NEWNEWS queries, implemented by
023     * {@link org.apache.commons.net.nntp.NNTPClient#listNewNewsgroups listNewNewsGroups }
024     *  and
025     * {@link org.apache.commons.net.nntp.NNTPClient#listNewNews listNewNews }
026     *  respectively.  It prevents you from having to format
027     * date, time, distribution, and newgroup arguments.
028     * <p>
029     * You might use the class as follows:
030     * <pre>
031     * query = new NewsGroupsOrNewsQuery(new GregorianCalendar(97, 11, 15), false);
032     * query.addDistribution("comp");
033     * NewsgroupInfo[] newsgroups = client.listNewgroups(query);
034     * </pre>
035     * This will retrieve the list of newsgroups starting with the comp.
036     * distribution prefix created since midnight 11/15/97.
037     * <p>
038     * <p>
039     * @author Daniel F. Savarese
040     * @see NNTPClient
041     ***/
042    
043    public final class NewGroupsOrNewsQuery
044    {
045        private String __date, __time;
046        private StringBuffer __distributions;
047        private StringBuffer __newsgroups;
048        private boolean __isGMT;
049    
050    
051        /***
052         * Creates a new query using the given time as a reference point.
053         * <p>
054         * @param date  The date since which new groups or news have arrived.
055         * @param gmt   True if the date should be considered as GMT, false if not.
056         ***/
057        public NewGroupsOrNewsQuery(Calendar date, boolean gmt)
058        {
059            int num;
060            String str;
061            StringBuffer buffer;
062    
063            __distributions = null;
064            __newsgroups = null;
065            __isGMT = gmt;
066    
067            buffer = new StringBuffer();
068    
069            // Get year
070            num = date.get(Calendar.YEAR);
071            str = Integer.toString(num);
072            num = str.length();
073    
074            if (num >= 2)
075                buffer.append(str.substring(num - 2));
076            else
077                buffer.append("00");
078    
079            // Get month
080            num = date.get(Calendar.MONTH) + 1;
081            str = Integer.toString(num);
082            num = str.length();
083    
084            if (num == 1)
085            {
086                buffer.append('0');
087                buffer.append(str);
088            }
089            else if (num == 2)
090                buffer.append(str);
091            else
092                buffer.append("01");
093    
094            // Get day
095            num = date.get(Calendar.DAY_OF_MONTH);
096            str = Integer.toString(num);
097            num = str.length();
098    
099            if (num == 1)
100            {
101                buffer.append('0');
102                buffer.append(str);
103            }
104            else if (num == 2)
105                buffer.append(str);
106            else
107                buffer.append("01");
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            {
120                buffer.append('0');
121                buffer.append(str);
122            }
123            else if (num == 2)
124                buffer.append(str);
125            else
126                buffer.append("00");
127    
128            // Get minutes
129            num = date.get(Calendar.MINUTE);
130            str = Integer.toString(num);
131            num = str.length();
132    
133            if (num == 1)
134            {
135                buffer.append('0');
136                buffer.append(str);
137            }
138            else if (num == 2)
139                buffer.append(str);
140            else
141                buffer.append("00");
142    
143    
144            // Get seconds
145            num = date.get(Calendar.SECOND);
146            str = Integer.toString(num);
147            num = str.length();
148    
149            if (num == 1)
150            {
151                buffer.append('0');
152                buffer.append(str);
153            }
154            else if (num == 2)
155                buffer.append(str);
156            else
157                buffer.append("00");
158    
159            __time = buffer.toString();
160        }
161    
162    
163        /***
164         * Add a newsgroup to the list of newsgroups being queried.  Newsgroups
165         * added this way are only meaningful to the NEWNEWS command.  Newsgroup
166         * names may include the <code> * </code> wildcard, as in
167         * <code>comp.lang.* </code> or <code> comp.lang.java.* </code>.  Adding
168         * at least one newsgroup is mandatory for the NEWNEWS command.
169         * <p>
170         * @param newsgroup  The newsgroup to add to the list of groups to be
171         *                   checked for new news.
172         ***/
173        public void addNewsgroup(String newsgroup)
174        {
175            if (__newsgroups != null)
176                __newsgroups.append(',');
177            else
178                __newsgroups = new StringBuffer();
179            __newsgroups.append(newsgroup);
180        }
181    
182    
183        /***
184         * Add a newsgroup to the list of newsgroups being queried, but indicate
185         * that group should not be checked for new news.  Newsgroups
186         * added this way are only meaningful to the NEWNEWS command.
187         * Newsgroup names may include the <code> * </code> wildcard, as in
188         * <code>comp.lang.* </code> or <code> comp.lang.java.* </code>.
189         * <p>
190         * The following would create a query that searched for new news in
191         * all comp.lang.java newsgroups except for comp.lang.java.advocacy.
192         * <pre>
193         * query.addNewsgroup("comp.lang.java.*");
194         * query.omitNewsgroup("comp.lang.java.advocacy");
195         * </pre>
196         * <p>
197         * @param newsgroup  The newsgroup to add to the list of groups to be
198         *                   checked for new news, but which should be omitted from
199         *                   the search for new news..
200         ***/
201        public void omitNewsgroup(String newsgroup)
202        {
203            addNewsgroup("!" + newsgroup);
204        }
205    
206    
207        /***
208         * Add a distribution group to the query.  The distribution part of a
209         * newsgroup is the segment of the name preceding the first dot (e.g.,
210         * comp, alt, rec).  Only those newsgroups matching one of the
211         * distributions or, in the case of NEWNEWS, an article in a newsgroup
212         * matching one of the distributions, will be reported as a query result.
213         * Adding distributions is purely optional.
214         * <p>
215         * @param distribution A distribution to add to the query.
216         ***/
217        public void addDistribution(String distribution)
218        {
219            if (__distributions != null)
220                __distributions.append(',');
221            else
222                __distributions = new StringBuffer();
223            __distributions.append(distribution);
224        }
225    
226        /***
227         * Return the NNTP query formatted date (year, month, day in the form
228         * YYMMDD.
229         * <p>
230         * @return The NNTP query formatted date.
231         ***/
232        public String getDate()
233        {
234            return __date;
235        }
236    
237        /***
238         * Return the NNTP query formatted time (hour, minutes, seconds in the form
239         * HHMMSS.
240         * <p>
241         * @return The NNTP query formatted time.
242         ***/
243        public String getTime()
244        {
245            return __time;
246        }
247    
248        /***
249         * Return whether or not the query date should be treated as GMT.
250         * <p>
251         * @return True if the query date is to be treated as GMT, false if not.
252         ***/
253        public boolean isGMT()
254        {
255            return __isGMT;
256        }
257    
258        /***
259         * Return the comma separated list of distributions.  This may be null
260         * if there are no distributions.
261         * <p>
262         * @return The list of distributions, which may be null if no distributions
263         *         have been specified.
264         ***/
265        public String getDistributions()
266        {
267            return (__distributions == null ? null : __distributions.toString());
268        }
269    
270        /***
271         * Return the comma separated list of newsgroups.  This may be null
272         * if there are no newsgroups
273         * <p>
274         * @return The list of newsgroups, which may be null if no newsgroups
275         *         have been specified.
276         ***/
277        public String getNewsgroups()
278        {
279            return (__newsgroups == null ? null : __newsgroups.toString());
280        }
281    }