    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    }