View Javadoc

    1   /*
    2    * Copyright 2001-2005 The Apache Software Foundation
    3    *
    4    * Licensed under the Apache License, Version 2.0 (the "License");
    5    * you may not use this file except in compliance with the License.
    6    * You may obtain a copy of the License at
    7    *
    8    *     http://www.apache.org/licenses/LICENSE-2.0
    9    *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  package org.apache.commons.net.nntp;
    17
    18  import java.util.Calendar;
    19
    20  /****
    21   * The NewGroupsOrNewsQuery class.  This is used to issue NNTP NEWGROUPS and
    22   * NEWNEWS queries, implemented by
    23   * {@link org.apache.commons.net.nntp.NNTPClient#listNewNewsgroups listNewNewsGroups }
    24   *  and
    25   * {@link org.apache.commons.net.nntp.NNTPClient#listNewNews listNewNews }
    26   *  respectively.  It prevents you from having to format
    27   * date, time, distribution, and newgroup arguments.
    28   * <p>
    29   * You might use the class as follows:
    30   * <pre>
    31   * query = new NewsGroupsOrNewsQuery(new GregorianCalendar(97, 11, 15), false);
    32   * query.addDistribution("comp");
    33   * NewsgroupInfo[] newsgroups = client.listNewgroups(query);
    34   * </pre>
    35   * This will retrieve the list of newsgroups starting with the comp.
    36   * distribution prefix created since midnight 11/15/97.
    37   * <p>
    38   * <p>
    39   * @author Daniel F. Savarese
    40   * @see NNTPClient
    41   ***/
    42
    43  public final class NewGroupsOrNewsQuery
    44  {
    45      private String __date, __time;
    46      private StringBuffer __distributions;
    47      private StringBuffer __newsgroups;
    48      private boolean __isGMT;
    49
    50
    51      /****
    52       * Creates a new query using the given time as a reference point.
    53       * <p>
    54       * @param date  The date since which new groups or news have arrived.
    55       * @param gmt   True if the date should be considered as GMT, false if not.
    56       ***/
    57      public NewGroupsOrNewsQuery(Calendar date, boolean gmt)
    58      {
    59          int num;
    60          String str;
    61          StringBuffer buffer;
    62
    63          __distributions = null;
    64          __newsgroups = null;
    65          __isGMT = gmt;
    66
    67          buffer = new StringBuffer();
    68
    69          // Get year
    70          num = date.get(Calendar.YEAR);
    71          str = Integer.toString(num);
    72          num = str.length();
    73
    74          if (num >= 2)
    75              buffer.append(str.substring(num - 2));
    76          else
    77              buffer.append("00");
    78
    79          // Get month
    80          num = date.get(Calendar.MONTH) + 1;
    81          str = Integer.toString(num);
    82          num = str.length();
    83
    84          if (num == 1)
    85          {
    86              buffer.append('0');
    87              buffer.append(str);
    88          }
    89          else if (num == 2)
    90              buffer.append(str);
    91          else
    92              buffer.append("01");
    93
    94          // Get day
    95          num = date.get(Calendar.DAY_OF_MONTH);
    96          str = Integer.toString(num);
    97          num = str.length();
    98
    99          if (num == 1)
    100         {
    101             buffer.append('0');
    102             buffer.append(str);
    103         }
    104         else if (num == 2)
    105             buffer.append(str);
    106         else
    107             buffer.append("01");
    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         {
    120             buffer.append('0');
    121             buffer.append(str);
    122         }
    123         else if (num == 2)
    124             buffer.append(str);
    125         else
    126             buffer.append("00");
    127
    128         // Get minutes
    129         num = date.get(Calendar.MINUTE);
    130         str = Integer.toString(num);
    131         num = str.length();
    132
    133         if (num == 1)
    134         {
    135             buffer.append('0');
    136             buffer.append(str);
    137         }
    138         else if (num == 2)
    139             buffer.append(str);
    140         else
    141             buffer.append("00");
    142
    143
    144         // Get seconds
    145         num = date.get(Calendar.SECOND);
    146         str = Integer.toString(num);
    147         num = str.length();
    148
    149         if (num == 1)
    150         {
    151             buffer.append('0');
    152             buffer.append(str);
    153         }
    154         else if (num == 2)
    155             buffer.append(str);
    156         else
    157             buffer.append("00");
    158
    159         __time = buffer.toString();
    160     }
    161
    162
    163     /****
    164      * Add a newsgroup to the list of newsgroups being queried.  Newsgroups
    165      * added this way are only meaningful to the NEWNEWS command.  Newsgroup
    166      * names may include the <code> * </code> wildcard, as in
    167      * <code>comp.lang.* </code> or <code> comp.lang.java.* </code>.  Adding
    168      * at least one newsgroup is mandatory for the NEWNEWS command.
    169      * <p>
    170      * @param newsgroup  The newsgroup to add to the list of groups to be
    171      *                   checked for new news.
    172      ***/
    173     public void addNewsgroup(String newsgroup)
    174     {
    175         if (__newsgroups != null)
    176             __newsgroups.append(',');
    177         else
    178             __newsgroups = new StringBuffer();
    179         __newsgroups.append(newsgroup);
    180     }
    181
    182
    183     /****
    184      * Add a newsgroup to the list of newsgroups being queried, but indicate
    185      * that group should not be checked for new news.  Newsgroups
    186      * added this way are only meaningful to the NEWNEWS command.
    187      * Newsgroup names may include the <code> * </code> wildcard, as in
    188      * <code>comp.lang.* </code> or <code> comp.lang.java.* </code>.
    189      * <p>
    190      * The following would create a query that searched for new news in
    191      * all comp.lang.java newsgroups except for comp.lang.java.advocacy.
    192      * <pre>
    193      * query.addNewsgroup("comp.lang.java.*");
    194      * query.omitNewsgroup("comp.lang.java.advocacy");
    195      * </pre>
    196      * <p>
    197      * @param newsgroup  The newsgroup to add to the list of groups to be
    198      *                   checked for new news, but which should be omitted from
    199      *                   the search for new news..
    200      ***/
    201     public void omitNewsgroup(String newsgroup)
    202     {
    203         addNewsgroup("!" + newsgroup);
    204     }
    205
    206
    207     /****
    208      * Add a distribution group to the query.  The distribution part of a
    209      * newsgroup is the segment of the name preceding the first dot (e.g.,
    210      * comp, alt, rec).  Only those newsgroups matching one of the
    211      * distributions or, in the case of NEWNEWS, an article in a newsgroup
    212      * matching one of the distributions, will be reported as a query result.
    213      * Adding distributions is purely optional.
    214      * <p>
    215      * @param distribution A distribution to add to the query.
    216      ***/
    217     public void addDistribution(String distribution)
    218     {
    219         if (__distributions != null)
    220             __distributions.append(',');
    221         else
    222             __distributions = new StringBuffer();
    223         __distributions.append(distribution);
    224     }
    225
    226     /****
    227      * Return the NNTP query formatted date (year, month, day in the form
    228      * YYMMDD.
    229      * <p>
    230      * @return The NNTP query formatted date.
    231      ***/
    232     public String getDate()
    233     {
    234         return __date;
    235     }
    236
    237     /****
    238      * Return the NNTP query formatted time (hour, minutes, seconds in the form
    239      * HHMMSS.
    240      * <p>
    241      * @return The NNTP query formatted time.
    242      ***/
    243     public String getTime()
    244     {
    245         return __time;
    246     }
    247
    248     /****
    249      * Return whether or not the query date should be treated as GMT.
    250      * <p>
    251      * @return True if the query date is to be treated as GMT, false if not.
    252      ***/
    253     public boolean isGMT()
    254     {
    255         return __isGMT;
    256     }
    257
    258     /****
    259      * Return the comma separated list of distributions.  This may be null
    260      * if there are no distributions.
    261      * <p>
    262      * @return The list of distributions, which may be null if no distributions
    263      *         have been specified.
    264      ***/
    265     public String getDistributions()
    266     {
    267         return (__distributions == null ? null : __distributions.toString());
    268     }
    269
    270     /****
    271      * Return the comma separated list of newsgroups.  This may be null
    272      * if there are no newsgroups
    273      * <p>
    274      * @return The list of newsgroups, which may be null if no newsgroups
    275      *         have been specified.
    276      ***/
    277     public String getNewsgroups()
    278     {
    279         return (__newsgroups == null ? null : __newsgroups.toString());
    280     }
    281 }