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     * @author Daniel F. Savarese
042     * @see NNTPClient
043     ***/
044    
045    public 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            StringBuilder buffer;
064    
065            __distributions = null;
066            __newsgroups = null;
067            __isGMT = gmt;
068    
069            buffer = new StringBuilder();
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    }