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