View Javadoc

1   /*
2    *  File: DateIterator.java 
3    *  Copyright (c) 2004-2007  Peter Kliem (Peter.Kliem@jaret.de)
4    *  A commercial license is available, see http://www.jaret.de.
5    *
6    * All rights reserved. This program and the accompanying materials
7    * are made available under the terms of the Common Public License v1.0
8    * which accompanies this distribution, and is available at
9    * http://www.eclipse.org/legal/cpl-v10.html
10   */
11  package de.jaret.util.date.iterator;
12  
13  
14  import de.jaret.util.date.JaretDate;
15  
16  /**
17   * Interface describing an iterator for dates.
18   * 
19   * @author kliem
20   * @version $Id: DateIterator.java 883 2009-10-07 21:03:00Z kliem $
21   */
22  public interface DateIterator {
23      /**
24       * Enumeration for the different format types.
25       */
26      enum Format {
27          /**
28           * SHORT, MEDIUM, LONG: denote the format of the label.
29           */
30          SHORT, MEDIUM, LONG
31      };
32  
33      /**
34       * (re)initialize the iterator with a start and an end date.
35       * 
36       * @param startDate first date that will be returned in subsequent calls
37       * @param endDate last date that will be returned
38       */
39      void reInitialize(JaretDate startDate, JaretDate endDate);
40  
41      /**
42       * Retrieve the next date from the iterator.
43       * 
44       * @return next date
45       */
46      JaretDate getNextDate();
47  
48      /**
49       * Check whether the iterator will supply a next date.
50       * 
51       * @return true if the next call to getNextDate() will return a valid date
52       */
53      boolean hasNextDate();
54  
55      /**
56       * Retrieve the next date without modifying the iterator.
57       * 
58       * @return the next valid date or <code>null</code> if no subsequent date is available
59       */
60      JaretDate previewNextDate();
61  
62      /**
63       * Retrieve a label for a given date.
64       * 
65       * @param date the date to format
66       * @param format short, medium or long
67       * @return label
68       */
69      String getLabel(JaretDate date, Format format);
70  
71      /**
72       * Set a formatter to be used with this iterator overriding the default formatting.
73       * 
74       * @param formatter the formatter to use.
75       */
76      void setFormatter(IIteratorFormatter formatter);
77  
78      /**
79       * Return the approximate step between dates in milli seconds.
80       * 
81       * @return approximate step between iterated dates in milli seconds
82       */
83      long getApproxStepMilliSeconds();
84      
85      /**
86       * If the correct DST flag is set to true, the iterator will add/remove an hour if the
87       * DST switch time has been passed. This is false by default and you should only use it if you are knowing
88       * what you are doing. This uses the Default TimeZone for determining DST switches.
89       */
90      void setCorrectDST(boolean correctDST);
91  
92  }