    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    }