    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
    018package org.apache.commons.net.nntp;
    019
    020import 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
    044public final class NewGroupsOrNewsQuery
    045{
    046    private final String __date, __time;
    047    private StringBuffer __distributions;
    048    private StringBuffer __newsgroups;
    049    private final 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}