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    
018    package org.apache.commons.net.nntp;
019    
020    import 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    
044    public 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            // Get month
081            num = date.get(Calendar.MONTH) + 1;
082            str = Integer.toString(num);
083            num = str.length();
084    
085            if (num == 1)
086            {
087                buffer.append('0');
088                buffer.append(str);
089            }
090            else if (num == 2)
091                buffer.append(str);
092            else
093                buffer.append("01");
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            {
102                buffer.append('0');
103                buffer.append(str);
104            }
105            else if (num == 2)
106                buffer.append(str);
107            else
108                buffer.append("01");
109    
110            __date = buffer.toString();
111    
112            buffer.setLength(0);
113    
114            // Get hour
115            num = date.get(Calendar.HOUR_OF_DAY);
116            str = Integer.toString(num);
117            num = str.length();
118    
119            if (num == 1)
120            {
121                buffer.append('0');
122                buffer.append(str);
123            }
124            else if (num == 2)
125                buffer.append(str);
126            else
127                buffer.append("00");
128    
129            // Get minutes
130            num = date.get(Calendar.MINUTE);
131            str = Integer.toString(num);
132            num = str.length();
133    
134            if (num == 1)
135            {
136                buffer.append('0');
137                buffer.append(str);
138            }
139            else if (num == 2)
140                buffer.append(str);
141            else
142                buffer.append("00");
143    
144    
145            // Get seconds
146            num = date.get(Calendar.SECOND);
147            str = Integer.toString(num);
148            num = str.length();
149    
150            if (num == 1)
151            {
152                buffer.append('0');
153                buffer.append(str);
154            }
155            else if (num == 2)
156                buffer.append(str);
157            else
158                buffer.append("00");
159    
160            __time = buffer.toString();
161        }
162    
163    
164        /***
165         * Add a newsgroup to the list of newsgroups being queried.  Newsgroups
166         * added this way are only meaningful to the NEWNEWS command.  Newsgroup
167         * names may include the <code> * </code> wildcard, as in
168         * <code>comp.lang.* </code> or <code> comp.lang.java.* </code>.  Adding
169         * at least one newsgroup is mandatory for the NEWNEWS command.
170         * <p>
171         * @param newsgroup  The newsgroup to add to the list of groups to be
172         *                   checked for new news.
173         ***/
174        public void addNewsgroup(String newsgroup)
175        {
176            if (__newsgroups != null)
177                __newsgroups.append(',');
178            else
179                __newsgroups = new StringBuffer();
180            __newsgroups.append(newsgroup);
181        }
182    
183    
184        /***
185         * Add a newsgroup to the list of newsgroups being queried, but indicate
186         * that group should not be checked for new news.  Newsgroups
187         * added this way are only meaningful to the NEWNEWS command.
188         * Newsgroup names may include the <code> * </code> wildcard, as in
189         * <code>comp.lang.* </code> or <code> comp.lang.java.* </code>.
190         * <p>
191         * The following would create a query that searched for new news in
192         * all comp.lang.java newsgroups except for comp.lang.java.advocacy.
193         * <pre>
194         * query.addNewsgroup("comp.lang.java.*");
195         * query.omitNewsgroup("comp.lang.java.advocacy");
196         * </pre>
197         * <p>
198         * @param newsgroup  The newsgroup to add to the list of groups to be
199         *                   checked for new news, but which should be omitted from
200         *                   the search for new news..
201         ***/
202        public void omitNewsgroup(String newsgroup)
203        {
204            addNewsgroup("!" + newsgroup);
205        }
206    
207    
208        /***
209         * Add a distribution group to the query.  The distribution part of a
210         * newsgroup is the segment of the name preceding the first dot (e.g.,
211         * comp, alt, rec).  Only those newsgroups matching one of the
212         * distributions or, in the case of NEWNEWS, an article in a newsgroup
213         * matching one of the distributions, will be reported as a query result.
214         * Adding distributions is purely optional.
215         * <p>
216         * @param distribution A distribution to add to the query.
217         ***/
218        public void addDistribution(String distribution)
219        {
220            if (__distributions != null)
221                __distributions.append(',');
222            else
223                __distributions = new StringBuffer();
224            __distributions.append(distribution);
225        }
226    
227        /***
228         * Return the NNTP query formatted date (year, month, day in the form
229         * YYMMDD.
230         * <p>
231         * @return The NNTP query formatted date.
232         ***/
233        public String getDate()
234        {
235            return __date;
236        }
237    
238        /***
239         * Return the NNTP query formatted time (hour, minutes, seconds in the form
240         * HHMMSS.
241         * <p>
242         * @return The NNTP query formatted time.
243         ***/
244        public String getTime()
245        {
246            return __time;
247        }
248    
249        /***
250         * Return whether or not the query date should be treated as GMT.
251         * <p>
252         * @return True if the query date is to be treated as GMT, false if not.
253         ***/
254        public boolean isGMT()
255        {
256            return __isGMT;
257        }
258    
259        /***
260         * Return the comma separated list of distributions.  This may be null
261         * if there are no distributions.
262         * <p>
263         * @return The list of distributions, which may be null if no distributions
264         *         have been specified.
265         ***/
266        public String getDistributions()
267        {
268            return (__distributions == null ? null : __distributions.toString());
269        }
270    
271        /***
272         * Return the comma separated list of newsgroups.  This may be null
273         * if there are no newsgroups
274         * <p>
275         * @return The list of newsgroups, which may be null if no newsgroups
276         *         have been specified.
277         ***/
278        public String getNewsgroups()
279        {
280            return (__newsgroups == null ? null : __newsgroups.toString());
281        }
282    }