NewGroupsOrNewsQuery.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  18. package org.apache.commons.net.nntp;

  20. import java.util.Calendar;
  21. import java.util.Objects;

  23. /**
  24.  * The NewGroupsOrNewsQuery class. This is used to issue NNTP NEWGROUPS and NEWNEWS queries, implemented by
  25.  * {@link org.apache.commons.net.nntp.NNTPClient#listNewNewsgroups listNewNewsGroups } and {@link org.apache.commons.net.nntp.NNTPClient#listNewNews listNewNews
  26.  * } respectively. It prevents you from having to format date, time, distribution, and newgroup arguments.
  27.  * <p>
  28.  * You might use the class as follows:
  29.  * </p>
  30.  *
  31.  * <pre>
  32.  * query = new NewsGroupsOrNewsQuery(new GregorianCalendar(97, 11, 15), false);
  33.  * query.addDistribution("comp");
  34.  * NewsgroupInfo[] newsgroups = client.listNewgroups(query);
  35.  * </pre>
  36.  *
  37.  * This will retrieve the list of newsgroups starting with the comp. distribution prefix created since midnight 11/15/97.
  38.  *
  39.  * @see NNTPClient
  40.  */

  42. public final class NewGroupsOrNewsQuery {
  43.     private final String date, time;
  44.     private StringBuffer distributions;
  45.     private StringBuffer newsgroups;
  46.     private final boolean isGMT;

  48.     /**
  49.      * Creates a new query using the given time as a reference point.
  50.      *
  51.      * @param date The date since which new groups or news have arrived.
  52.      * @param gmt  True if the date should be considered as GMT, false if not.
  53.      */
  54.     public NewGroupsOrNewsQuery(final Calendar date, final boolean gmt) {
  55.         int num;
  56.         String str;
  57.         final StringBuilder buffer;

  59.         this.distributions = null;
  60.         this.newsgroups = null;
  61.         this.isGMT = gmt;

  63.         buffer = new StringBuilder();

  65.         // Get year
  66.         num = date.get(Calendar.YEAR);
  67.         str = Integer.toString(num);
  68.         num = str.length();

  70.         if (num >= 2) {
  71.             buffer.append(str.substring(num - 2));
  72.         } else {
  73.             buffer.append("00");
  74.         }

  76.         // Get month
  77.         num = date.get(Calendar.MONTH) + 1;
  78.         str = Integer.toString(num);
  79.         num = str.length();

  81.         if (num == 1) {
  82.             buffer.append('0');
  83.             buffer.append(str);
  84.         } else if (num == 2) {
  85.             buffer.append(str);
  86.         } else {
  87.             buffer.append("01");
  88.         }

  90.         // Get day
  91.         num = date.get(Calendar.DAY_OF_MONTH);
  92.         str = Integer.toString(num);
  93.         num = str.length();

  95.         if (num == 1) {
  96.             buffer.append('0');
  97.             buffer.append(str);
  98.         } else if (num == 2) {
  99.             buffer.append(str);
  100.         } else {
  101.             buffer.append("01");
  102.         }

  104.         this.date = buffer.toString();

  106.         buffer.setLength(0);

  108.         // Get hour
  109.         num = date.get(Calendar.HOUR_OF_DAY);
  110.         str = Integer.toString(num);
  111.         num = str.length();

  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.         }

  122.         // Get minutes
  123.         num = date.get(Calendar.MINUTE);
  124.         str = Integer.toString(num);
  125.         num = str.length();

  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.         }

  136.         // Get seconds
  137.         num = date.get(Calendar.SECOND);
  138.         str = Integer.toString(num);
  139.         num = str.length();

  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.         }

  150.         this.time = buffer.toString();
  151.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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. }
Created with JaCoCo 0.8.12.202403310830