    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    }