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