    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;
    021import java.util.Objects;
    022
    023/**
    024 * The NewGroupsOrNewsQuery class. This is used to issue NNTP NEWGROUPS and NEWNEWS queries, implemented by
    025 * {@link org.apache.commons.net.nntp.NNTPClient#listNewNewsgroups listNewNewsGroups } and {@link org.apache.commons.net.nntp.NNTPClient#listNewNews listNewNews
    026 * } respectively. It prevents you from having to format date, time, distribution, and newgroup arguments.
    027 * <p>
    028 * You might use the class as follows:
    029 * </p>
    030 *
    031 * <pre>
    032 * query = new NewsGroupsOrNewsQuery(new GregorianCalendar(97, 11, 15), false);
    033 * query.addDistribution("comp");
    034 * NewsgroupInfo[] newsgroups = client.listNewgroups(query);
    035 * </pre>
    036 *
    037 * This will retrieve the list of newsgroups starting with the comp. distribution prefix created since midnight 11/15/97.
    038 *
    039 * @see NNTPClient
    040 */
    041
    042public final class NewGroupsOrNewsQuery {
    043    private final String date, time;
    044    private StringBuffer distributions;
    045    private StringBuffer newsgroups;
    046    private final boolean isGMT;
    047
    048    /**
    049     * Creates a new query using the given time as a reference point.
    050     *
    051     * @param date The date since which new groups or news have arrived.
    052     * @param gmt  True if the date should be considered as GMT, false if not.
    053     */
    054    public NewGroupsOrNewsQuery(final Calendar date, final boolean gmt) {
    055        int num;
    056        String str;
    057        final StringBuilder buffer;
    058
    059        this.distributions = null;
    060        this.newsgroups = null;
    061        this.isGMT = gmt;
    062
    063        buffer = new StringBuilder();
    064
    065        // Get year
    066        num = date.get(Calendar.YEAR);
    067        str = Integer.toString(num);
    068        num = str.length();
    069
    070        if (num >= 2) {
    071            buffer.append(str.substring(num - 2));
    072        } else {
    073            buffer.append("00");
    074        }
    075
    076        // Get month
    077        num = date.get(Calendar.MONTH) + 1;
    078        str = Integer.toString(num);
    079        num = str.length();
    080
    081        if (num == 1) {
    082            buffer.append('0');
    083            buffer.append(str);
    084        } else if (num == 2) {
    085            buffer.append(str);
    086        } else {
    087            buffer.append("01");
    088        }
    089
    090        // Get day
    091        num = date.get(Calendar.DAY_OF_MONTH);
    092        str = Integer.toString(num);
    093        num = str.length();
    094
    095        if (num == 1) {
    096            buffer.append('0');
    097            buffer.append(str);
    098        } else if (num == 2) {
    099            buffer.append(str);
    100        } else {
    101            buffer.append("01");
    102        }
    103
    104        this.date = buffer.toString();
    105
    106        buffer.setLength(0);
    107
    108        // Get hour
    109        num = date.get(Calendar.HOUR_OF_DAY);
    110        str = Integer.toString(num);
    111        num = str.length();
    112
    113        if (num == 1) {
    114            buffer.append('0');
    115            buffer.append(str);
    116        } else if (num == 2) {
    117            buffer.append(str);
    118        } else {
    119            buffer.append("00");
    120        }
    121
    122        // Get minutes
    123        num = date.get(Calendar.MINUTE);
    124        str = Integer.toString(num);
    125        num = str.length();
    126
    127        if (num == 1) {
    128            buffer.append('0');
    129            buffer.append(str);
    130        } else if (num == 2) {
    131            buffer.append(str);
    132        } else {
    133            buffer.append("00");
    134        }
    135
    136        // Get seconds
    137        num = date.get(Calendar.SECOND);
    138        str = Integer.toString(num);
    139        num = str.length();
    140
    141        if (num == 1) {
    142            buffer.append('0');
    143            buffer.append(str);
    144        } else if (num == 2) {
    145            buffer.append(str);
    146        } else {
    147            buffer.append("00");
    148        }
    149
    150        this.time = buffer.toString();
    151    }
    152
    153    /**
    154     * Add a distribution group to the query. The distribution part of a newsgroup is the segment of the name preceding the first dot (e.g., comp, alt, rec).
    155     * Only those newsgroups matching one of the distributions or, in the case of NEWNEWS, an article in a newsgroup matching one of the distributions, will be
    156     * reported as a query result. Adding distributions is purely optional.
    157     *
    158     * @param distribution A distribution to add to the query.
    159     */
    160    public void addDistribution(final String distribution) {
    161        if (distributions != null) {
    162            distributions.append(',');
    163        } else {
    164            distributions = new StringBuffer();
    165        }
    166        distributions.append(distribution);
    167    }
    168
    169    /**
    170     * Add a newsgroup to the list of newsgroups being queried. Newsgroups added this way are only meaningful to the NEWNEWS command. Newsgroup names may
    171     * include the <code> * </code> wildcard, as in <code>comp.lang.* </code> or <code> comp.lang.java.* </code>. Adding at least one newsgroup is mandatory for
    172     * the NEWNEWS command.
    173     *
    174     * @param newsgroup The newsgroup to add to the list of groups to be checked for new news.
    175     */
    176    public void addNewsgroup(final String newsgroup) {
    177        if (newsgroups != null) {
    178            newsgroups.append(',');
    179        } else {
    180            newsgroups = new StringBuffer();
    181        }
    182        newsgroups.append(newsgroup);
    183    }
    184
    185    /**
    186     * Return the NNTP query formatted date (year, month, day in the form YYMMDD).
    187     *
    188     * @return The NNTP query formatted date.
    189     */
    190    public String getDate() {
    191        return date;
    192    }
    193
    194    /**
    195     * Return the comma separated list of distributions. This may be null if there are no distributions.
    196     *
    197     * @return The list of distributions, which may be null if no distributions have been specified.
    198     */
    199    public String getDistributions() {
    200        return Objects.toString(distributions, null);
    201    }
    202
    203    /**
    204     * Return the comma separated list of newsgroups. This may be null if there are no newsgroups
    205     *
    206     * @return The list of newsgroups, which may be null if no newsgroups have been specified.
    207     */
    208    public String getNewsgroups() {
    209        return Objects.toString(newsgroups, null);
    210    }
    211
    212    /**
    213     * Return the NNTP query formatted time (hour, minutes, seconds in the form HHMMSS).
    214     *
    215     * @return The NNTP query formatted time.
    216     */
    217    public String getTime() {
    218        return time;
    219    }
    220
    221    /**
    222     * Return whether or not the query date should be treated as GMT.
    223     *
    224     * @return True if the query date is to be treated as GMT, false if not.
    225     */
    226    public boolean isGMT() {
    227        return isGMT;
    228    }
    229
    230    /**
    231     * Add a newsgroup to the list of newsgroups being queried, but indicate that group should not be checked for new news. Newsgroups added this way are only
    232     * meaningful to the NEWNEWS command. Newsgroup names may include the <code> * </code> wildcard, as in <code>comp.lang.* </code> or
    233     * <code> comp.lang.java.* </code>.
    234     * <p>
    235     * The following would create a query that searched for new news in all comp.lang.java newsgroups except for comp.lang.java.advocacy.
    236     * </p>
    237     *
    238     * <pre>
    239     * query.addNewsgroup("comp.lang.java.*");
    240     * query.omitNewsgroup("comp.lang.java.advocacy");
    241     * </pre>
    242     *
    243     * @param newsgroup The newsgroup to add to the list of groups to be checked for new news, but which should be omitted from the search for new news.
    244     */
    245    public void omitNewsgroup(final String newsgroup) {
    246        addNewsgroup("!" + newsgroup);
    247    }
    248}