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}